@agent-native/core 0.108.0 → 0.109.1

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

@@ -0,0 +1,166 @@
+import { defineAction } from "@agent-native/core";
+import {
+  callMcpTool,
+  listVisibleMcpTools,
+  type AppMcpTool,
+} from "@agent-native/core/mcp-client";
+import { z } from "zod";
+
+import { readGongNativeInsightsPolicy } from "../server/lib/gong-native-policy";
+
+const GONG_NATIVE_OPERATIONS = [
+  "ask_account",
+  "ask_deal",
+  "generate_brief",
+] as const;
+
+type GongNativeOperation = (typeof GONG_NATIVE_OPERATIONS)[number];
+
+function operationName(value: string): string {
+  return value.trim().toLowerCase().replace(/-/g, "_");
+}
+
+function gongNativeTools(tools: AppMcpTool[]): AppMcpTool[] {
+  const names = new Set<string>(GONG_NATIVE_OPERATIONS);
+  return tools.filter((tool) => names.has(operationName(tool.name)));
+}
+
+function selectTool(
+  tools: AppMcpTool[],
+  operation: GongNativeOperation,
+): AppMcpTool | null {
+  const matches = tools.filter(
+    (tool) => operationName(tool.name) === operation,
+  );
+  if (matches.length === 1) return matches[0];
+  const gongNamed = matches.filter((tool) => /gong/i.test(tool.serverId));
+  return gongNamed.length === 1 ? gongNamed[0] : null;
+}
+
+export default defineAction({
+  description:
+    "Use Gong's official MCP semantic operations for one bounded qualitative synthesis request. Omit operation to inspect the connected schemas without spending Gong credits. Paid calls fail closed unless configure-gong-native-insights has enabled them for this workspace and this invocation sets allowCreditRequest=true. With operation, pass one consolidated arguments object; each invocation independently consumes Gong credits. Use this only for themes, risks, summaries, and deck narrative. For transcripts, quotes, counts, source records, or absence/exhaustive claims use gong-calls or the provider corpus evidence path instead.",
+  schema: z.object({
+    operation: z
+      .enum(GONG_NATIVE_OPERATIONS)
+      .optional()
+      .describe(
+        "Official Gong MCP operation. Omit to list the currently connected operation schemas without calling Gong AI.",
+      ),
+    allowCreditRequest: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Explicitly authorize this one Gong semantic request. Leave false while inspecting schemas or when the workspace should not spend Gong credits.",
+      ),
+    arguments: z
+      .record(z.string(), z.unknown())
+      .default({})
+      .describe(
+        "Arguments passed unchanged to the connected Gong MCP operation. Consolidate related questions into one request and narrow the entity/date scope.",
+      ),
+  }),
+  readOnly: true,
+  parallelSafe: true,
+  needsApproval: ({ operation, allowCreditRequest }) =>
+    Boolean(operation && allowCreditRequest),
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  http: false,
+  run: async ({ operation, allowCreditRequest, arguments: args }) => {
+    const tools = gongNativeTools(await listVisibleMcpTools());
+    if (!operation) {
+      return {
+        connected: tools.length > 0,
+        creditRequests: 0,
+        creditUnit: "request",
+        evidenceMode: "provider-synthesis",
+        rawEvidenceAvailable: false,
+        operations: tools.map((tool) => ({
+          operation: operationName(tool.name),
+          serverId: tool.serverId,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        })),
+        evidenceFallbackAction: "gong-calls",
+        guidance:
+          tools.length > 0
+            ? "Choose one operation and make one consolidated, narrowly scoped request. Inspecting this catalog did not call Gong AI or consume a Gong credit request."
+            : "No official Gong semantic MCP operations are connected in this request scope. Use gong-calls for bounded evidence, or connect Gong MCP before using the synthesis path.",
+      };
+    }
+
+    if (!allowCreditRequest) {
+      return {
+        connected: tools.length > 0,
+        operation,
+        blocked: true,
+        creditRequests: 0,
+        creditUnit: "request",
+        evidenceMode: "provider-synthesis",
+        rawEvidenceAvailable: false,
+        evidenceFallbackAction: "gong-calls",
+        guidance:
+          "This Gong semantic request was not sent. Set allowCreditRequest=true only after choosing one consolidated, narrowly scoped request; use gong-calls for evidence retrieval without Gong AI synthesis.",
+      };
+    }
+
+    const policy = await readGongNativeInsightsPolicy();
+    if (!policy.enabled) {
+      return {
+        connected: tools.length > 0,
+        operation,
+        blocked: true,
+        blockedBy: "workspace-policy",
+        policy,
+        creditRequests: 0,
+        creditUnit: "request",
+        evidenceMode: "provider-synthesis",
+        rawEvidenceAvailable: false,
+        evidenceFallbackAction: "gong-calls",
+        guidance:
+          "This Gong semantic request was not sent because paid native insights are disabled for this workspace. An authorized user can enable them with configure-gong-native-insights; use gong-calls for evidence retrieval in the meantime.",
+      };
+    }
+
+    const tool = selectTool(tools, operation);
+    if (!tool) {
+      return {
+        connected: tools.length > 0,
+        operation,
+        creditRequests: 0,
+        creditUnit: "request",
+        evidenceMode: "provider-synthesis",
+        rawEvidenceAvailable: false,
+        error:
+          tools.length === 0
+            ? "No official Gong semantic MCP operations are connected in this request scope."
+            : `The ${operation} operation is missing or ambiguous across connected MCP servers.`,
+        availableOperations: tools.map((candidate) => ({
+          operation: operationName(candidate.name),
+          serverId: candidate.serverId,
+        })),
+        evidenceFallbackAction: "gong-calls",
+      };
+    }
+
+    const startedAt = Date.now();
+    const result = await callMcpTool(tool.serverId, tool.name, args);
+    return {
+      connected: true,
+      source: "gong-native-mcp",
+      operation,
+      creditRequests: 1,
+      creditUnit: "request",
+      durationMs: Date.now() - startedAt,
+      evidenceMode: "provider-synthesis",
+      synthesisOnly: true,
+      rawEvidenceAvailable: false,
+      coverageComplete: false,
+      coverageUnknown: true,
+      result,
+      evidenceFallbackAction: "gong-calls",
+      guidance:
+        "Treat this as Gong-generated qualitative synthesis, not transcript evidence. Do not use it for verbatim quotes, exact counts, source-record claims, or proof of absence; route those to gong-calls or the provider corpus evidence path.",
+    };
+  },
+});

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

