@agent-native/core 0.108.0 → 0.109.0

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

@@ -20,10 +20,12 @@ const DEFAULT_GONG_TRANSCRIPT_LIMIT = 3;
 const MAX_GONG_TRANSCRIPT_LIMIT = 50;
 const DEFAULT_TRANSCRIPT_MAX_CHARS = 8_000;
 const MAX_TRANSCRIPT_MAX_CHARS = 100_000;
+const MAX_AGGREGATE_TRANSCRIPT_CHARS = 60_000;
 const DEFAULT_TRANSCRIPT_SCAN_LIMIT = 50;
 const MAX_TRANSCRIPT_SCAN_LIMIT = 200;
 const DEFAULT_TRANSCRIPT_SEARCH_MAX_CHARS = MAX_TRANSCRIPT_MAX_CHARS;
 const TRANSCRIPT_BATCH_SIZE = 20;
+const TRANSCRIPT_BATCH_CONCURRENCY = 3;
 const MAX_TRANSCRIPT_MATCHES_PER_CALL = 5;
 const MATCH_SNIPPET_RADIUS = 240;
 
@@ -74,6 +76,20 @@ function normalizeBoundedInt(
   return Math.max(min, Math.min(max, Math.floor(value!)));
 }
 
+function boundedTranscriptExcerptChars(
+  requestedChars: number,
+  transcriptCount: number,
+): number {
+  if (transcriptCount <= 0) return requestedChars;
+  return Math.min(
+    requestedChars,
+    Math.max(
+      1_000,
+      Math.floor(MAX_AGGREGATE_TRANSCRIPT_CHARS / transcriptCount),
+    ),
+  );
+}
+
 function asRecord(value: unknown): Record<string, unknown> | null {
   return value && typeof value === "object"
     ? (value as Record<string, unknown>)
@@ -218,6 +234,36 @@ async function fetchTranscriptBatch(calls: GongCall[]): Promise<{
   }
 }
 
