@agent-native/core 0.108.0 → 0.109.0

package/corpus/core/src/provider-api/index.ts

@@ -1284,6 +1284,35 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
     defaultHeaders: { "Notion-Version": "2026-03-11" },
     templateUses: ["analytics", "brain", "content", "dispatch"],
     examples: [{ label: "Search", method: "POST", path: "/search", body: {} }],
+    corpusRecipes: [
+      {
+        label: "Search a Notion data source with complete cursor coverage",
+        useWhen:
+          "Use for coverage-sensitive searches across one known Notion data source's page properties. This does not search page block bodies.",
+        workflow: [
+          "Resolve the exact data source id and apply the narrowest provider-side filter and filter_properties projection first.",
+          "Start provider-corpus-job with mode=paginated-search and pass next_cursor back as start_cursor in the POST body.",
+          "Search only the returned properties and report the 10,000-result API ceiling plus any incomplete request_status.",
+          "For page body text, stage page ids and fetch block children through a separate bounded data program; property search is not body search.",
+        ],
+        request: {
+          method: "POST",
+          path: "/data_sources/<data-source-id>/query",
+          body: { page_size: 100 },
+        },
+        pagination: {
+          itemsPath: "results",
+          nextCursorPath: "next_cursor",
+          cursorBodyPath: "start_cursor",
+          maxPages: 100,
+        },
+        search: {
+          textPaths: ["properties"],
+          idPaths: ["id"],
+          metadataPaths: ["id", "url", "created_time", "last_edited_time"],
+        },
+      },
+    ],
   },
   posthog: {
     id: "posthog",
@@ -1306,11 +1335,21 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
     ],
     examples: [
       {
-        label: "List events",
-        method: "GET",
-        path: "/api/projects/{projectId}/events/",
+        label: "Aggregate events with HogQL",
+        method: "POST",
+        path: "/api/projects/{projectId}/query/",
+        body: {
+          query: {
+            kind: "HogQLQuery",
+            query:
+              "SELECT event, count() AS events FROM events WHERE timestamp >= now() - INTERVAL 7 DAY GROUP BY event ORDER BY events DESC LIMIT 100",
+          },
+        },
       },
     ],
+    notes: [
+      "Prefer the query endpoint with a bounded HogQL projection or server-side aggregation over paging raw events into the agent context.",
+    ],
   },
   prometheus: {
     id: "prometheus",
@@ -1400,6 +1439,39 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
       { label: "Search messages", method: "GET", path: "/search.messages" },
       { label: "Post message", method: "POST", path: "/chat.postMessage" },
     ],
