@agent-native/core 0.101.6 → 0.101.7

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2258
-- template files: 5635
+- template files: 5639

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.101.7
+
+### Patch Changes
+
+- 70caa6f: Preserve participant-visible integration replies and verified artifact identities so threaded corrections can reliably target resources after renames.
+
 ## 0.101.6
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.101.6",
+  "version": "0.101.7",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/a2a/artifact-response.ts

@@ -1,3 +1,5 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
 export interface A2AToolResultSummary {
   tool: string;
   result: string;
@@ -6,6 +8,121 @@ export interface A2AToolResultSummary {
 export interface A2AArtifactResponseOptions {
   baseUrl?: string;
   includeReferencedArtifacts?: boolean;
+  includePersistedArtifactMarker?: boolean;
+}
+
+export interface A2AArtifactIdentity {
+  resourceType:
+    | "document"
+    | "deck"
+    | "dashboard"
+    | "analysis"
+    | "image"
+    | "design"
+    | "monitor"
+    | "form";
+  id: string;
+  sourceAction: string;
+  titleAtAction?: string;
+  url?: string;
+}
+
+const ARTIFACT_IDENTITY_WRITE_TOOLS = new Set([
+  "save-monitor",
+  "create-form",
+  "submit-content-database-form",
+  "add-database-item",
+  "create-document",
+  "update-document",
+  "create-deck",
+  "duplicate-deck",
+  "add-slide",
+  "update-dashboard",
+  "rename-dashboard",
+  "save-analysis",
+  "generate-image",
+  "edit-image",
+  "refine-image",
+  "restyle-image",
+  "save-generated-image",
+  "save-generated-asset",
+  "export-image",
+  "export-asset",
+  "generate-image-batch",
+  "create-design",
+  "generate-design",
+  "create-file",
+  "duplicate-design",
+]);
+
+const PERSISTED_ARTIFACT_MARKER = "agent-native:persisted-artifacts=";
+const PERSISTED_ARTIFACT_MARKER_PATTERN =
+  /\s*<!--\s*agent-native:persisted-artifacts=[A-Za-z0-9_-]+\.[a-f0-9]{64}\s*-->/g;
+const ARTIFACT_RESOURCE_TYPES = new Set<A2AArtifactIdentity["resourceType"]>([
+  "document",
+  "deck",
+  "dashboard",
+  "analysis",
+  "image",
+  "design",
+  "monitor",
+  "form",
+]);
+
+function persistedArtifactIdentitiesFromMarker(
+  result: string,
+): A2AArtifactIdentity[] {
+  const secret = process.env.A2A_SECRET;
+  if (!secret) return [];
+  const match = result.match(
+    /<!--\s*agent-native:persisted-artifacts=([A-Za-z0-9_-]+)\.([a-f0-9]{64})\s*-->/,
+  );
+  if (!match) return [];
+  try {
+    const payload = match[1];
+    const expected = createHmac("sha256", secret).update(payload).digest();
+    const supplied = Buffer.from(match[2], "hex");
+    if (
+      supplied.length !== expected.length ||
+      !timingSafeEqual(supplied, expected)
+    ) {
+      return [];
+    }
+    const parsed = JSON.parse(Buffer.from(payload, "base64url").toString());
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .slice(0, 12)
+      .filter((identity): identity is A2AArtifactIdentity => {
+        const item = asRecord(identity);
+        return (
+          !!item &&
+          ARTIFACT_RESOURCE_TYPES.has(
+            item.resourceType as A2AArtifactIdentity["resourceType"],
+          ) &&
+          typeof item.id === "string" &&
+          typeof item.sourceAction === "string"
+        );
+      });
+  } catch {
+    return [];
+  }
+}
+
+function withPersistedArtifactMarker(
+  text: string,
+  toolResults: A2AToolResultSummary[],
+): string {
+  const identities = extractA2AArtifactIdentities(toolResults).slice(0, 12);
+  const secret = process.env.A2A_SECRET;
+  if (identities.length === 0 || !secret) return text;
+  const payload = Buffer.from(JSON.stringify(identities)).toString("base64url");
+  const signature = createHmac("sha256", secret).update(payload).digest("hex");
+  const marker = `<!-- ${PERSISTED_ARTIFACT_MARKER}${payload}.${signature} -->`;
+  return text ? `${text}\n\n${marker}` : marker;
+}
+
+export function stripA2APersistedArtifactMarkers(text: string): string {
+  return text.replace(PERSISTED_ARTIFACT_MARKER_PATTERN, "").trim();
 }
 
 interface CreatedDocumentArtifact {
@@ -617,15 +734,25 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
 
     if (
       toolResult.tool === "generate-image" ||
+      toolResult.tool === "edit-image" ||
       toolResult.tool === "refine-image" ||
+      toolResult.tool === "restyle-image" ||
       toolResult.tool === "get-asset" ||
       toolResult.tool === "save-generated-image" ||
+      toolResult.tool === "save-generated-asset" ||
       toolResult.tool === "export-image"
     ) {
       addImageArtifact(images, parsed);
       continue;
     }
 
+    if (toolResult.tool === "export-asset") {
+      if (stringValue(parsed.artifactType) === "image") {
+        addImageArtifact(images, parsed);
+      }
+      continue;
+    }
+
     if (toolResult.tool === "generate-image-batch") {
       if (Array.isArray(parsed.images)) {
         for (const item of parsed.images) {
@@ -730,6 +857,114 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
   };
 }
 
+/**
+ * Extract a compact, verified identity ledger from successful artifact tools.
+ * The ledger deliberately excludes raw tool results so it is safe to retain in
+ * long-lived thread context and stable even when a resource is later renamed.
+ */
+export function extractA2AArtifactIdentities(
+  results: A2AToolResultSummary[],
+): A2AArtifactIdentity[] {
+  const identities = new Map<string, A2AArtifactIdentity>();
+
+  const remember = (identity: A2AArtifactIdentity) => {
+    identities.set(`${identity.resourceType}:${identity.id}`, identity);
+  };
+
+  for (const result of results) {
+    if (result.tool === "call-agent") {
+      for (const identity of persistedArtifactIdentitiesFromMarker(
+        result.result,
+      )) {
+        remember({ ...identity, sourceAction: "call-agent" });
+      }
+      continue;
+    }
+    if (!ARTIFACT_IDENTITY_WRITE_TOOLS.has(result.tool)) continue;
+    const artifacts = collectArtifacts([result]);
+    for (const document of artifacts.documents) {
+      remember({
+        resourceType: "document",
+        id: document.id,
+        sourceAction: result.tool,
+        titleAtAction: document.title,
+        url: document.url,
+      });
+    }
+    for (const deck of artifacts.decks) {
+      remember({
+        resourceType: "deck",
+        id: deck.id,
+        sourceAction: result.tool,
+        url: deck.url,
+      });
+    }
+    for (const dashboard of artifacts.dashboards) {
+      remember({
+        resourceType: "dashboard",
+        id: dashboard.id,
+        sourceAction: result.tool,
+        titleAtAction: dashboard.title,
+        url: dashboard.url,
+      });
+    }
+    for (const analysis of artifacts.analyses) {
+      remember({
+        resourceType: "analysis",
+        id: analysis.id,
+        sourceAction: result.tool,
+        titleAtAction: analysis.title,
+        url: analysis.url,
+      });
+    }
+    for (const image of artifacts.images) {
+      remember({
+        resourceType: "image",
+        id: image.id,
+        sourceAction: result.tool,
+        titleAtAction: image.title,
+        url: image.url,
+      });
+    }
+    for (const design of artifacts.designShells) {
+      remember({
+        resourceType: "design",
+        id: design.id,
+        sourceAction: result.tool,
+        titleAtAction: design.title,
+      });
+    }
+    for (const design of artifacts.generatedDesigns) {
+      remember({
+        resourceType: "design",
+        id: design.id,
+        sourceAction: result.tool,
+        url: design.url,
+      });
+    }
+    for (const monitor of artifacts.monitors) {
+      remember({
+        resourceType: "monitor",
+        id: monitor.id,
+        sourceAction: result.tool,
+        titleAtAction: monitor.name,
+        url: monitor.url,
+      });
+    }
+    for (const form of artifacts.forms) {
+      remember({
+        resourceType: "form",
+        id: form.id,
+        sourceAction: result.tool,
+        titleAtAction: form.title,
+        url: form.url,
+      });
+    }
+  }
+
+  return [...identities.values()];
+}
+
 type DownstreamArtifact =
   | { kind: "deck"; id: string; url: string }
   | { kind: "document"; id: string; url: string; title?: string }
@@ -1131,6 +1366,10 @@ export function appendA2AArtifactLinks(
   const baseUrl = normalizeBaseUrl(options.baseUrl);
   const includeReferencedArtifacts =
     options.includeReferencedArtifacts ?? false;
+  const finalize = (value: string) =>
+    options.includePersistedArtifactMarker
+      ? withPersistedArtifactMarker(value, toolResults)
+      : value;
   const {
     documents,
     decks,
@@ -1160,7 +1399,7 @@ export function appendA2AArtifactLinks(
     ) ||
       /\b(?:done|created|ready|here(?:'s| is)|complete|finished)\b/i.test(text))
   ) {
-    return formatIncompleteDesignMessage(incompleteShells);
+    return finalize(formatIncompleteDesignMessage(incompleteShells));
   }
 
   const unverifiedRefs = findUnverifiedArtifactReferences(
@@ -1174,15 +1413,17 @@ export function appendA2AArtifactLinks(
     generatedDesigns,
   );
   if (unverifiedRefs.length > 0) {
-    return formatUnverifiedArtifactMessage(
-      unverifiedRefs,
-      documents,
-      decks,
-      dashboards,
-      analyses,
-      images,
-      generatedDesigns,
-      baseUrl,
+    return finalize(
+      formatUnverifiedArtifactMessage(
+        unverifiedRefs,
+        documents,
+        decks,
+        dashboards,
+        analyses,
+        images,
+        generatedDesigns,
+        baseUrl,
+      ),
     );
   }
 
@@ -1258,9 +1499,11 @@ export function appendA2AArtifactLinks(
     }
   }
 
-  if (missingLines.length === 0) return text;
+  if (missingLines.length === 0) {
+    return finalize(text);
+  }
   const artifactBlock = `Artifacts:\n${missingLines.join("\n")}`;
-  return text ? `${text}\n\n${artifactBlock}` : artifactBlock;
+  return finalize(text ? `${text}\n\n${artifactBlock}` : artifactBlock);
 }
 
 export function buildA2ARecoverableArtifactMessage(

package/corpus/core/src/agent/thread-data-builder.ts

@@ -637,23 +637,96 @@ export function threadDataToEngineMessages(
   for (const entry of data.messages) {
     const m = entry?.message ?? entry;
     if (!m || (m.role !== "user" && m.role !== "assistant")) continue;
-    const text =
-      typeof m.content === "string"
-        ? m.content
-        : Array.isArray(m.content)
-          ? m.content
-              .filter(
-                (c: any) => c?.type === "text" && typeof c.text === "string",
-              )
-              .map((c: any) => c.text)
-              .join("\n")
-          : "";
+    const text = threadMessageTextForEngine(m);
     if (!text.trim()) continue;
     messages.push({ role: m.role, content: [{ type: "text", text }] });
   }
   return messages;
 }
 
+const MAX_INTEGRATION_ARTIFACTS_IN_CONTEXT = 12;
+const MAX_INTEGRATION_ARTIFACT_FIELD_CHARS = 500;
+
+function boundedString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed
+    ? trimmed.slice(0, MAX_INTEGRATION_ARTIFACT_FIELD_CHARS)
+    : undefined;
+}
+
+function promptSafeJson(value: unknown): string {
+  return JSON.stringify(value)
+    .replaceAll("&", "\\u0026")
+    .replaceAll("<", "\\u003c")
+    .replaceAll(">", "\\u003e");
+}
+
+function messageTextContent(message: any): string {
+  if (typeof message?.content === "string") return message.content;
+  if (!Array.isArray(message?.content)) return "";
+  return message.content
+    .filter(
+      (part: any) => part?.type === "text" && typeof part.text === "string",
+    )
+    .map((part: any) => part.text)
+    .join("\n");
+}
+
+/**
+ * Select the participant-visible delivery for integration turns while keeping
+ * a compact, trusted resource ledger available to the agent. Raw tool results
+ * remain in thread_data for UI/audit use but are not replayed into the prompt.
+ */
+export function threadMessageTextForEngine(message: any): string {
+  const delivery = message?.metadata?.integrationDelivery;
+  const deliveryAttempted =
+    message?.metadata?.integrationDeliveryAttempted === true;
+  const deliveredText =
+    message?.role === "assistant" &&
+    delivery?.status === "delivered" &&
+    typeof delivery.text === "string" &&
+    delivery.text.trim()
+      ? delivery.text
+      : undefined;
+  let text =
+    deliveredText ??
+    (message?.role === "assistant" && deliveryAttempted
+      ? ""
+      : messageTextContent(message));
+
+  if (message?.role !== "assistant") return text;
+  const storedArtifacts = message?.metadata?.integrationArtifacts;
+  if (!Array.isArray(storedArtifacts)) return text;
+
+  const artifacts = storedArtifacts
+    .slice(0, MAX_INTEGRATION_ARTIFACTS_IN_CONTEXT)
+    .map((artifact: any) => ({
+      resourceType: boundedString(artifact?.resourceType),
+      id: boundedString(artifact?.id),
+      sourceAction: boundedString(artifact?.sourceAction),
+      titleAtAction: boundedString(artifact?.titleAtAction),
+      url: boundedString(artifact?.url),
+    }))
+    .filter(
+      (artifact: {
+        resourceType?: string;
+        id?: string;
+        sourceAction?: string;
+      }) => artifact.resourceType && artifact.id && artifact.sourceAction,
+    );
+  if (artifacts.length === 0) return text;
+
+  const context = [
+    "<integration_artifact_context>",
+    "Trusted action history for this conversation. Resource IDs remain stable if participants rename the resource. Use these IDs when a follow-up refers to an earlier artifact, while still deciding from the request whether to update, add, supersede, or create.",
+    promptSafeJson(artifacts),
+    "</integration_artifact_context>",
+  ].join("\n");
+  text = text.trim() ? `${text.trim()}\n\n${context}` : context;
+  return text;
+}
+
 export interface CodeAgentThreadTranscriptEvent {
   id: string;
   runId: string;

package/corpus/core/src/integrations/a2a-continuation-processor.ts

@@ -1,4 +1,8 @@
-import { appendA2AArtifactLinks } from "../a2a/artifact-response.js";
+import {
+  appendA2AArtifactLinks,
+  extractA2AArtifactIdentities,
+  stripA2APersistedArtifactMarkers,
+} from "../a2a/artifact-response.js";
 import { A2AClient, signA2AToken } from "../a2a/client.js";
 import type { Task } from "../a2a/types.js";
 import {
@@ -6,6 +10,8 @@ import {
   isLlmCredentialError,
   LLM_MISSING_CREDENTIALS_ERROR_CODE,
 } from "../agent/engine/credential-errors.js";
+import { extractThreadMeta } from "../agent/thread-data-builder.js";
+import { getThread, updateThreadData } from "../chat-threads/store.js";
 import { withConfiguredAppBasePath } from "../server/app-base-path.js";
 import { FRAMEWORK_ROUTE_PREFIX } from "../server/core-routes-plugin.js";
 import {
@@ -19,9 +25,11 @@ import {
   type A2AContinuation,
 } from "./a2a-continuations-store.js";
 import { signInternalToken } from "./internal-token.js";
+import { getThreadMapping } from "./thread-mapping-store.js";
 import type {
   OutgoingMessage,
   PlatformAdapter,
+  PlatformDeliveryReceipt,
   PlatformRunProgress,
 } from "./types.js";
 
@@ -359,8 +367,10 @@ async function deliverAndCompleteA2AContinuation(
   if (!deliveryContinuation) return;
 
   try {
-    const outgoing = adapter.formatAgentResponse(text);
-    await withTimeout(
+    const outgoing = adapter.formatAgentResponse(
+      stripA2APersistedArtifactMarkers(text),
+    );
+    const deliveryReceipt = await withTimeout(
       deliverA2AContinuationResponse(
         adapter,
         deliveryContinuation,
@@ -371,6 +381,27 @@ async function deliverAndCompleteA2AContinuation(
       PLATFORM_SEND_TIMEOUT_MS,
       `${deliveryContinuation.platform} response delivery timed out`,
     );
+    let persistenceError: unknown;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        await persistA2AContinuationDelivery(
+          deliveryContinuation,
+          outgoing,
+          deliveryReceipt,
+          text,
+        );
+        persistenceError = undefined;
+        break;
+      } catch (err) {
+        persistenceError = err;
+      }
+    }
+    if (persistenceError) {
+      console.error(
+        `[integrations] Delivered A2A continuation ${deliveryContinuation.id} but could not persist its thread history:`,
+        persistenceError,
+      );
+    }
   } catch (err) {
     if (deliveryContinuation.attempts >= MAX_ATTEMPTS) {
       await failA2AContinuation(
@@ -392,7 +423,7 @@ async function deliverA2AContinuationResponse(
   message: OutgoingMessage,
   progress: PlatformRunProgress | null,
   status: "done" | "error",
-): Promise<void> {
+): Promise<PlatformDeliveryReceipt> {
   if (progress) {
     try {
       await progress.onEvent({
@@ -400,8 +431,9 @@ async function deliverA2AContinuationResponse(
         agent: continuation.agentName,
         status,
       });
-      await progress.complete(message);
-      return;
+      const receipt = await progress.complete(message);
+      if (receipt?.status === "delivered") return receipt;
+      throw new Error("Continuation progress completed without delivery proof");
     } catch {
       // A resumed Slack stream can no longer be finalized (for example when
       // chat.stopStream rejects). Preserve the final answer with the same
@@ -417,9 +449,69 @@ async function deliverA2AContinuationResponse(
       }
     }
   }
-  await adapter.sendResponse(message, continuation.incoming, {
+  const receipt = await adapter.sendResponse(message, continuation.incoming, {
     placeholderRef: continuation.placeholderRef ?? undefined,
   });
+  if (receipt?.status !== "delivered") {
+    throw new Error("Continuation response completed without delivery proof");
+  }
+  return receipt;
+}
+
+async function persistA2AContinuationDelivery(
+  continuation: A2AContinuation,
+  outgoing: OutgoingMessage,
+  receipt: PlatformDeliveryReceipt,
+  artifactText: string,
+): Promise<void> {
+  const mapping = await getThreadMapping(
+    continuation.platform,
+    continuation.externalThreadId,
+  );
+  if (!mapping) return;
+  const thread = await getThread(mapping.internalThreadId);
+  if (!thread) return;
+
+  let repo: any;
+  try {
+    repo = JSON.parse(thread.threadData || "{}");
+  } catch {
+    repo = {};
+  }
+  if (!Array.isArray(repo.messages)) repo.messages = [];
+
+  const artifacts = extractA2AArtifactIdentities([
+    { tool: "call-agent", result: artifactText },
+  ]);
+  const metadata: Record<string, unknown> = {
+    integrationDeliveryAttempted: true,
+    integrationDelivery: {
+      platform: continuation.platform,
+      status: "delivered",
+      text: outgoing.text,
+      deliveredAt: new Date().toISOString(),
+      ...(receipt.messageRefs?.length
+        ? { messageRefs: receipt.messageRefs }
+        : {}),
+    },
+  };
+  if (artifacts.length > 0) metadata.integrationArtifacts = artifacts;
+
+  repo.messages.push({
+    id: `msg-${Date.now()}-assistant-continuation`,
+    role: "assistant",
+    content: [{ type: "text", text: outgoing.text }],
+    createdAt: new Date().toISOString(),
+    metadata,
+  });
+  const meta = extractThreadMeta(repo);
+  await updateThreadData(
+    mapping.internalThreadId,
+    JSON.stringify(repo),
+    meta.title || thread.title || "Integration Chat",
+    meta.preview || thread.preview || "",
+    repo.messages.length,
+  );
 }
 
 async function rescheduleAndRedispatchA2AContinuation(

package/corpus/core/src/integrations/adapters/discord.ts

@@ -9,6 +9,7 @@ import type {
   IntegrationStatus,
   OutgoingMessage,
   PlatformAdapter,
+  PlatformDeliveryReceipt,
 } from "../types.js";
 
 const DISCORD_MAX_CONTENT_LENGTH = 2_000;
@@ -209,7 +210,7 @@ export function discordAdapter(): PlatformAdapter {
     async sendResponse(
       message: OutgoingMessage,
       context: IncomingMessage,
-    ): Promise<void> {
+    ): Promise<void | PlatformDeliveryReceipt> {
       const applicationId = readString(context.platformContext.applicationId);
       const interactionToken = readString(
         context.responseContext?.interactionToken,
@@ -236,6 +237,7 @@ export function discordAdapter(): PlatformAdapter {
           chunk,
         );
       }
+      return { status: "delivered" };
     },
 
     formatAgentResponse(text: string): OutgoingMessage {

package/corpus/core/src/integrations/adapters/email.ts

@@ -18,6 +18,7 @@ import type {
   OutgoingMessage,
   IntegrationStatus,
   OutboundTarget,
+  PlatformDeliveryReceipt,
 } from "../types.js";
 
 /** Max body length before truncation */
@@ -249,7 +250,7 @@ export function emailAdapter(): PlatformAdapter {
     async sendResponse(
       message: OutgoingMessage,
       context: IncomingMessage,
-    ): Promise<void> {
+    ): Promise<void | PlatformDeliveryReceipt> {
       const agentAddress = await resolveSecret("EMAIL_AGENT_ADDRESS");
       if (!agentAddress) {
         console.error("[email] EMAIL_AGENT_ADDRESS not configured");
@@ -284,7 +285,9 @@ export function emailAdapter(): PlatformAdapter {
         });
       } catch (err) {
         console.error("[email] Failed to send response:", err);
+        throw err;
       }
+      return { status: "delivered" };
     },
 
     async sendMessageToTarget(