+async function fetchTranscriptBatches(calls: GongCall[]): Promise<
+  Array<{
+    calls: GongCall[];
+    result: Awaited<ReturnType<typeof fetchTranscriptBatch>>;
+  }>
+> {
+  const batches = chunkCalls(calls, TRANSCRIPT_BATCH_SIZE);
+  const results: Array<{
+    calls: GongCall[];
+    result: Awaited<ReturnType<typeof fetchTranscriptBatch>>;
+  }> = [];
+  for (
+    let index = 0;
+    index < batches.length;
+    index += TRANSCRIPT_BATCH_CONCURRENCY
+  ) {
+    results.push(
+      ...(await Promise.all(
+        batches
+          .slice(index, index + TRANSCRIPT_BATCH_CONCURRENCY)
+          .map(async (batch) => ({
+            calls: batch,
+            result: await fetchTranscriptBatch(batch),
+          })),
+      )),
+    );
+  }
+  return results;
+}
+
 async function searchTranscriptEvidence(
   calls: GongCall[],
   query: string,
@@ -234,8 +280,10 @@ async function searchTranscriptEvidence(
   let truncatedTranscripts = 0;
   const callsToScan = calls.slice(0, scanLimit);
 
-  for (const batch of chunkCalls(callsToScan, TRANSCRIPT_BATCH_SIZE)) {
-    const batchResult = await fetchTranscriptBatch(batch);
+  for (const {
+    calls: batch,
+    result: batchResult,
+  } of await fetchTranscriptBatches(callsToScan)) {
     errors.push(...batchResult.errors);
 
     for (const call of batch) {
@@ -374,8 +422,10 @@ async function loadTranscriptEvidence(
 ): Promise<TranscriptEvidence[]> {
   const evidence: TranscriptEvidence[] = [];
   const callsToLoad = calls.slice(0, limit);
-  for (const batch of chunkCalls(callsToLoad, TRANSCRIPT_BATCH_SIZE)) {
-    const batchResult = await fetchTranscriptBatch(batch);
+  for (const {
+    calls: batch,
+    result: batchResult,
+  } of await fetchTranscriptBatches(callsToLoad)) {
     const errorByCallId = new Map(
       batchResult.errors.map((error) => [error.callId, error.error]),
     );
@@ -411,19 +461,31 @@ async function loadTranscriptEvidence(
  * ISO string for the Gong window filters. Returns undefined for empty/invalid
  * input so the caller falls back to the `days` window.
  */
-function normalizeGongDate(value: string | undefined): string | undefined {
+function normalizeGongDate(
+  value: string | undefined,
+  boundary: "start" | "end" = "start",
+): string | undefined {
   if (!value || typeof value !== "string") return undefined;
-  const ms = Date.parse(value.trim());
+  const normalized = value.trim();
+  const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(normalized);
+  const ms = Date.parse(dateOnly ? `${normalized}T00:00:00.000Z` : normalized);
   if (Number.isNaN(ms)) return undefined;
-  return new Date(ms).toISOString();
+  const date = new Date(ms);
+  if (dateOnly && boundary === "end") date.setUTCDate(date.getUTCDate() + 1);
+  return date.toISOString();
 }
 
 export default defineAction({
   // Read-only provider query: safe to call from run-code `appAction` and
   // reusable across continuation retries (no re-fetch on resume).
   readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  // A bounded multi-call transcript review is intentionally larger than the
+  // shared 50K tool default. One batched result avoids 10+ one-call-at-a-time
+  // model round trips while still staying well below the model context limit.
+  maxResultChars: 100_000,
   description:
-    "Query Gong sales calls, transcripts, and users. Pass --users for user list, --transcript for one transcript, --company to search by company/domain/person/email. For bounded account-level transcript mention/search questions, set transcriptQuery to search matching transcripts server-side and return coverage counts plus snippets instead of large transcript blobs. For deal, customer, objection, next-step, or deep-dive analysis, set includeTranscripts=true only when you need broad qualitative context rather than a specific term search. For complete account/cohort coverage (call counts, broad cohorts, or when 'no calls mention X' must be defensible), use provider-api-catalog(provider='gong') and provider-corpus-job mode='batch-search' against /calls/transcript after call-id discovery; this action can still enumerate a bounded account/company window with exhaustive=true via after/before.",
+    "Query Gong sales calls, transcripts, and users. Pass --users for user list, --transcript for one transcript, --company to search by company/domain/person/email. For bounded account-level transcript mention/search questions, set transcriptQuery to search matching transcripts server-side and return coverage counts plus snippets instead of large transcript blobs. For deal, customer, objection, next-step, or deep-dive analysis, set includeTranscripts=true only when you need broad qualitative context rather than a specific term search. For an 'all calls' transcript review in a bounded account/date window, use exhaustive=true with after/before and includeTranscripts=true; the action batches transcript retrieval and reports complete/partial coverage instead of forcing one tool call per transcript. For very broad cohorts or defensible absence searches, use provider-api-catalog(provider='gong') and provider-corpus-job mode='batch-search' against /calls/transcript after call-id discovery.",
   schema: z.object({
     users: cliBoolean.optional().describe("Set to true to list Gong users"),
     transcript: z.string().optional().describe("Call ID to get transcript"),
@@ -470,7 +532,7 @@ export default defineAction({
       .max(MAX_TRANSCRIPT_MAX_CHARS)
       .optional()
       .describe(
-        "Maximum transcript characters to return per call (default 8000, max 100000). Use the default for analysis; raise it only when the user asks for more quoted detail.",
+        "Maximum transcript characters to return per call (default 8000, max 100000). Batched results also share a 60000-character aggregate excerpt budget. Use the default for analysis; raise it only when the user asks for more quoted detail.",
       ),
     transcriptQuery: z
       .string()
@@ -490,7 +552,7 @@ export default defineAction({
     exhaustive: cliBoolean
       .optional()
       .describe(
-        "Return EVERY matching call in the window instead of stopping at `limit` — use this for complete cohort/account coverage when 'how many' or absence matters (e.g. scanning all of an account's calls). Returns call metadata only (transcripts are never auto-loaded in this mode, so it stays fast and avoids context bloat); then pull transcripts deliberately with `--transcript=<callId>` or a run-code scan. Always bound it with `after`/`before` or a small `days`: an unbounded exhaustive scan pages the whole Gong org and can hit the function timeout.",
+        "Return EVERY matching call in the window instead of stopping at `limit` — use this for complete cohort/account coverage when 'how many' or absence matters. By default this is metadata-only. With includeTranscripts=true, transcripts are fetched in batches up to transcriptLimit (all matched calls by default when there are 50 or fewer) and explicit coverage is returned. Always bound it with after/before or a small days window: an unbounded exhaustive scan pages the whole Gong org and can hit the function timeout.",
       ),
     after: z
       .string()
@@ -532,21 +594,21 @@ export default defineAction({
       );
       const exhaustive = Boolean(args.exhaustive);
       const fromDateTime = normalizeGongDate(args.after);
-      const toDateTime = normalizeGongDate(args.before);
+      const toDateTime = normalizeGongDate(args.before, "end");
       const result = await searchCalls(args.company, days, limit, {
         exhaustive,
         ...(fromDateTime ? { fromDateTime } : {}),
         ...(toDateTime ? { toDateTime } : {}),
       });
-      // Exhaustive mode is a metadata-only discovery pass: never auto-load
-      // transcripts (that would bloat context and risk the function timeout).
-      // The agent pulls transcripts deliberately afterward (--transcript or a
-      // run-code scan over result.calls).
-      const shouldLoadTranscripts =
-        Boolean(args.includeTranscripts) && !exhaustive;
+      const shouldLoadTranscripts = Boolean(args.includeTranscripts);
       const transcriptLimit = normalizeBoundedInt(
         args.transcriptLimit,
-        DEFAULT_GONG_TRANSCRIPT_LIMIT,
+        exhaustive
+          ? Math.max(
+              1,
+              Math.min(result.calls.length, MAX_GONG_TRANSCRIPT_LIMIT),
+            )
+          : DEFAULT_GONG_TRANSCRIPT_LIMIT,
         1,
         MAX_GONG_TRANSCRIPT_LIMIT,
       );
@@ -557,6 +619,10 @@ export default defineAction({
         1_000,
         MAX_TRANSCRIPT_MAX_CHARS,
       );
+      const boundedTranscriptExcerptMaxChars = boundedTranscriptExcerptChars(
+        transcriptExcerptMaxChars,
+        Math.min(transcriptLimit, result.calls.length),
+      );
       const transcriptSearchMaxChars = normalizeBoundedInt(
         args.transcriptMaxChars,
         transcriptQuery
@@ -583,9 +649,16 @@ export default defineAction({
         ? await loadTranscriptEvidence(
             result.calls,
             transcriptLimit,
-            transcriptExcerptMaxChars,
+            boundedTranscriptExcerptMaxChars,
           )
         : undefined;
+      const transcriptErrors =
+        transcripts?.filter((transcript) => Boolean(transcript.error)) ?? [];
+      const transcriptCoverageComplete = Boolean(
+        transcripts &&
+        transcripts.length >= result.calls.length &&
+        transcriptErrors.length === 0,
+      );
 
       return {
         ...result,
@@ -611,15 +684,29 @@ export default defineAction({
             }
           : {}),
         ...(transcripts ? { transcripts } : {}),
+        ...(transcripts
+          ? {
+              transcriptCoverage: {
+                availableCalls: result.calls.length,
+                inspectedCalls: transcripts.length,
+                successfulCalls: transcripts.length - transcriptErrors.length,
+                errorCount: transcriptErrors.length,
+                coverageComplete: transcriptCoverageComplete,
+                scanLimited: transcripts.length < result.calls.length,
+              },
+            }
+          : {}),
         guidance: [
           transcriptSearch
             ? `Transcript search inspected ${transcriptSearch.inspectedCalls} of ${result.calls.length} matching call(s) for "${transcriptQuery}" and found ${transcriptSearch.matches.length} matching call(s). Use coverageComplete/errors before making absence claims; increase transcriptScanLimit or narrow the window if coverage is incomplete.`
             : "",
           exhaustive
-            ? `Exhaustive discovery: returned all ${result.calls.length} matching call(s) in the window (metadata only). To search transcript content for a term, pull transcripts with --transcript=<callId> or a run-code scan over these call IDs — do not conclude a term is absent from metadata alone.`
+            ? shouldLoadTranscripts
+              ? `Exhaustive discovery returned all ${result.calls.length} matching call(s) in the bounded window before loading transcripts.`
+              : `Exhaustive discovery: returned all ${result.calls.length} matching call(s) in the window (metadata only). Set includeTranscripts=true to fetch the bounded set in batches, or use a provider-corpus job for a broader transcript search.`
             : callLimitGuidance(result.limit, result.truncated),
           shouldLoadTranscripts
-            ? `Loaded transcript excerpts for ${transcripts?.length ?? 0} matching call(s). Ground qualitative claims in the transcript text and cite the inspected call count.`
+            ? `Loaded transcript excerpts for ${transcripts?.length ?? 0} of ${result.calls.length} matching call(s) in batches (${transcriptCoverageComplete ? "complete coverage" : "partial coverage"}). Ground qualitative claims in the transcript text and cite transcriptCoverage; do not fetch these calls again one at a time.`
             : exhaustive
               ? ""
               : "For deep-dive or qualitative analysis, call this action again with includeTranscripts=true before drawing conclusions from call content.",
@@ -651,6 +738,10 @@ export default defineAction({
         1_000,
         MAX_TRANSCRIPT_MAX_CHARS,
       );
+      const boundedTranscriptExcerptMaxChars = boundedTranscriptExcerptChars(
+        transcriptExcerptMaxChars,
+        Math.min(transcriptLimit, limited.calls.length),
+      );
       const transcriptSearchMaxChars = normalizeBoundedInt(
         args.transcriptMaxChars,
         transcriptQuery
@@ -677,7 +768,7 @@ export default defineAction({
         ? await loadTranscriptEvidence(
             limited.calls,
             transcriptLimit,
-            transcriptExcerptMaxChars,
+            boundedTranscriptExcerptMaxChars,
           )
         : undefined;
 

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.",
+    };
+  },
+});