+    notes: [
+      "Bot-token reads must not call conversations.join implicitly. A bot can read only conversations it is already a member of with the required history scope.",
+      "search.messages requires a compatible user token; do not assume a bot token can use it. Use conversations.history for channel-scoped bot reads.",
+    ],
+    corpusRecipes: [
+      {
+        label: "Search complete Slack channel history",
+        useWhen:
+          "Use for all-message, mention, phrase, or absence-sensitive searches in one known Slack conversation without one agent turn per cursor page.",
+        workflow: [
+          "Resolve the exact channel id without joining or mutating membership.",
+          "Start provider-corpus-job with mode=paginated-search against conversations.history, bounded by oldest/latest when possible.",
+          "Pass response_metadata.next_cursor back as cursor and let quota_wait pause/resume rate-limited installations.",
+          "Report channel id, time bounds, pages, messages searched, matches, and is_limited or access gaps.",
+        ],
+        request: {
+          method: "GET",
+          path: "/conversations.history",
+          query: { channel: "<channel-id>" },
+        },
+        pagination: {
+          itemsPath: "messages",
+          nextCursorPath: "response_metadata.next_cursor",
+          cursorParam: "cursor",
+          maxPages: 500,
+        },
+        search: {
+          textPaths: ["text", "blocks", "attachments"],
+          idPaths: ["ts", "client_msg_id"],
+          metadataPaths: ["ts", "user", "thread_ts", "type", "subtype"],
+        },
+      },
+    ],
   },
   stripe: {
     id: "stripe",
@@ -1690,60 +1762,66 @@ export async function executeProviderApiRequest(
   // --- fetchAllPages mode ---
   if (args.fetchAllPages) {
     const pageCfg = args.fetchAllPages;
-    const { items, pageCount, lastStatus, lastContentType } =
-      await fetchAllPages(pageCfg, async (extra) => {
-        const queryWithCursor = extra?.query
-          ? mergeQueryObjects(
-              substituteUnknown(args.query, placeholders),
-              extra.query,
-            )
-          : substituteUnknown(args.query, placeholders);
-        const pageUrl = buildProviderUrl({
-          config,
-          baseUrl,
-          rawPath: substituteString(args.path, placeholders),
-          query: queryWithCursor,
-        });
-        const bodyWithCursor = extra?.bodyCursor
-          ? setValueAtPath(
-              substituteUnknown(args.body, placeholders),
-              extra.bodyCursor.path,
-              extra.bodyCursor.value,
-            )
-          : substituteUnknown(args.body, placeholders);
-        const pageBody = prepareBody(bodyWithCursor, { ...headers });
-        const requestKey = createProviderRequestDedupeKey({
-          method,
-          url: pageUrl.href,
-          body: pageBody,
-          headers,
-        });
-        const resp = await fetchWithTimeout(pageUrl.href, {
+    const {
+      items,
+      pageCount,
+      lastStatus,
+      lastContentType,
+      truncated,
+      nextCursor,
+    } = await fetchAllPages(pageCfg, async (extra) => {
+      const queryWithCursor = extra?.query
+        ? mergeQueryObjects(
+            substituteUnknown(args.query, placeholders),
+            extra.query,
+          )
+        : substituteUnknown(args.query, placeholders);
+      const pageUrl = buildProviderUrl({
+        config,
+        baseUrl,
+        rawPath: substituteString(args.path, placeholders),
+        query: queryWithCursor,
+      });
+      const bodyWithCursor = extra?.bodyCursor
+        ? setValueAtPath(
+            substituteUnknown(args.body, placeholders),
+            extra.bodyCursor.path,
+            extra.bodyCursor.value,
+          )
+        : substituteUnknown(args.body, placeholders);
+      const pageBody = prepareBody(bodyWithCursor, headers);
+      const requestKey = createProviderRequestDedupeKey({
+        method,
+        url: pageUrl.href,
+        body: pageBody,
+        headers,
+      });
+      const resp = await fetchWithTimeout(pageUrl.href, {
+        method,
+        headers,
+        body: pageBody,
+        maxBytes: effectiveMaxBytes,
+        timeoutMs: clampTimeout(args.timeoutMs),
+        secretValues: auth.secretValues,
+        quota: {
+          identity: quotaIdentity,
           method,
-          headers,
-          body: pageBody,
-          maxBytes: effectiveMaxBytes,
-          timeoutMs: clampTimeout(args.timeoutMs),
-          secretValues: auth.secretValues,
-          quota: {
-            identity: quotaIdentity,
-            method,
-            target: describeProviderRequestTarget(
-              pageUrl.href,
-              auth.secretValues,
-            ),
-            requestKey,
-          },
-        });
-        return {
-          text:
-            resp.text ??
-            (resp.json !== undefined ? JSON.stringify(resp.json) : ""),
-          contentType: resp.contentType,
-          status: resp.status,
-          ok: resp.ok,
-        };
+          target: describeProviderRequestTarget(
+            pageUrl.href,
+            auth.secretValues,
+          ),
+          requestKey,
+        },
       });
+      return {
+        text:
+          resp.text ??
+          (resp.json !== undefined ? JSON.stringify(resp.json) : ""),
+        contentType: resp.contentType,
+        status: resp.status,
+        ok: resp.ok,
+      };
+    });
 
     const allItemsJson = JSON.stringify(items, null, 2);
     const metadata = {
@@ -1751,6 +1829,8 @@ export async function executeProviderApiRequest(
       pagesRead: pageCount,
       totalItems: Array.isArray(items) ? items.length : 0,
       lastStatus,
+      truncated,
+      nextCursor,
     };
 
     if (args.saveToFile) {
@@ -2642,57 +2722,63 @@ async function executeCustomProviderApiRequest(
   // --- fetchAllPages mode (same cursor pagination as built-in providers) ---
   if (args.fetchAllPages) {
     const pageCfg = args.fetchAllPages;
-    const { items, pageCount, lastStatus, lastContentType } =
-      await fetchAllPages(pageCfg, async (extra) => {
-        const queryWithCursor = extra?.query
-          ? mergeQueryObjects(args.query, extra.query)
-          : args.query;
-        const pageUrl = buildProviderUrl({
-          config: syntheticConfig,
-          baseUrl,
-          rawPath: args.path,
-          query: queryWithCursor,
-        });
-        const bodyWithCursor = extra?.bodyCursor
-          ? setValueAtPath(
-              args.body,
-              extra.bodyCursor.path,
-              extra.bodyCursor.value,
-            )
-          : args.body;
-        const pageBody = prepareBody(bodyWithCursor, { ...headers });
-        const requestKey = createProviderRequestDedupeKey({
-          method,
-          url: pageUrl.href,
-          body: pageBody,
-          headers,
-        });
-        const resp = await fetchWithTimeout(pageUrl.href, {
+    const {
+      items,
+      pageCount,
+      lastStatus,
+      lastContentType,
+      truncated,
+      nextCursor,
+    } = await fetchAllPages(pageCfg, async (extra) => {
+      const queryWithCursor = extra?.query
+        ? mergeQueryObjects(args.query, extra.query)
+        : args.query;
+      const pageUrl = buildProviderUrl({
+        config: syntheticConfig,
+        baseUrl,
+        rawPath: args.path,
+        query: queryWithCursor,
+      });
+      const bodyWithCursor = extra?.bodyCursor
+        ? setValueAtPath(
+            args.body,
+            extra.bodyCursor.path,
+            extra.bodyCursor.value,
+          )
+        : args.body;
+      const pageBody = prepareBody(bodyWithCursor, headers);
+      const requestKey = createProviderRequestDedupeKey({
+        method,
+        url: pageUrl.href,
+        body: pageBody,
+        headers,
+      });
+      const resp = await fetchWithTimeout(pageUrl.href, {
+        method,
+        headers,
+        body: pageBody,
+        maxBytes: effectiveMaxBytes,
+        timeoutMs: clampTimeout(args.timeoutMs),
+        secretValues: auth.secretValues,
+        quota: {
+          identity: quotaIdentity,
           method,
-          headers,
-          body: pageBody,
-          maxBytes: effectiveMaxBytes,
-          timeoutMs: clampTimeout(args.timeoutMs),
-          secretValues: auth.secretValues,
-          quota: {
-            identity: quotaIdentity,
-            method,
-            target: describeProviderRequestTarget(
-              pageUrl.href,
-              auth.secretValues,
-            ),
-            requestKey,
-          },
-        });
-        return {
-          text:
-            resp.text ??
-            (resp.json !== undefined ? JSON.stringify(resp.json) : ""),
-          contentType: resp.contentType,
-          status: resp.status,
-          ok: resp.ok,
-        };
+          target: describeProviderRequestTarget(
+            pageUrl.href,
+            auth.secretValues,
+          ),
+          requestKey,
+        },
       });
+      return {
+        text:
+          resp.text ??
+          (resp.json !== undefined ? JSON.stringify(resp.json) : ""),
+        contentType: resp.contentType,
+        status: resp.status,
+        ok: resp.ok,
+      };
+    });
 
     const allItemsJson = JSON.stringify(items, null, 2);
     const metadata = {
@@ -2704,6 +2790,8 @@ async function executeCustomProviderApiRequest(
       pagesRead: pageCount,
       totalItems: Array.isArray(items) ? items.length : 0,
       lastStatus,
+      truncated,
+      nextCursor,
     };
 
     if (args.saveToFile) {
@@ -5146,6 +5234,8 @@ async function fetchAllPages(
   pageCount: number;
   lastStatus: number;
   lastContentType: string | null;
+  truncated: boolean;
+  nextCursor: string | null;
 }> {
   const maxPages = Math.min(
     Number.isFinite(config.maxPages) && config.maxPages! > 0
@@ -5159,6 +5249,7 @@ async function fetchAllPages(
   let pageCount = 0;
   let lastStatus = 0;
   let lastContentType: string | null = null;
+  let truncated = false;
 
   if (!config.cursorParam && !config.cursorBodyPath) {
     throw new Error(
@@ -5224,12 +5315,21 @@ async function fetchAllPages(
       nextCursor === null ||
       nextCursor === cursor
     ) {
+      truncated = false;
       break;
     }
     cursor = String(nextCursor);
+    truncated = pageCount >= maxPages;
   }
 
-  return { items, pageCount, lastStatus, lastContentType };
+  return {
+    items,
+    pageCount,
+    lastStatus,
+    lastContentType,
+    truncated,
+    nextCursor: truncated ? (cursor ?? null) : null,
+  };
 }
 
 function fingerprint(value: string): string {

package/corpus/core/src/scripts/call-agent.ts

@@ -6,6 +6,7 @@ import {
   shouldPreferGlobalA2ASecret,
   signA2AToken,
 } from "../a2a/client.js";
+import { invokeAgentAction } from "../a2a/invoke.js";
 import type { A2AApprovedAction, Task } from "../a2a/types.js";
 import {
   formatLlmCredentialErrorMessage,
@@ -94,12 +95,13 @@ function formatDownstreamLlmCredentialFailure(
 
 export const tool: ActionTool = {
   description:
-    "Call a DIFFERENT, separately-deployed agent app to ask a question or delegate a task. This is strictly for cross-app A2A communication — for example, asking the mail agent to send an email while you are the calendar agent. NEVER use this to call your own app or perform actions you can do with your own tools. Using call-agent on yourself will fail and waste time. " +
+    "Call a DIFFERENT, separately-deployed app over A2A. When you know the exact exposed read-only action, pass action + input and omit message; this invokes it directly without starting the other app's model and is the fastest path for bounded data reads. Use message only for natural-language investigation, synthesis, mutations, or multi-step work that needs the other agent. NEVER use this to call your own app or perform actions you can do with your own tools. Using call-agent on yourself will fail and waste time. " +
     'For brand-consistent generated media, the first-party Assets agent is available as agent="assets"; use it when another app needs generated heroes, diagrams, product shots, thumbnails, videos, or design imagery, unless the current app has its own generation action that already delegates there. ' +
     "IMPORTANT — handling the response: " +
     "(a) If it contains a URL or ID, copy it VERBATIM into your reply. Do not 'correct' or pluralize the path (e.g. /deck/ → /decks/), normalize casing, or change the slug — any edit breaks the link. " +
     '(b) If it does NOT contain a URL/ID and the user asked for one, say so explicitly (e.g. "the agent created the deck/image but didn\'t return a link — open the app directly to view it"). NEVER invent a URL, slug, or path — guessing produces broken links that look real. ' +
-    "(c) If the downstream response reports missing credentials, never repeat raw env var names, Vault key names, token names, secret names, or other credential identifiers. Tell the user the target app needs its LLM/provider connection configured.",
+    "(c) If the downstream response reports missing credentials, never repeat raw env var names, Vault key names, token names, secret names, or other credential identifiers. Tell the user the target app needs its LLM/provider connection configured. " +
+    "(d) A bounded wait can expire while the remote task is still healthy. The result will include its taskId and exact retry instructions. Continue polling that SAME task with taskId; NEVER send a new check-in/follow-up message, because that starts duplicate downstream work.",
   parameters: {
     type: "object",
     properties: {
@@ -110,7 +112,24 @@ export const tool: ActionTool = {
       },
       message: {
         type: "string",
-        description: "The message/question to send to the other agent",
+        description:
+          "The message/question to send when starting a new task. Omit when taskId is provided.",
+      },
+      taskId: {
+        type: "string",
+        description:
+          "Existing A2A task ID returned by a timed-out call. Polls that exact task without sending a new message. Never create a fresh check-in message for work that already has a taskId.",
+      },
+      action: {
+        type: "string",
+        description:
+          "Exact read-only action exposed by the target app. Use with input and omit message/taskId to skip the downstream agent loop.",
+      },
+      input: {
+        type: "object",
+        description:
+          "Complete input object for action. The target app validates it and refuses actions that are not explicitly exposed read-only operations.",
+        additionalProperties: true,
       },
       approvedActions: {
         type: "array",
@@ -126,7 +145,7 @@ export const tool: ActionTool = {
         },
       },
     },
-    required: ["agent", "message"],
+    required: ["agent"],
   },
 };
 
@@ -137,12 +156,23 @@ export async function run(
 ): Promise<string> {
   const agentIdOrName = String(args.agent ?? "");
   const message = String(args.message ?? "");
+  const taskId = String(args.taskId ?? "").trim();
+  const action = String(args.action ?? "").trim();
+  const input = args.input ?? {};
   const approvedActions = Array.isArray(args.approvedActions)
     ? (args.approvedActions as A2AApprovedAction[])
     : undefined;
 
   if (!agentIdOrName) return "Error: --agent is required";
-  if (!message) return "Error: --message is required";
+  if (!message && !taskId && !action) {
+    return "Error: --message, --taskId, or --action is required";
+  }
+  if (action && (message || taskId)) {
+    return "Error: --action direct-invoke mode cannot be combined with --message or --taskId";
+  }
+  if (action && (!input || typeof input !== "object" || Array.isArray(input))) {
+    return "Error: --input must be an object when --action is provided";
+  }
 
   // Prevent self-calls — the agent must use its own registered tools instead
   if (selfAppId && agentIdOrName.toLowerCase() === selfAppId.toLowerCase()) {
@@ -157,16 +187,36 @@ export async function run(
     return `Error: Agent "${agentIdOrName}" not found. Available agents: ${available || "(none)"}`;
   }
 
+  if (action) {
+    if (context?.send) {
+      context.send({ type: "agent_call", agent: agent.name, status: "start" });
+    }
+    try {
+      const output = await invokeReadOnlyAppAction(
+        agent,
+        action,
+        input as Record<string, unknown>,
+      );
+      return output;
+    } finally {
+      if (context?.send) {
+        context.send({ type: "agent_call", agent: agent.name, status: "done" });
+      }
+    }
+  }
+
   // Append a small cross-app hint to the outgoing message so the receiving
   // agent (which may be on an older deploy without the receiver-side hint
   // in handlers.ts) still emits fully-qualified URLs. This is belt-and-
   // suspenders with the receiver hint — but it works against any current
   // deployment, no redeploy required.
-  const messageWithHint =
-    `${message}${integrationSourceContextHint()}\n\n` +
-    `[Note: this request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
-    `If you create or reference a deck/document/design/dashboard, include its FULLY-QUALIFIED URL (e.g. ${agent.url}/deck/<id>) in your reply, not a relative path. ` +
-    `Use only artifact IDs and URL paths returned by successful actions — never invent slugs, IDs, or hosts.]`;
+  const messageWithHint = taskId
+    ? ""
+    : `${message}${integrationSourceContextHint()}\n\n` +
+      `[Note: this request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
+      `If you create or reference a deck/document/design/dashboard, include its FULLY-QUALIFIED URL (e.g. ${agent.url}/deck/<id>) in your reply, not a relative path. ` +
+      `Use only artifact IDs and URL paths returned by successful actions — never invent slugs, IDs, or hosts. ` +
+      `Return a concise caller-ready synthesis rather than raw tool output or full transcripts; preserve source counts, IDs, short supporting quotes, and URLs needed to substantiate the answer.]`;
 
   try {
     // If we have a send context, use streaming so the UI shows progressive text
@@ -228,8 +278,9 @@ export async function run(
 
       let responseText = "";
       let lastSentLength = 0;
-      const existingContinuationText =
-        await formatExistingIntegrationContinuationIfRetry(agent, message);
+      const existingContinuationText = taskId
+        ? null
+        : await formatExistingIntegrationContinuationIfRetry(agent, message);
       if (existingContinuationText) return existingContinuationText;
 
       context.send({
@@ -338,13 +389,12 @@ export async function run(
           orgDomain: callerOrgDomain,
           orgSecret: callerOrgSecret,
           approvedActions,
+          ...(taskId ? { taskId } : {}),
           onUpdate: onRemotePollUpdate,
+          returnRecoverableArtifactsOnTimeout: false,
           ...(callTimeoutMs
             ? {
                 timeoutMs: callTimeoutMs,
-                // Integration callers must keep the timeout task id so the
-                // catch below can enqueue durable continuation polling.
-                returnRecoverableArtifactsOnTimeout: false,
               }
             : {}),
         });
@@ -387,8 +437,11 @@ export async function run(
                 agent.url,
               );
             } else {
-              const reason = pollErr?.message ?? "unknown error";
-              responseText = `The ${agent.name} agent is taking longer than expected and didn't reply in time. (${reason})`;
+              responseText = formatExistingTaskWaitInstruction(
+                agent.name,
+                timeoutTaskId,
+                agentIdOrName,
+              );
             }
           }
         } else {
@@ -427,6 +480,8 @@ export async function run(
       orgDomain: domain,
       orgSecret,
       approvedActions,
+      ...(taskId ? { taskId } : {}),
+      returnRecoverableArtifactsOnTimeout: false,
     });
     const sanitized =
       formatDownstreamLlmCredentialFailure(agent.name, response) ?? response;
@@ -438,6 +493,14 @@ export async function run(
       err,
     );
     if (credentialMessage) return credentialMessage;
+    const timeoutTaskId = getA2ATaskTimeoutTaskId(err);
+    if (timeoutTaskId) {
+      return formatExistingTaskWaitInstruction(
+        agent.name,
+        timeoutTaskId,
+        agentIdOrName,
+      );
+    }
     // Friendlier message for the common timeout case so the calling agent can
     // decide whether to give up or retry.
     if (/timeout|did not complete|Inactivity|504/i.test(msg)) {
@@ -447,6 +510,63 @@ export async function run(
   }
 }
 
+async function invokeReadOnlyAppAction(
+  agent: { name: string; url: string },
+  action: string,
+  input: Record<string, unknown>,
+): Promise<string> {
+  const callerEmail = getRequestUserEmail();
+  if (!callerEmail) {
+    return `Error calling ${agent.name} action ${action}: a signed-in user identity is required`;
+  }
+
+  let callerOrgDomain: string | undefined;
+  let callerOrgSecret: string | undefined;
+  const orgId = getRequestOrgId();
+  if (orgId) {
+    try {
+      callerOrgDomain = (await getOrgDomain(orgId)) ?? undefined;
+    } catch {}
+    try {
+      callerOrgSecret = (await getOrgA2ASecret(orgId)) ?? undefined;
+    } catch {}
+  }
+
+  if (!callerOrgSecret && !process.env.A2A_SECRET) {
+    return `Error calling ${agent.name} action ${action}: direct cross-app reads require A2A identity verification`;
+  }
+
+  try {
+    const invocation = await invokeAgentAction({
+      target: agent.url,
+      action,
+      input,
+      userEmail: callerEmail,
+      orgDomain: callerOrgDomain,
+      orgSecret: callerOrgSecret,
+    });
+    return invocation.result.status === "completed"
+      ? invocation.result.output
+      : `Error calling ${agent.name} action ${action}: ${invocation.result.output}`;
+  } catch (error) {
+    return `Error calling ${agent.name} action ${action}: ${
+      error instanceof Error ? error.message : String(error)
+    }`;
+  }
+}
+
+function formatExistingTaskWaitInstruction(
+  agentName: string,
+  taskId: string,
+  agentIdOrName: string,
+): string {
+  return (
+    `The ${agentName} task is still running under taskId "${taskId}". ` +
+    `Do not send ${agentName} a new check-in or follow-up message; that would start duplicate work. ` +
+    `Call call-agent again with agent="${agentIdOrName}" and taskId="${taskId}" (omit message) to continue waiting for this same task.`
+  );
+}
+
 async function enqueueIntegrationContinuationIfPossible(
   taskId: string,
   agent: { name: string; url: string },