@@ -2,12 +2,13 @@ import { defineAction } from "@agent-native/core";
 import { z } from "zod";
 
 import {
-  getAllDeals,
   getDealPipelines,
   getDealOwners,
   getVisiblePipelines,
   searchHubSpotObjects,
   type Deal,
+  type HubSpotSearchFilter,
+  type HubSpotSearchFilterGroup,
   type Pipeline,
 } from "../server/lib/hubspot";
 
@@ -22,6 +23,7 @@ const StringListSchema = z.preprocess((value) => {
 
 const TextMatchSchema = z.enum(["token", "contains", "exact"]);
 const ClosedStatusSchema = z.enum(["any", "won", "lost", "closed", "open"]);
+const HUBSPOT_SEARCH_RESULT_CAP = 10_000;
 
 function stageLookups(pipelines: Pipeline[]) {
   const stageLabels: Record<string, string> = {};
@@ -261,6 +263,102 @@ function hasStructuredFilters(filters: ReturnType<typeof buildFilterSummary>) {
   ].some((key) => key in filters);
 }
 
+function buildHubSpotDealFilters(options: {
+  visiblePipelines: Pipeline[];
+  owners: Record<string, string>;
+  owner?: string;
+  product?: string;
+  productMatch: TextMatchMode;
+  pipeline?: string;
+  closedStatus: ClosedStatus;
+  closedDateFromMs: number | null;
+  closedDateToMs: number | null;
+}): { filterGroups: HubSpotSearchFilterGroup[]; impossible: boolean } {
+  let pipelineIds = options.visiblePipelines.map((pipeline) => pipeline.id);
+  if (options.pipeline) {
+    const needle = options.pipeline.toLowerCase();
+    pipelineIds = options.visiblePipelines
+      .filter(
+        (pipeline) =>
+          pipeline.id.toLowerCase().includes(needle) ||
+          pipeline.label.toLowerCase().includes(needle),
+      )
+      .map((pipeline) => pipeline.id);
+  }
+  if (!pipelineIds.length) return { filterGroups: [], impossible: true };
+
+  const filters: HubSpotSearchFilter[] = [
+    { propertyName: "pipeline", operator: "IN", values: pipelineIds },
+  ];
+
+  if (options.owner) {
+    const needle = options.owner.toLowerCase();
+    const ownerIds = Object.entries(options.owners)
+      .filter(
+        ([id, name]) =>
+          id.toLowerCase() === needle || name.toLowerCase() === needle,
+      )
+      .map(([id]) => id);
+    if (!ownerIds.length) return { filterGroups: [], impossible: true };
+    filters.push({
+      propertyName: "hubspot_owner_id",
+      operator: "IN",
+      values: ownerIds,
+    });
+  }
+
+  if (options.product) {
+    filters.push({
+      propertyName: "products",
+      operator: options.productMatch === "exact" ? "EQ" : "CONTAINS_TOKEN",
+      value:
+        options.productMatch === "contains"
+          ? `*${options.product}*`
+          : options.product,
+    });
+  }
+
+  if (options.closedStatus !== "any") {
+    const lookups = stageLookups(options.visiblePipelines);
+    const wonIds = [...lookups.wonStageIds];
+    const lostIds = [...lookups.lostStageIds];
+    const closedIds = [...new Set([...wonIds, ...lostIds])];
+    const values =
+      options.closedStatus === "won"
+        ? wonIds
+        : options.closedStatus === "lost"
+          ? lostIds
+          : closedIds;
+    if (!values.length && options.closedStatus !== "open") {
+      return { filterGroups: [], impossible: true };
+    }
+    if (closedIds.length) {
+      filters.push({
+        propertyName: "dealstage",
+        operator: options.closedStatus === "open" ? "NOT_IN" : "IN",
+        values: options.closedStatus === "open" ? closedIds : values,
+      });
+    }
+  }
+
+  if (options.closedDateFromMs != null) {
+    filters.push({
+      propertyName: "closedate",
+      operator: "GTE",
+      value: String(options.closedDateFromMs),
+    });
+  }
+  if (options.closedDateToMs != null) {
+    filters.push({
+      propertyName: "closedate",
+      operator: "LTE",
+      value: String(options.closedDateToMs),
+    });
+  }
+
+  return { filterGroups: [{ filters }], impossible: false };
+}
+
 function buildGuidance(options: {
   query: string | undefined;
   structuredFilters: boolean;
@@ -270,6 +368,7 @@ function buildGuidance(options: {
   returned: number;
   offset: number;
   limit: number;
+  searchCoverageLimited: boolean;
 }) {
   const guidance: string[] = [];
 
@@ -278,7 +377,9 @@ function buildGuidance(options: {
       "Used HubSpot full-text deal search for the query. Treat query matches as broad keyword/account matches, not proof that a specific property equals the query.",
     );
   } else {
-    guidance.push("Loaded visible HubSpot deals before local filtering.");
+    guidance.push(
+      "Used HubSpot CRM search with provider-side pipeline and structured filters; the action did not scan the full deal corpus locally.",
+    );
   }
 
   if (options.structuredFilters) {
@@ -292,11 +393,26 @@ function buildGuidance(options: {
   }
 
   if (options.truncated) {
-    const more = options.hasMore
-      ? `Fetch the next page with offset ${options.offset + options.returned}.`
-      : "This is the last page of the cohort.";
+    if (options.query) {
+      const more = options.hasMore
+        ? "Fetch the next page with the returned nextAfter cursor."
+        : "This query has no usable next cursor.";
+      guidance.push(
+        `Returned ${options.returned} of ${options.total} matching deals (limit ${options.limit}). This is a partial slice — do NOT treat it as the full cohort. ${more} Narrow the query or use provider-api-request with provider = hubspot and stageAs for a projected corpus.`,
+      );
+    } else {
+      const more = options.hasMore
+        ? `Fetch the next page with offset ${options.offset + options.returned}.`
+        : "This is the last page of the cohort.";
+      guidance.push(
+        `Returned ${options.returned} of ${options.total} matching deals (limit ${options.limit}, offset ${options.offset}). This is a partial slice — do NOT treat it as the full cohort. Use total for counts/aggregates. ${more} Narrow the filters or, for exhaustive cohort analysis, use provider-api-request with provider = hubspot and stageAs.`,
+      );
+    }
+  }
+
+  if (options.searchCoverageLimited) {
     guidance.push(
-      `Returned ${options.returned} of ${options.total} matching deals (limit ${options.limit}, offset ${options.offset}). This is a partial slice — do NOT treat it as the full cohort. Use total for counts/aggregates. ${more} Narrow the filters or, for exhaustive cohort analysis, use provider-api-request with provider = hubspot and stageAs.`,
+      "HubSpot search cannot page beyond 10,000 results for one query, so coverage is incomplete even if this page has no next cursor. Split the cohort into non-overlapping closed-date windows and combine the projected results; do not report an exhaustive count or absence claim from this query alone.",
     );
   }
 
@@ -308,7 +424,7 @@ export default defineAction({
   // reusable across continuation retries (no re-fetch on resume).
   readOnly: true,
   description:
-    "Get HubSpot deals with normalized stage, pipeline, owner, forecast, and NBM fields. This is a bounded deal analytics shortcut, not the full HubSpot capability surface. Use query for a specific customer/deal/account deep dive. For cohorts like products field = Publish, closed-won, pipeline = New Business, or close date in a range, use the structured product, pipeline, closedStatus, closedDateFrom, and closedDateTo filters instead of query when the answer is the deal list itself. If the cohort feeds a cross-source join, transcript/message/ticket search, exhaustive absence check, or downstream code/corpus workflow, prefer provider-api-catalog/provider-api-request with provider = hubspot and stageAs so the cohort is available as a staged dataset. Both paths are bounded: at most limit deals are returned (default 25, max 100). The structured-filter path returns total as the true matched count and a truncated flag; page with offset (or narrow filters) instead of expecting the whole cohort in one call, since a full enriched cohort can be several MB and overruns extension and context budgets. For non-deal CRM records use hubspot-records; for arbitrary HubSpot endpoints, filters, associations, batch APIs, or payloads use provider-api-catalog/provider-api-docs/provider-api-request with provider = hubspot.",
+    "Get HubSpot deals with normalized stage, pipeline, owner, forecast, and NBM fields. This is a bounded deal analytics shortcut, not the full HubSpot capability surface. Use query for a specific customer/deal/account deep dive. For cohorts like products field = Publish, closed-won, pipeline = New Business, or close date in a range, use the structured product, pipeline, closedStatus, closedDateFrom, and closedDateTo filters instead of query when the answer is the deal list itself. If the cohort feeds a cross-source join, transcript/message/ticket search, exhaustive absence check, or downstream code/corpus workflow, prefer provider-api-catalog/provider-api-request with provider = hubspot and stageAs so the cohort is available as a staged dataset. Both paths are bounded: at most limit deals are returned (default 25, max 200). HubSpot search returns a total but no server-side aggregates and cannot page past 10,000 matches for one query; compute metrics on filtered/projected rows, and split larger cohorts into non-overlapping date windows while reporting coverage. The structured-filter path returns total as the matched count and a truncated flag; page with offset (or narrow filters) instead of expecting the whole cohort in one call, since a full enriched cohort can be several MB and overruns extension and context budgets. For non-deal CRM records use hubspot-records; for arbitrary HubSpot endpoints, filters, associations, batch APIs, or payloads use provider-api-catalog/provider-api-docs/provider-api-request with provider = hubspot.",
   schema: z.object({
     properties: StringListSchema.describe(
       "Optional comma-separated extra HubSpot deal property names to include.",
@@ -357,7 +473,7 @@ export default defineAction({
       .number()
       .int()
       .min(1)
-      .max(100)
+      .max(200)
       .default(25)
       .describe(
         "Maximum deals to return. Applies to BOTH full-text query results and structured-filter cohorts. The structured-filter path returns at most this many enriched deals (use total for the true matched count and offset to page).",
@@ -366,6 +482,7 @@ export default defineAction({
       .number()
       .int()
       .min(0)
+      .max(HUBSPOT_SEARCH_RESULT_CAP - 1)
       .default(0)
       .describe(
         "Number of structured-filter results to skip before returning limit deals. Use for paging through a large cohort; ignored when query is provided.",
@@ -408,27 +525,57 @@ export default defineAction({
       );
     }
 
-    const [dealResult, allPipelines, owners] = await Promise.all([
-      trimmedQuery
-        ? searchHubSpotObjects({
-            objectType: "deals",
-            query: trimmedQuery,
-            properties,
-            limit,
-            after,
-          })
-        : getAllDeals(properties),
+    const [allPipelines, owners] = await Promise.all([
       getDealPipelines(),
       getDealOwners(),
     ]);
-
     const visiblePipelines = getVisiblePipelines(allPipelines);
     const visibleIds = new Set(visiblePipelines.map((p) => p.id));
     const lookups = stageLookups(visiblePipelines);
     const ownerFilter = owner?.trim().toLowerCase();
-    const rawDeals = Array.isArray(dealResult)
-      ? dealResult
-      : dealResult.records.map(recordToDeal);
+    const providerFilters = buildHubSpotDealFilters({
+      visiblePipelines,
+      owners,
+      owner: trimmedOwner,
+      product: trimmedProduct,
+      productMatch,
+      pipeline: trimmedPipeline,
+      closedStatus,
+      closedDateFromMs: fromMs,
+      closedDateToMs: toMs,
+    });
+    const requestedAfter = trimmedQuery ? after : String(offset);
+    const numericAfter = requestedAfter
+      ? Number.parseInt(requestedAfter, 10)
+      : 0;
+    if (
+      requestedAfter &&
+      Number.isFinite(numericAfter) &&
+      numericAfter >= HUBSPOT_SEARCH_RESULT_CAP
+    ) {
+      throw new Error(
+        "HubSpot search cannot page beyond 10,000 results. Split the query into non-overlapping closed-date windows and report the combined coverage.",
+      );
+    }
+    const requestLimit = Number.isFinite(numericAfter)
+      ? Math.min(limit, HUBSPOT_SEARCH_RESULT_CAP - numericAfter)
+      : limit;
+    const dealResult = providerFilters.impossible
+      ? {
+          records: [],
+          total: 0,
+          nextAfter: null,
+          properties: properties ?? [],
+        }
+      : await searchHubSpotObjects({
+          objectType: "deals",
+          query: trimmedQuery,
+          filterGroups: providerFilters.filterGroups,
+          properties,
+          limit: requestLimit,
+          after: requestedAfter,
+        });
+    const rawDeals = dealResult.records.map(recordToDeal);
     const filters = buildFilterSummary({
       owner: trimmedOwner,
       query: trimmedQuery,
@@ -461,24 +608,21 @@ export default defineAction({
         return matchesDateRange(deal, fromMs, toMs);
       });
 
-    // The full-text query path is already bounded by HubSpot's own `limit`.
-    // EVERY non-query call (with or without structured filters) scans the whole
-    // visible deal set, so bound the returned cohort here. This is deliberately
-    // NOT gated on `structuredFilters`: the unfiltered `hubspot-deals({})` call
-    // is the LARGEST payload of all (every visible deal), so it must be bounded
-    // too — a full enriched cohort can be multiple MB, which overruns the
-    // extension iframe bridge and the agent context. We
-    // keep `total` as the true matched count and signal partial slices via
-    // `truncated` so callers never mistake a page for the full cohort.
-    // `truncated` means "this response is only part of the cohort" (returned <
-    // total) and stays true on the LAST page of a paginated read too; pagination
-    // (is there a next page) is reported separately via `hasMore` / `nextOffset`.
-    const matchedTotal = matchedDeals.length;
-    const deals = trimmedQuery
-      ? matchedDeals
-      : matchedDeals.slice(offset, offset + limit);
-    const truncated = !trimmedQuery && deals.length < matchedTotal;
-    const hasMore = !trimmedQuery && offset + deals.length < matchedTotal;
+    // HubSpot applies the cohort filters and pagination before returning the
+    // page. Keep the local checks as a compatibility/correctness guard, but do
+    // not scan and slice the full deal corpus in this action.
+    const matchedTotal = dealResult.total;
+    const deals = matchedDeals;
+    const searchCoverageLimited = matchedTotal >= HUBSPOT_SEARCH_RESULT_CAP;
+    const nextCursor = dealResult.nextAfter
+      ? Number.parseInt(dealResult.nextAfter, 10)
+      : null;
+    const nextCursorWithinCap =
+      nextCursor == null ||
+      !Number.isFinite(nextCursor) ||
+      nextCursor < HUBSPOT_SEARCH_RESULT_CAP;
+    const hasMore = dealResult.nextAfter != null && nextCursorWithinCap;
+    const truncated = deals.length < matchedTotal || searchCoverageLimited;
 
     return {
       deals,
@@ -488,7 +632,10 @@ export default defineAction({
       count: deals.length,
       query: trimmedQuery || null,
       filters,
-      nextAfter: Array.isArray(dealResult) ? null : dealResult.nextAfter,
+      nextAfter: hasMore ? dealResult.nextAfter : null,
+      searchResultCap: HUBSPOT_SEARCH_RESULT_CAP,
+      searchCoverageComplete: !searchCoverageLimited,
+      searchCoverageLimited,
       ...(trimmedQuery
         ? {}
         : {
@@ -507,12 +654,9 @@ export default defineAction({
         returned: deals.length,
         offset,
         limit,
+        searchCoverageLimited,
       }),
-      ...(Array.isArray(dealResult)
-        ? {}
-        : {
-            searchedProperties: dealResult.properties,
-          }),
+      searchedProperties: dealResult.properties,
     };
   },
 });

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

@@ -0,0 +1,123 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { executeProviderApiRequest } from "../server/lib/provider-api";
+
+const DAY_MS = 24 * 60 * 60 * 1_000;
+
+export default defineAction({
+  description:
+    "Fetch a bounded Pylon issue corpus through Pylon's server-side search endpoint, or preserve the legacy account/accounts compatibility calls used by generated extensions. Agents should prefer provider-api-request or provider-corpus-job for ad hoc Pylon queries.",
+  schema: z.object({
+    account: z.string().optional(),
+    accounts: z.coerce.boolean().default(false),
+    query: z.string().optional(),
+    days: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(730)
+      .default(371)
+      .describe("Created-at lookback window. Defaults to 53 weeks."),
+    pageSize: z.coerce.number().int().min(1).max(999).default(500),
+    maxPages: z.coerce.number().int().min(1).max(50).default(20),
+  }),
+  readOnly: true,
+  parallelSafe: true,
+  agentTool: false,
+  toolCallable: true,
+  http: { method: "POST" },
+  run: async ({ account, accounts, query, days, pageSize, maxPages }) => {
+    if (accounts) {
+      const response = (await executeProviderApiRequest({
+        provider: "pylon",
+        method: "GET",
+        path: "/accounts",
+        ...(query?.trim() ? { query: { query: query.trim() } } : {}),
+      })) as { response?: { json?: unknown } };
+      const body = response.response?.json;
+      const values = Array.isArray(body)
+        ? body
+        : body && typeof body === "object" && "data" in body
+          ? Array.isArray((body as { data?: unknown }).data)
+            ? (body as { data: unknown[] }).data
+            : []
+          : [];
+      return {
+        accounts: values,
+        total: values.length,
+        source: "pylon-accounts-compatibility",
+      };
+    }
+
+    if (account?.trim() || query?.trim()) {
+      const now = new Date();
+      const start = new Date(now.getTime() - 30 * DAY_MS);
+      const response = (await executeProviderApiRequest({
+        provider: "pylon",
+        method: "GET",
+        path: "/issues",
+        query: {
+          ...(account?.trim() ? { account_id: account.trim() } : {}),
+          ...(query?.trim() ? { query: query.trim() } : {}),
+          start_time: start.toISOString(),
+          end_time: now.toISOString(),
+        },
+      })) as { response?: { json?: unknown } };
+      const body = response.response?.json;
+      const values = Array.isArray(body)
+        ? body
+        : body && typeof body === "object" && "data" in body
+          ? Array.isArray((body as { data?: unknown }).data)
+            ? (body as { data: unknown[] }).data
+            : []
+          : [];
+      return {
+        issues: values,
+        total: values.length,
+        ...(account?.trim() ? { account: account.trim() } : {}),
+        source: "pylon-issues-compatibility",
+      };
+    }
+
+    const createdAfter = new Date(Date.now() - days * DAY_MS).toISOString();
+    const response = (await executeProviderApiRequest({
+      provider: "pylon",
+      method: "POST",
+      path: "/issues/search",
+      body: {
+        filter: {
+          field: "created_at",
+          operator: "time_is_after",
+          value: createdAfter,
+        },
+        limit: pageSize,
+      },
+      fetchAllPages: {
+        cursorPath: "pagination.cursor",
+        cursorBodyPath: "cursor",
+        itemsPath: "data",
+        maxPages,
+      },
+    })) as {
+      items?: unknown[];
+      pagesRead?: number;
+      totalItems?: number;
+      lastStatus?: number;
+      truncated?: boolean;
+      nextCursor?: string | null;
+    };
+    const issues = Array.isArray(response.items) ? response.items : [];
+    const pagesRead = Number(response.pagesRead ?? 0);
+    return {
+      issues,
+      total: Number(response.totalItems ?? issues.length),
+      pagesRead,
+      createdAfter,
+      coverageComplete: response.truncated !== true,
+      truncated: response.truncated === true,
+      nextCursor: response.nextCursor ?? null,
+      source: "pylon-issues-search",
+    };
+  },
+});

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

@@ -15,7 +15,7 @@ function resolveScope() {
 
 export default defineAction({
   description:
-    "Query the built-in first-party Analytics source: events recorded through this app's analytics collector endpoint (/track) and session replay summaries recorded through /api/analytics/replay. This source does not require an external provider connection. Use it for questions about app/site traffic, product events, template/app usage, conversions, session recordings, LLM/agent observability, model cost, token volume, latency, and other first-party data collected by this analytics app. Use source-specific actions such as BigQuery, GA4, Mixpanel, PostHog, or Amplitude when the user asks for those sources or the relevant data lives there. SQL may read analytics_events and session_recordings only; session_replay_chunks is intentionally unavailable, and reads are automatically scoped to the current user/org. analytics_events columns include event_name, timestamp, event_date, user_id, anonymous_id, user_key, session_id, app, template, signed_in, url, path, hostname, referrer, properties, and context. LLM observability events use event_name = '$ai_generation'; useful properties include $ai_trace_id/run_id, $ai_session_id/thread_id, $ai_model/model, $ai_provider/provider, $ai_input_tokens/input_tokens, $ai_output_tokens/output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, $ai_total_cost_usd/cost_usd, duration_ms/$ai_latency, status, tool_calls, successful_tools, failed_tools, and error_message/$ai_error. session_recordings columns include id, session_id, user_id, anonymous_id, user_key, started_at, ended_at, duration_ms, chunk_count, event_count, page_count, error_count, rage_click_count, app, template, status, first_url, last_url, path, hostname, referrer, and metadata.",
+    "Query the built-in first-party Analytics source: events recorded through this app's analytics collector endpoint (/track) and session replay summaries recorded through /api/analytics/replay. This source does not require an external provider connection. Use it for questions about app/site traffic, product events, template/app usage, conversions, session recordings, LLM/agent observability, model cost, token volume, latency, and other first-party data collected by this analytics app. Use source-specific actions such as BigQuery, GA4, Mixpanel, PostHog, or Amplitude when the user asks for those sources or the relevant data lives there. SQL may read analytics_events and session_recordings only; session_replay_chunks is intentionally unavailable, and reads are automatically scoped to the current user/org. analytics_events columns include event_name, timestamp, event_date, user_id, anonymous_id, user_key, session_id, app, template, signed_in, url, path, hostname, referrer, properties, and context. LLM observability events use event_name = '$ai_generation'; useful properties include $ai_trace_id/run_id, $ai_session_id/thread_id, $ai_model/model, $ai_provider/provider, $ai_input_tokens/input_tokens, $ai_output_tokens/output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, $ai_total_cost_usd/cost_usd, duration_ms/$ai_latency, status, tool_calls, successful_tools, failed_tools, tools, tools_truncated, delegated, delegation_protocol, caller_app, a2a_task_id, parent_run_id, parent_turn_id, and error_message/$ai_error. The bounded tools array contains names, relative start times, durations, statuses, and coarse error classes only, never args or results; failed runs and interrupted tools remain queryable. session_recordings columns include id, session_id, user_id, anonymous_id, user_key, started_at, ended_at, duration_ms, chunk_count, event_count, page_count, error_count, rage_click_count, app, template, status, first_url, last_url, path, hostname, referrer, and metadata.",
   schema: z.object({
     sql: z
       .string()