@agent-native/core 0.107.0 → 0.107.2

package/corpus/core/src/integrations/webhook-handler.ts

@@ -4,6 +4,7 @@ import {
   appendA2AArtifactLinks,
   buildA2AVerifiedMutationReceipt,
   extractA2AArtifactIdentities,
+  type A2AArtifactIdentity,
   type A2AToolResultSummary,
 } from "../a2a/artifact-response.js";
 import { collectFinalResponseTextFromAgentEvents } from "../a2a/response-text.js";
@@ -43,7 +44,7 @@ import { attachToolSearch } from "../agent/tool-search.js";
 import { createThread, getThread } from "../chat-threads/store.js";
 import { updateThreadData } from "../chat-threads/store.js";
 import { isLocalDatabase } from "../db/client.js";
-import { resolveOrgIdForEmail } from "../org/context.js";
+import { getOrgA2ASecret, resolveOrgIdForEmail } from "../org/context.js";
 import { withConfiguredAppBasePath } from "../server/app-base-path.js";
 import { FRAMEWORK_ROUTE_PREFIX } from "../server/core-routes-plugin.js";
 import {
@@ -62,6 +63,7 @@ import { signInternalToken } from "./internal-token.js";
 import {
   insertPendingTask,
   isDuplicateEventError,
+  stageTaskDeliveryPayload,
   type PendingTask,
 } from "./pending-tasks-store.js";
 import { integrationScopeSubjectKey } from "./scope-store.js";
@@ -69,6 +71,7 @@ import { getThreadMapping, saveThreadMapping } from "./thread-mapping-store.js";
 import type {
   PlatformAdapter,
   IncomingMessage,
+  OutgoingMessage,
   PlatformDeliveryReceipt,
 } from "./types.js";
 import {
@@ -92,6 +95,27 @@ type ToolDoneEvent = {
   completedSideEffect?: boolean;
 };
 
+export type IntegrationResponseDeliveryTaskPayload = {
+  kind: "response-delivery";
+  incoming: IncomingMessage;
+  message: OutgoingMessage;
+  placeholderRef?: string;
+  internalThreadId?: string;
+  userMessageId?: string;
+  assistantMessageId?: string;
+  deliveryReceipt?: PlatformDeliveryReceipt;
+  deliveredAt?: string;
+  artifacts?: A2AArtifactIdentity[];
+};
+
+export type ProcessIntegrationTaskResult =
+  | { status: "completed" }
+  | {
+      status: "delivery-pending";
+      payload: IntegrationResponseDeliveryTaskPayload;
+      errorMessage: string;
+    };
+
 /**
  * Build a stable per-event dedup key from the incoming message. The same
  * key is computed for every retry of the same event from the platform —
@@ -124,6 +148,17 @@ function buildEventDedupKey(incoming: IncomingMessage): string {
   return `${incoming.platform}:${incoming.externalThreadId}:${eventReference}`;
 }
 
+function buildDeliveryHistoryMessageIds(incoming: IncomingMessage): {
+  userMessageId: string;
+  assistantMessageId: string;
+} {
+  const eventKey = buildEventDedupKey(incoming);
+  return {
+    userMessageId: `integration-${eventKey}-user`,
+    assistantMessageId: `integration-${eventKey}-assistant`,
+  };
+}
+
 export interface WebhookHandlerOptions {
   adapter: PlatformAdapter;
   /** Resolved system prompt string */
@@ -546,7 +581,7 @@ export function resolveBaseUrl(event: H3Event): string {
 export async function processIntegrationTask(
   task: PendingTask,
   options: WebhookHandlerOptions,
-): Promise<void> {
+): Promise<ProcessIntegrationTaskResult> {
   const parsed = JSON.parse(task.payload) as {
     incoming: IncomingMessage;
     placeholderRef?: string;
@@ -555,7 +590,7 @@ export async function processIntegrationTask(
 
   await recordInboundIntegrationAudit(task, parsed.incoming);
 
-  await processIncomingMessage(parsed.incoming, options, {
+  return processIncomingMessage(parsed.incoming, options, {
     taskId: task.id,
     attempts: task.attempts,
     placeholderRef: parsed.placeholderRef,
@@ -615,7 +650,7 @@ async function processIncomingMessage(
     orgId?: string;
     principalType?: "user" | "service";
   } = {},
-): Promise<void> {
+): Promise<ProcessIntegrationTaskResult> {
   const {
     adapter,
     systemPrompt,
@@ -698,10 +733,49 @@ async function processIncomingMessage(
     const outgoing = adapter.formatAgentResponse(
       "This channel or requester has reached its configured AI usage budget. An admin can review the budget in Messaging settings.",
     );
-    await adapter.sendResponse(outgoing, incoming, {
-      placeholderRef: opts.placeholderRef,
-    });
-    return;
+    let deliveryPayload: IntegrationResponseDeliveryTaskPayload = {
+      kind: "response-delivery",
+      incoming,
+      message: outgoing,
+      ...(opts.placeholderRef ? { placeholderRef: opts.placeholderRef } : {}),
+    };
+    try {
+      if (opts.taskId) {
+        await stageTaskDeliveryPayload(
+          opts.taskId,
+          JSON.stringify(deliveryPayload),
+        );
+      }
+      const receipt = await adapter.sendResponse(outgoing, incoming, {
+        placeholderRef: opts.placeholderRef,
+      });
+      if (receipt?.status !== "delivered") {
+        throw new Error(
+          `${incoming.platform} response completed without delivery proof`,
+        );
+      }
+      deliveryPayload = {
+        ...deliveryPayload,
+        deliveryReceipt: receipt,
+        deliveredAt: new Date().toISOString(),
+      };
+      if (opts.taskId) {
+        await stageTaskDeliveryPayload(
+          opts.taskId,
+          JSON.stringify(deliveryPayload),
+        );
+      }
+      return { status: "completed" };
+    } catch (error) {
+      return {
+        status: "delivery-pending",
+        payload: deliveryPayload,
+        errorMessage:
+          error instanceof Error
+            ? error.message.slice(0, 1000)
+            : `${incoming.platform} response delivery failed`,
+      };
+    }
   }
 
   let threadId: string;
@@ -785,11 +859,13 @@ async function processIncomingMessage(
   // A2A delegation. Without this, getRequestOrgId() returns undefined and
   // call-agent can't look up the org's a2a_secret or org_domain.
   let orgId: string | null | undefined;
+  let artifactSecrets: string[];
   let runnableActions: Record<string, ActionEntry>;
   let tools: ReturnType<typeof actionsToEngineTools>;
   let availableTools: ReturnType<typeof actionsToEngineTools>;
   try {
     orgId = opts.orgId ?? (await resolveOrgIdForEmail(ownerEmail));
+    artifactSecrets = await resolveIntegrationArtifactSecrets(orgId);
     // Attach tool-search on a shallow copy so framework additions merged in
     // by `createIntegrationsPlugin` (integration memory, `call-agent`) can be
     // deferred behind it without mutating the plugin's long-lived registry.
@@ -811,7 +887,7 @@ async function processIncomingMessage(
 
   // Wait for the run to complete inside this fresh function execution.
   // We use a Promise so the processor endpoint can await the full lifecycle.
-  await new Promise<void>((resolve) => {
+  return new Promise<ProcessIntegrationTaskResult>((resolve) => {
     startRun(
       runId,
       threadId,
@@ -921,6 +997,14 @@ async function processIncomingMessage(
       async (completedRun: ActiveRun) => {
         let keepSlackInputWindow = false;
         let queuedA2AContinuation = false;
+        let outgoingForDelivery: OutgoingMessage | undefined;
+        let stagedDeliveryPayload:
+          | IntegrationResponseDeliveryTaskPayload
+          | undefined;
+        let threadCheckpoint:
+          | { userMessageId: string; assistantMessageId?: string }
+          | undefined;
+        let outcome: ProcessIntegrationTaskResult = { status: "completed" };
         try {
           queuedA2AContinuation = hasQueuedA2AContinuation(completedRun);
           const slackInputRequest =
@@ -1029,6 +1113,26 @@ async function processIncomingMessage(
             const outgoing = adapter.formatAgentResponse(responseText, {
               threadDeepLinkUrl,
             });
+            outgoingForDelivery = outgoing;
+            stagedDeliveryPayload = {
+              kind: "response-delivery",
+              incoming,
+              message: outgoing,
+              ...(opts.placeholderRef
+                ? { placeholderRef: opts.placeholderRef }
+                : {}),
+              internalThreadId: threadId,
+              ...buildDeliveryHistoryMessageIds(incoming),
+              artifacts: extractA2AArtifactIdentities(toolResults, {
+                persistedArtifactSecrets: artifactSecrets,
+              }),
+            };
+            if (opts.taskId) {
+              await stageTaskDeliveryPayload(
+                opts.taskId,
+                JSON.stringify(stagedDeliveryPayload),
+              );
+            }
             let deliveryReceipt: void | PlatformDeliveryReceipt;
             if (queuedA2AContinuation && progress?.ref) {
               // Post substantive parent results as a normal thread reply while
@@ -1054,24 +1158,33 @@ async function processIncomingMessage(
                 placeholderRef: opts.placeholderRef,
               });
             }
-            const delivered = deliveryReceipt?.status === "delivered";
-            if (!delivered) {
+            if (deliveryReceipt?.status !== "delivered") {
               throw new Error(
                 `${incoming.platform} response completed without delivery proof`,
               );
             }
-            if (delivered) {
-              deliveredResponse = {
-                platform: incoming.platform,
-                status: "delivered",
-                text: outgoing.text,
-                deliveredAt: new Date().toISOString(),
-                ...(deliveryReceipt?.messageRefs?.length
-                  ? { messageRefs: deliveryReceipt.messageRefs }
-                  : {}),
-              };
+            const deliveredAt = new Date().toISOString();
+            stagedDeliveryPayload = {
+              ...stagedDeliveryPayload,
+              deliveryReceipt,
+              deliveredAt,
+            };
+            if (opts.taskId) {
+              await stageTaskDeliveryPayload(
+                opts.taskId,
+                JSON.stringify(stagedDeliveryPayload),
+              );
             }
-            if (slackInputRequest && delivered && incoming.senderId) {
+            deliveredResponse = {
+              platform: incoming.platform,
+              status: "delivered",
+              text: outgoing.text,
+              deliveredAt,
+              ...(deliveryReceipt.messageRefs?.length
+                ? { messageRefs: deliveryReceipt.messageRefs }
+                : {}),
+            };
+            if (slackInputRequest && incoming.senderId) {
               await setIntegrationAwaitingInput({
                 platform: "slack",
                 externalThreadId: incoming.externalThreadId,
@@ -1113,14 +1226,34 @@ async function processIncomingMessage(
           }
 
           // Persist thread data
-          await persistThreadData(
+          threadCheckpoint = await persistThreadData(
             threadId,
             incoming.text,
             completedRun,
             thread,
             deliveredResponse,
             toolResults,
+            stagedDeliveryPayload,
+            artifactSecrets,
           );
+          if (outgoingForDelivery && stagedDeliveryPayload) {
+            if (!threadCheckpoint) {
+              throw new Error("Integration response history checkpoint failed");
+            }
+            stagedDeliveryPayload = {
+              ...stagedDeliveryPayload,
+              userMessageId: threadCheckpoint.userMessageId,
+              ...(threadCheckpoint.assistantMessageId
+                ? { assistantMessageId: threadCheckpoint.assistantMessageId }
+                : {}),
+            };
+            if (opts.taskId) {
+              await stageTaskDeliveryPayload(
+                opts.taskId,
+                JSON.stringify(stagedDeliveryPayload),
+              );
+            }
+          }
           await recordIntegrationUsage({
             usage,
             ownerEmail,
@@ -1141,9 +1274,64 @@ async function processIncomingMessage(
             `[integrations] Error sending response to ${incoming.platform}:`,
             err,
           );
+          if (outgoingForDelivery) {
+            const errorMessage =
+              err instanceof Error
+                ? err.message.slice(0, 1000)
+                : `${incoming.platform} response delivery failed`;
+            if (!stagedDeliveryPayload?.deliveryReceipt) {
+              threadCheckpoint = await persistThreadData(
+                threadId,
+                incoming.text,
+                completedRun,
+                thread,
+                undefined,
+                collectToolResultSummaries(completedRun),
+                stagedDeliveryPayload,
+                artifactSecrets,
+              );
+            }
+            if (usage) {
+              await recordIntegrationUsage({
+                usage,
+                ownerEmail,
+                appId: options.appId,
+                runId,
+                threadId,
+                taskId: opts.taskId,
+                orgId: orgId ?? undefined,
+                incoming,
+              }).catch(() => {});
+              try {
+                await settleApplicableIntegrationBudgets(
+                  budgetReservations.reservations,
+                  usage,
+                );
+                budgetsSettled = true;
+              } catch {}
+            }
+            outcome = {
+              status: "delivery-pending",
+              payload: {
+                ...(stagedDeliveryPayload ?? {
+                  kind: "response-delivery",
+                  incoming,
+                  message: outgoingForDelivery,
+                  internalThreadId: threadId,
+                }),
+                ...(threadCheckpoint?.userMessageId
+                  ? { userMessageId: threadCheckpoint.userMessageId }
+                  : {}),
+                ...(threadCheckpoint?.assistantMessageId
+                  ? { assistantMessageId: threadCheckpoint.assistantMessageId }
+                  : {}),
+              },
+              errorMessage,
+            };
+            return;
+          }
           // A queued continuation owns the final platform response. Later
-          // bookkeeping failures (for example, persisting this parent run)
-          // must not close its resumable native stream with a false failure.
+          // bookkeeping failures must not close its stream with a false failure.
           if (queuedA2AContinuation) return;
           // Last-ditch: try to post a brief apology so the thread isn't silent.
           try {
@@ -1170,7 +1358,7 @@ async function processIncomingMessage(
               budgetReservations.reservations,
             );
           }
-          resolve();
+          resolve(outcome);
         }
       },
       // Integration workers are ordinary self-dispatched serverless requests,
@@ -1583,7 +1771,12 @@ async function persistThreadData(
     messageRefs?: string[];
   },
   toolResults: A2AToolResultSummary[] = [],
-): Promise<void> {
+  messageIds?: Pick<
+    IntegrationResponseDeliveryTaskPayload,
+    "userMessageId" | "assistantMessageId"
+  >,
+  artifactSecrets: readonly string[] = [],
+): Promise<{ userMessageId: string; assistantMessageId?: string } | undefined> {
   try {
     let repo: any;
     try {
@@ -1595,31 +1788,44 @@ async function persistThreadData(
 
     // Add user message
     const userMsg = {
-      id: `msg-${Date.now()}-user`,
+      id: messageIds?.userMessageId ?? `msg-${Date.now()}-user`,
       role: "user",
       content: [{ type: "text", text: userText }],
       createdAt: new Date().toISOString(),
     };
 
     // Build assistant message from run events
-    const assistantMsg = buildAssistantMessage(
+    const builtAssistantMsg = buildAssistantMessage(
       completedRun.events ?? [],
       completedRun.runId,
     );
+    if (builtAssistantMsg && messageIds?.assistantMessageId) {
+      builtAssistantMsg.id = messageIds.assistantMessageId;
+    }
+    const existingAssistantMsg = builtAssistantMsg
+      ? repo.messages.find(
+          (message: any) => message?.id === builtAssistantMsg.id,
+        )
+      : undefined;
+    const assistantMsg = existingAssistantMsg ?? builtAssistantMsg;
     if (assistantMsg) {
       assistantMsg.metadata.integrationDeliveryAttempted = true;
+      const artifactIdentities = extractA2AArtifactIdentities(toolResults, {
+        persistedArtifactSecrets: artifactSecrets,
+      });
+      if (artifactIdentities.length > 0) {
+        assistantMsg.metadata.integrationArtifacts = artifactIdentities;
+      }
       if (deliveredResponse) {
         assistantMsg.metadata.integrationDelivery = deliveredResponse;
-        const artifactIdentities = extractA2AArtifactIdentities(toolResults);
-        if (artifactIdentities.length > 0) {
-          assistantMsg.metadata.integrationArtifacts = artifactIdentities;
-        }
       }
     }
 
-    repo.messages.push(userMsg);
-    if (assistantMsg) {
-      repo.messages.push(assistantMsg);
+    if (!repo.messages.some((message: any) => message?.id === userMsg.id)) {
+      repo.messages.push(userMsg);
+    }
+    if (builtAssistantMsg && !existingAssistantMsg) {
+      repo.messages.push(builtAssistantMsg);
     }
 
     const meta = extractThreadMeta(repo);
@@ -1630,7 +1836,104 @@ async function persistThreadData(
       meta.preview || thread?.preview || "",
       repo.messages.length,
     );
+    return {
+      userMessageId: userMsg.id,
+      ...(assistantMsg?.id ? { assistantMessageId: assistantMsg.id } : {}),
+    };
   } catch {
     // Best-effort persistence
+    return undefined;
+  }
+}
+
+async function resolveIntegrationArtifactSecrets(
+  orgId: string | null | undefined,
+): Promise<string[]> {
+  const secrets: string[] = [];
+  const add = (secret: string | null | undefined) => {
+    const value = secret?.trim();
+    if (value && !secrets.includes(value)) secrets.push(value);
+  };
+  add(process.env.A2A_SECRET);
+  if (orgId) {
+    try {
+      add(await getOrgA2ASecret(orgId));
+    } catch {}
   }
+  return secrets;
+}
+
+export async function recordIntegrationResponseDelivery(
+  payload: IntegrationResponseDeliveryTaskPayload,
+  receipt: PlatformDeliveryReceipt,
+): Promise<void> {
+  if (!payload.internalThreadId) return;
+  const thread = await getThread(payload.internalThreadId);
+  if (!thread) throw new Error("Integration delivery thread was not found");
+
+  let repo: any;
+  try {
+    repo = JSON.parse(thread.threadData || "{}");
+  } catch {
+    throw new Error("Integration delivery thread data is invalid");
+  }
+  if (!Array.isArray(repo.messages)) {
+    repo.messages = [];
+  }
+  const stableMessageIds = buildDeliveryHistoryMessageIds(payload.incoming);
+  const userMessageId = payload.userMessageId ?? stableMessageIds.userMessageId;
+  const assistantMessageId =
+    payload.assistantMessageId ?? stableMessageIds.assistantMessageId;
+  const userMsg = userMessageId
+    ? repo.messages.find((message: any) => message?.id === userMessageId)
+    : undefined;
+  let assistantMsg = assistantMessageId
+    ? repo.messages.find((message: any) => message?.id === assistantMessageId)
+    : undefined;
+  const createdAt = payload.deliveredAt ?? new Date().toISOString();
+  if (!userMsg) {
+    repo.messages.push({
+      id: userMessageId,
+      role: "user",
+      content: [{ type: "text", text: payload.incoming.text }],
+      createdAt,
+    });
+  }
+  if (!assistantMsg) {
+    assistantMsg = {
+      id: assistantMessageId,
+      role: "assistant",
+      content: [{ type: "text", text: payload.message.text }],
+      createdAt,
+      metadata: {
+        integrationDeliveryAttempted: true,
+        ...(payload.artifacts?.length
+          ? { integrationArtifacts: payload.artifacts }
+          : {}),
+      },
+    };
+    repo.messages.push(assistantMsg);
+  }
+  if (!assistantMsg.metadata || typeof assistantMsg.metadata !== "object") {
+    assistantMsg.metadata = {};
+  }
+  assistantMsg.metadata.integrationDeliveryAttempted = true;
+  assistantMsg.metadata.integrationDelivery = {
+    platform: payload.incoming.platform,
+    status: "delivered",
+    text: payload.message.text,
+    deliveredAt: payload.deliveredAt ?? new Date().toISOString(),
+    ...(receipt.messageRefs?.length
+      ? { messageRefs: receipt.messageRefs }
+      : {}),
+  };
+
+  const meta = extractThreadMeta(repo);
+  await updateThreadData(
+    payload.internalThreadId,
+    JSON.stringify(repo),
+    meta.title || thread.title || "Integration Chat",
+    meta.preview || thread.preview || "",
+    repo.messages.length,
+  );
 }

package/corpus/core/src/localization/default-messages.ts

@@ -697,7 +697,10 @@ const messages = {
     configure: "Configure",
     connect: "Connect",
     connectWithOAuth: "Connect with OAuth",
+    useApiToken: "Use API token",
     connectSuggestion: "Connect {{name}} to use this link in chat",
+    connectSuggestionWithApiToken:
+      "Connect {{name}} with an API token to use this link in chat",
     dismissSuggestion: "Dismiss integration suggestion",
     backToIntegrations: "Back to integrations",
     customTitle: "Add custom MCP server",
@@ -792,7 +795,7 @@ const messages = {
           "Bring Figma design context and canvas actions into an agent.",
         useCase: "Design files, components, variables, design systems, canvas",
         setupNote:
-          "Figma only allows clients listed in its MCP Catalog. Agent Native needs vendor approval before this remote endpoint can complete a connection; use the existing Figma OAuth connector for app-owned workflows in the meantime.",
+          "Figma MCP only allows clients listed in Figma's MCP Catalog, so this remote endpoint cannot connect from Agent Native yet. Use the Figma REST API fallback with a personal access token for reading file and node context; MCP canvas actions remain unavailable until Figma approves Agent Native.",
       },
       canva: {
         description: "Search, create, and update Canva designs and assets.",

package/corpus/core/src/secrets/register-framework-secrets.ts

@@ -197,4 +197,32 @@ export function registerFrameworkSecrets(): void {
       required: false,
     });
   }
+
+  if (!getRequiredSecret("FIGMA_ACCESS_TOKEN")) {
+    registerRequiredSecret({
+      key: "FIGMA_ACCESS_TOKEN",
+      label: "Figma access token",
+      description:
+        "Optional fallback for reading Figma file and node context when the hosted Figma MCP server is unavailable. Generate a personal access token with current_user:read and file_content:read.",
+      docsUrl:
+        "https://developers.figma.com/docs/rest-api/personal-access-tokens/",
+      scope: "user",
+      kind: "api-key",
+      required: false,
+      validator: async (value) => {
+        const response = await fetch("https://api.figma.com/v1/me", {
+          headers: {
+            "X-Figma-Token": value,
+            "User-Agent": "AgentNative/1.0",
+          },
+        });
+        return response.ok
+          ? { ok: true }
+          : {
+              ok: false,
+              error: `Figma rejected the token (HTTP ${response.status}).`,
+            };
+      },
+    });
+  }
 }