@agent-native/core 0.106.1 → 0.106.2

package/corpus/README.md

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

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.106.2
+
+### Patch Changes
+
+- 7fb8e89: Return a verified artifact receipt when an integration mutation succeeds without a final model summary.
+
 ## 0.106.1
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.106.1",
+  "version": "0.106.2",
   "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

@@ -3,6 +3,8 @@ import { createHmac, timingSafeEqual } from "node:crypto";
 export interface A2AToolResultSummary {
   tool: string;
   result: string;
+  isError?: boolean;
+  completedSideEffect?: boolean;
 }
 
 export interface A2AArtifactResponseOptions {
@@ -34,6 +36,7 @@ const ARTIFACT_IDENTITY_WRITE_TOOLS = new Set([
   "add-database-item",
   "create-document",
   "update-document",
+  "set-document-property",
   "create-deck",
   "duplicate-deck",
   "add-slide",
@@ -545,6 +548,8 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
   const forms = new Map<string, CreatedFormArtifact>();
 
   for (const toolResult of results) {
+    if (toolResult.isError === true || toolResult.completedSideEffect === false)
+      continue;
     if (toolResult.tool === "call-agent") {
       for (const artifact of parseDownstreamArtifactBlock(toolResult.result)) {
         if (artifact.kind === "deck") {
@@ -632,6 +637,7 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
       toolResult.tool === "create-document" ||
       toolResult.tool === "update-document"
     ) {
+      if (parsed.conflict === true) continue;
       const id = stringValue(parsed.id);
       if (id) {
         documents.set(id, {
@@ -643,6 +649,17 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
       continue;
     }
 
+    if (toolResult.tool === "set-document-property") {
+      const id = stringValue(parsed.documentId);
+      if (id) {
+        documents.set(id, {
+          id,
+          url: stringValue(parsed.url) ?? stringValue(parsed.urlPath),
+        });
+      }
+      continue;
+    }
+
     if (
       toolResult.tool === "get-document" ||
       toolResult.tool === "get-content-document"
@@ -872,6 +889,8 @@ export function extractA2AArtifactIdentities(
   };
 
   for (const result of results) {
+    if (result.isError === true || result.completedSideEffect === false)
+      continue;
     if (result.tool === "call-agent") {
       for (const identity of persistedArtifactIdentitiesFromMarker(
         result.result,
@@ -1540,3 +1559,68 @@ export function buildA2ARecoverableArtifactMessage(
     ...lines,
   ].join("\n");
 }
+
+function mutationReceiptUrl(
+  identity: A2AArtifactIdentity,
+  baseUrl: string | undefined,
+): string | undefined {
+  if (
+    identity.sourceAction === "call-agent" &&
+    (!identity.url || identity.url.startsWith("/"))
+  ) {
+    return undefined;
+  }
+  if (identity.url) {
+    return identity.url.startsWith("/")
+      ? artifactUrl(baseUrl, identity.url)
+      : identity.url;
+  }
+
+  const path =
+    identity.resourceType === "document"
+      ? `/page/${identity.id}`
+      : identity.resourceType === "deck"
+        ? `/deck/${identity.id}`
+        : identity.resourceType === "dashboard"
+          ? `/adhoc/${identity.id}`
+          : identity.resourceType === "analysis"
+            ? `/analyses/${identity.id}`
+            : identity.resourceType === "image"
+              ? `/image/${identity.id}`
+              : identity.resourceType === "design"
+                ? `/design/${identity.id}`
+                : undefined;
+  return path ? artifactUrl(baseUrl, path) : undefined;
+}
+
+/**
+ * Build a bounded participant-facing receipt from authenticated artifact writes.
+ * Unlike generic artifact recovery, this only trusts identities extracted from
+ * successful write actions (or a signed downstream write ledger), so a read or
+ * an unverified URL cannot be rounded up to a successful mutation.
+ */
+export function buildA2AVerifiedMutationReceipt(
+  toolResults: A2AToolResultSummary[],
+  options: A2AArtifactResponseOptions = {},
+): string | null {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  const identities = extractA2AArtifactIdentities(toolResults);
+  if (identities.length === 0) return null;
+
+  const lines = identities.map((identity) => {
+    const label =
+      identity.resourceType.charAt(0).toUpperCase() +
+      identity.resourceType.slice(1);
+    const url = mutationReceiptUrl(identity, baseUrl);
+    return url
+      ? `- ${label}: ${url} (ID: ${identity.id})`
+      : `- ${label} ID: ${identity.id}`;
+  });
+
+  return [
+    "A verified change was saved, but I couldn't generate the detailed summary.",
+    "",
+    "Saved artifacts:",
+    ...lines,
+  ].join("\n");
+}

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

@@ -719,7 +719,7 @@ export function threadMessageTextForEngine(message: any): string {
 
   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.",
+    "Trusted action history for this conversation. Resource IDs remain stable if participants rename the resource. Fields such as titleAtAction are historical aliases from the time of that action, not current resource state. Use stable IDs to locate an earlier artifact, read its current state before changing it, and omit fields the user did not explicitly ask to change while still deciding whether to update, add, supersede, or create.",
     promptSafeJson(artifacts),
     "</integration_artifact_context>",
   ].join("\n");

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

@@ -2,6 +2,7 @@ import type { H3Event } from "h3";
 
 import {
   appendA2AArtifactLinks,
+  buildA2AVerifiedMutationReceipt,
   extractA2AArtifactIdentities,
   type A2AToolResultSummary,
 } from "../a2a/artifact-response.js";
@@ -83,7 +84,13 @@ const DEFERRED_RESPONSE_MAX_HANDLER_MS = 2_500;
 const EMPTY_INTEGRATION_RESPONSE_MESSAGE =
   "The model finished without a visible answer. Try again, or open the thread in Dispatch to inspect the run.";
 
-type ToolDoneEvent = { type: "tool_done"; tool: string; result: string };
+type ToolDoneEvent = {
+  type: "tool_done";
+  tool: string;
+  result: string;
+  isError?: boolean;
+  completedSideEffect?: boolean;
+};
 
 /**
  * Build a stable per-event dedup key from the incoming message. The same
@@ -204,6 +211,25 @@ function collectToolResultSummaries(
   return completedRun.events
     .map((runEvent) => runEvent.event)
     .filter((event): event is ToolDoneEvent => event.type === "tool_done")
+    .map((event) => ({
+      tool: event.tool,
+      result: event.result,
+      isError: event.isError,
+      completedSideEffect: event.completedSideEffect,
+    }));
+}
+
+function collectCompletedMutationToolResultSummaries(
+  completedRun: ActiveRun,
+): A2AToolResultSummary[] {
+  return completedRun.events
+    .map((runEvent) => runEvent.event)
+    .filter(
+      (event): event is ToolDoneEvent =>
+        event.type === "tool_done" &&
+        event.completedSideEffect === true &&
+        event.isError !== true,
+    )
     .map((event) => ({ tool: event.tool, result: event.result }));
 }
 
@@ -923,6 +949,18 @@ async function processIncomingMessage(
             queuedA2AContinuation &&
             isQueuedA2AContinuationDeferral(responseText);
 
+          // Compute trusted tool receipts before choosing the empty-answer
+          // fallback. A completed write must not be reported as though nothing
+          // happened merely because the model ran out of time before its prose
+          // summary. Read-only and unverified tool results do not qualify.
+          const baseUrl = process.env.APP_URL || process.env.URL || "";
+          const appBaseUrl = baseUrl ? withConfiguredAppBasePath(baseUrl) : "";
+          const toolResults = collectToolResultSummaries(completedRun);
+          const verifiedMutationReceipt = buildA2AVerifiedMutationReceipt(
+            collectCompletedMutationToolResultSummaries(completedRun),
+            { baseUrl: appBaseUrl || undefined },
+          );
+
           // If the run errored OR produced no text, post a graceful fallback so
           // the user isn't left wondering whether the bot saw their message.
           // Common case: an A2A delegation timed out and the agent loop bailed
@@ -953,7 +991,8 @@ async function processIncomingMessage(
                 "If it was a complex analytics question, opening the analytics app " +
                 "directly is the most reliable way to get an answer right now.";
             } else {
-              responseText = EMPTY_INTEGRATION_RESPONSE_MESSAGE;
+              responseText =
+                verifiedMutationReceipt ?? EMPTY_INTEGRATION_RESPONSE_MESSAGE;
             }
           }
           if (approval?.type === "approval_required") {
@@ -965,9 +1004,6 @@ async function processIncomingMessage(
           // platforms with rich blocks (Slack) can render a button instead
           // of inlining a `<url|text>` link that auto-unfurls into a giant
           // preview card.
-          const baseUrl = process.env.APP_URL || process.env.URL || "";
-          const appBaseUrl = baseUrl ? withConfiguredAppBasePath(baseUrl) : "";
-          const toolResults = collectToolResultSummaries(completedRun);
           if (!suppressPlatformReply) {
             responseText = appendA2AArtifactLinks(responseText, toolResults, {
               baseUrl: appBaseUrl || undefined,

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -13,7 +13,10 @@ import {
   type H3Event,
 } from "h3";
 
-import { buildA2ARecoverableArtifactMessage } from "../a2a/artifact-response.js";
+import {
+  buildA2ARecoverableArtifactMessage,
+  type A2AToolResultSummary,
+} from "../a2a/artifact-response.js";
 import {
   hasConfiguredA2ASecret,
   isLoopbackAddress,
@@ -1463,7 +1466,7 @@ export function createAgentChatPlugin(
           // Run the SAME agent loop, then extract the final answer from the
           // event stream so pre-tool narration never leaks as the A2A result.
           const a2aEvents: AgentChatEvent[] = [];
-          const a2aToolResults: Array<{ tool: string; result: string }> = [];
+          const a2aToolResults: A2AToolResultSummary[] = [];
           let lastRecoverableArtifactText = "";
           const controller = new AbortController();
 
@@ -1498,6 +1501,8 @@ export function createAgentChatPlugin(
                   a2aToolResults.push({
                     tool: event.tool,
                     result: event.result,
+                    isError: event.isError,
+                    completedSideEffect: event.completedSideEffect,
                   });
                   const recoverableArtifactText =
                     buildA2ARecoverableArtifactMessage(a2aToolResults, {

package/corpus/templates/clips/app/components/capture-install-options.tsx

@@ -7,7 +7,7 @@ import {
   IconDeviceDesktop,
   IconExternalLink,
 } from "@tabler/icons-react";
-import { type ReactNode } from "react";
+import { type ReactNode, useSyncExternalStore } from "react";
 
 import { Button, type ButtonProps } from "@/components/ui/button";
 import {
@@ -16,11 +16,24 @@ import {
   PopoverTrigger,
 } from "@/components/ui/popover";
 import {
+  attemptOpenDesktopApp,
   clipsChromeExtensionEnabled,
   clipsChromeExtensionUrl,
+  hasDownloadedDesktopApp,
+  subscribeDownloaded,
 } from "@/lib/capture-install-options";
 import { cn } from "@/lib/utils";
 
+// SSR snapshot is always false; same-tab markDesktopAppDownloaded() notifies
+// subscribers so mounted CTAs flip to "Open" without a reload.
+function useHasDownloadedDesktopApp(): boolean {
+  return useSyncExternalStore(
+    subscribeDownloaded,
+    hasDownloadedDesktopApp,
+    () => false,
+  );
+}
+
 type PopoverPlacement = {
   align?: "start" | "center" | "end";
   side?: "top" | "right" | "bottom" | "left";
@@ -29,11 +42,15 @@ type PopoverPlacement = {
 type CaptureInstallButtonProps = Omit<ButtonProps, "asChild"> &
   PopoverPlacement & {
     children: ReactNode;
+    /** Label shown once the desktop app has been downloaded. */
+    downloadedChildren?: ReactNode;
     desktopHref?: string;
   };
 
 type CaptureInstallInlineLinkProps = PopoverPlacement & {
   children: ReactNode;
+  /** Label shown once the desktop app has been downloaded. */
+  downloadedChildren?: ReactNode;
   className?: string;
   desktopHref?: string;
 };
@@ -110,16 +127,37 @@ function InstallOptionsContent({ desktopHref = "/download" }) {
 
 export function CaptureInstallButton({
   children,
+  downloadedChildren,
   className,
   desktopHref = "/download",
   align = "end",
   side = "bottom",
   ...buttonProps
 }: CaptureInstallButtonProps) {
+  const downloaded = useHasDownloadedDesktopApp();
+  const label = downloaded ? (downloadedChildren ?? children) : children;
+
+  if (downloaded) {
+    const { onClick, ...restButtonProps } = buttonProps;
+    return (
+      <Button
+        className={className}
+        {...restButtonProps}
+        onClick={(event) => {
+          onClick?.(event);
+          if (event.defaultPrevented) return;
+          attemptOpenDesktopApp(desktopHref);
+        }}
+      >
+        {label}
+      </Button>
+    );
+  }
+
   if (!clipsChromeExtensionEnabled) {
     return (
       <Button asChild className={className} {...buttonProps}>
-        <a href={appPath(desktopHref)}>{children}</a>
+        <a href={appPath(desktopHref)}>{label}</a>
       </Button>
     );
   }
@@ -128,7 +166,7 @@ export function CaptureInstallButton({
     <Popover>
       <PopoverTrigger asChild>
         <Button className={className} {...buttonProps}>
-          {children}
+          {label}
           <IconChevronDown className="h-3.5 w-3.5" />
         </Button>
       </PopoverTrigger>
@@ -141,15 +179,32 @@ export function CaptureInstallButton({
 
 export function CaptureInstallInlineLink({
   children,
+  downloadedChildren,
   className,
   desktopHref = "/download",
   align = "start",
   side = "bottom",
 }: CaptureInstallInlineLinkProps) {
+  const downloaded = useHasDownloadedDesktopApp();
+
+  const label = downloaded ? (downloadedChildren ?? children) : children;
+
+  if (downloaded) {
+    return (
+      <button
+        type="button"
+        onClick={() => attemptOpenDesktopApp(desktopHref)}
+        className={cn("cursor-pointer", className)}
+      >
+        {label}
+      </button>
+    );
+  }
+
   if (!clipsChromeExtensionEnabled) {
     return (
       <a href={appPath(desktopHref)} className={className}>
-        {children}
+        {label}
       </a>
     );
   }
@@ -158,7 +213,7 @@ export function CaptureInstallInlineLink({
     <Popover>
       <PopoverTrigger asChild>
         <button type="button" className={cn("cursor-pointer", className)}>
-          {children}
+          {label}
         </button>
       </PopoverTrigger>
       <PopoverContent align={align} side={side} className="w-80 p-3">

package/corpus/templates/clips/app/components/library/library-layout.tsx

@@ -528,7 +528,15 @@ export function LibraryLayout({ children }: LibraryLayoutProps) {
           <>
             <div className="shrink-0 space-y-1.5 px-2 py-1.5">
               {shouldShowSidebarLink && (
-                <CaptureInstallInlineLink className="flex w-full items-center gap-2 rounded px-2 py-1.5 text-xs text-foreground hover:bg-accent/60">
+                <CaptureInstallInlineLink
+                  className="flex w-full items-center gap-2 rounded px-2 py-1.5 text-xs text-foreground hover:bg-accent/60"
+                  downloadedChildren={
+                    <>
+                      <IconAppWindow className="h-4 w-4" />
+                      {t("captureInstall.openDesktopApp")}
+                    </>
+                  }
+                >
                   <IconAppWindow className="h-4 w-4" />
                   {t("navigation.desktopCta")}
                 </CaptureInstallInlineLink>

package/corpus/templates/clips/app/hooks/use-desktop-promo.ts

@@ -2,8 +2,8 @@ import { useCallback, useEffect, useState } from "react";
 
 import { useIsMobile } from "@/hooks/use-mobile";
 import {
-  hasDownloadedDesktopApp,
-  markDesktopAppDownloaded,
+  hasDismissedDesktopPromo,
+  markDesktopPromoDismissed,
 } from "@/lib/capture-install-options";
 
 function detectDesktopApp(): boolean {
@@ -27,12 +27,12 @@ export function useDesktopPromo() {
 
   useEffect(() => {
     setIsDesktopApp(detectDesktopApp());
-    setDismissed(hasDownloadedDesktopApp());
+    setDismissed(hasDismissedDesktopPromo());
   }, []);
 
   const dismiss = useCallback(() => {
     setDismissed(true);
-    markDesktopAppDownloaded();
+    markDesktopPromoDismissed();
   }, []);
 
   return {

package/corpus/templates/clips/app/i18n/ar-SA.ts

@@ -1106,6 +1106,7 @@ const messages = {
     desktopTitle: "Desktop app (مترجم)",
     desktopDescription:
       "Most seamless for global shortcuts, menu-bar recording, meetings, and repeat captures. (مترجم)",
+    openDesktopApp: "Open desktop app (مترجم)",
   },
   editableTitle: {
     untitled: "Untitled Clip (مترجم)",

package/corpus/templates/clips/app/i18n/de-DE.ts

@@ -1132,6 +1132,7 @@ Alle sichtbaren Änderungen für Clips-Nutzer werden hier dokumentiert. Du kanns
     desktopTitle: "Desktop app (Lokalisiert)",
     desktopDescription:
       "Most seamless for global shortcuts, menu-bar recording, meetings, and repeat captures. (Lokalisiert)",
+    openDesktopApp: "Open desktop app (Lokalisiert)",
   },
   editableTitle: {
     untitled: "Untitled Clip (Lokalisiert)",

package/corpus/templates/clips/app/i18n/en-US.ts

@@ -1102,6 +1102,7 @@ All notable user-facing changes to Clips are documented here. Open it any time f
     desktopTitle: "Desktop app",
     desktopDescription:
       "Most seamless for global shortcuts, menu-bar recording, meetings, and repeat captures.",
+    openDesktopApp: "Open desktop app",
   },
   editableTitle: {
     untitled: "Untitled Clip",

package/corpus/templates/clips/app/i18n/es-ES.ts

@@ -1125,6 +1125,7 @@ Todos los cambios visibles para los usuarios de Clips se documentan aquí. Puede
     desktopTitle: "Desktop app (Localizado)",
     desktopDescription:
       "Most seamless for global shortcuts, menu-bar recording, meetings, and repeat captures. (Localizado)",
+    openDesktopApp: "Open desktop app (Localizado)",
   },
   editableTitle: {
     untitled: "Untitled Clip (Localizado)",

package/corpus/templates/clips/app/i18n/fr-FR.ts

@@ -1127,6 +1127,7 @@ Tous les changements visibles par les utilisateurs de Clips sont documentés ici
     desktopTitle: "Desktop app (Localisé)",
     desktopDescription:
       "Most seamless for global shortcuts, menu-bar recording, meetings, and repeat captures. (Localisé)",
+    openDesktopApp: "Open desktop app (Localisé)",
   },
   editableTitle: {
     untitled: "Untitled Clip (Localisé)",

package/corpus/templates/clips/app/i18n/hi-IN.ts

@@ -1093,6 +1093,7 @@ Clips में उपयोगकर्ताओं को दिखने व
     desktopTitle: "Desktop app (स्थानीयकृत)",
     desktopDescription:
       "Most seamless for global shortcuts, menu-bar recording, meetings, and repeat captures. (स्थानीयकृत)",
+    openDesktopApp: "Open desktop app (स्थानीयकृत)",
   },
   editableTitle: {
     untitled: "Untitled Clip (स्थानीयकृत)",

package/corpus/templates/clips/app/i18n/ja-JP.ts

@@ -1114,6 +1114,7 @@ Clips のユーザー向けの主な変更はここに記録されます。コ
     desktopTitle: "Desktop app (ローカライズ済み)",
     desktopDescription:
       "Most seamless for global shortcuts, menu-bar recording, meetings, and repeat captures. (ローカライズ済み)",
+    openDesktopApp: "Open desktop app (ローカライズ済み)",
   },
   editableTitle: {
     untitled: "Untitled Clip (ローカライズ済み)",

package/corpus/templates/clips/app/i18n/ko-KR.ts

@@ -1103,6 +1103,7 @@ Clips의 모든 사용자 대상 변경 사항은 여기에 기록됩니다. 명
     desktopTitle: "Desktop app (현지화됨)",
     desktopDescription:
       "Most seamless for global shortcuts, menu-bar recording, meetings, and repeat captures. (현지화됨)",
+    openDesktopApp: "Open desktop app (현지화됨)",
   },
   editableTitle: {
     untitled: "Untitled Clip (현지화됨)",

package/corpus/templates/clips/app/i18n/pt-BR.ts

@@ -1121,6 +1121,7 @@ Todas as mudanças visíveis para usuários do Clips são documentadas aqui. Voc
     desktopTitle: "Desktop app (Localizado)",
     desktopDescription:
       "Most seamless for global shortcuts, menu-bar recording, meetings, and repeat captures. (Localizado)",
+    openDesktopApp: "Open desktop app (Localizado)",
   },
   editableTitle: {
     untitled: "Untitled Clip (Localizado)",

package/corpus/templates/clips/app/i18n/zh-CN.ts

@@ -1064,6 +1064,7 @@ Clips 中所有面向用户的重要更改都会记录在这里。你可以随
     desktopTitle: "Desktop app (已本地化)",
     desktopDescription:
       "Most seamless for global shortcuts, menu-bar recording, meetings, and repeat captures. (已本地化)",
+    openDesktopApp: "Open desktop app (已本地化)",
   },
   editableTitle: {
     untitled: "Untitled Clip (已本地化)",

package/corpus/templates/clips/app/i18n/zh-TW.ts

@@ -1055,6 +1055,7 @@ const messages = {
       "瀏覽器記錄選項已就緒，正在等待 Chrome Web Store URL。",
     desktopTitle: "桌面應用程式",
     desktopDescription: "最適合全域快捷鍵、選單列錄製、會議與重複擷取。",
+    openDesktopApp: "開啟桌面應用程式",
   },
   editableTitle: {
     untitled: "未命名剪輯",