@agent-native/toolkit 0.205.0 → 0.206.0-nightly-20261009011246

package/src/app/chat/chat/run-recovery.tsx

@@ -4,10 +4,12 @@ import {
   localizeKnownChatErrorText,
 } from "@agent-native/core/client/agent-chat";
 import { agentNativePath } from "@agent-native/core/client/api-path";
+import { injectedAgentNativeAppId } from "@agent-native/core/client/app-config";
 import { BuilderBMark } from "@agent-native/core/client/builder-mark";
 import { formatClientFailureReport } from "@agent-native/core/client/failure-report";
 import { useFeatureFlagState } from "@agent-native/core/client/feature-flags";
 import { useFormatters, useT } from "@agent-native/core/client/i18n";
+import { trackOnboardingEvent } from "@agent-native/core/client/onboarding/use-onboarding";
 import { SETTINGS_REDESIGN_FLAG } from "@agent-native/core/feature-flags/registry";
 import { buildSettingsRoute } from "@agent-native/core/navigation";
 import { withBuilderUtmTrackingParams } from "@agent-native/core/shared/builder-link-tracking";
@@ -35,14 +37,57 @@ import { useState, useEffect, useCallback, useRef } from "react";
 import { Link } from "react-router";
 
 import { DeferredBuilderConnectPopover } from "../../settings/deferred-builder-connect-popover.js";
+import { currentTemplateId } from "../../settings/shell/app-identity.js";
 import { useBuilderConnectFlow } from "../../settings/useBuilderStatus.js";
 import { BuilderReferralInviteRow } from "../BuilderReferralInviteRow.js";
+import { SESSION_REPLAY_MASK_PROPS } from "../session-replay-privacy.js";
 
 const builderSubscriptionUrl = withBuilderUtmTrackingParams(
   "https://builder.io/account/subscription?signupSource=agent-native",
   { content: "chat_credit_limit" },
 );
 
+function setupTelemetryAppName(): string {
+  const appId = injectedAgentNativeAppId() ?? currentTemplateId();
+  return appId && /^[a-z0-9][a-z0-9-]{0,63}$/.test(appId)
+    ? appId.replace(/^agent-native-/, "") || "framework"
+    : "framework";
+}
+
+type SetupTelemetryEventName =
+  | "integration_setup_exposed"
+  | "integration_method_clicked"
+  | "integration_method_outcome";
+type SetupTelemetryMethodId = "setup_card" | "builder" | "custom_keys";
+type SetupTelemetryAction = "view" | "click" | "connect";
+type SetupTelemetryOutcome =
+  | "exposed"
+  | "started"
+  | "connected"
+  | "status_read_failed"
+  | "connection_failed";
+
+function trackSetupFunnelEvent(
+  eventName: SetupTelemetryEventName,
+  methodId: SetupTelemetryMethodId,
+  action: SetupTelemetryAction,
+  outcome: SetupTelemetryOutcome,
+): void {
+  trackOnboardingEvent(eventName, {
+    flow: "chat_setup",
+    app_name: setupTelemetryAppName(),
+    step_id: "connect_ai",
+    method_id: methodId,
+    action,
+    outcome,
+  });
+}
+
+type BuilderConnectTelemetryAttempt = {
+  statusAvailableAfterStart: boolean;
+  terminalErrorCleared: boolean;
+};
+
 export type LoopLimitInfo = { maxIterations?: number };
 
 export type RunErrorInfo = {
@@ -233,12 +278,61 @@ export function BuilderConnectCta({
   reconnect?: boolean;
 }) {
   const t = useT();
+  const connectAttemptRef = useRef<BuilderConnectTelemetryAttempt | null>(null);
+  const handleConnected = useCallback(async () => {
+    try {
+      await onConnected?.();
+    } finally {
+      if (!connectAttemptRef.current) return;
+      connectAttemptRef.current = null;
+      trackSetupFunnelEvent(
+        "integration_method_outcome",
+        "builder",
+        "connect",
+        "connected",
+      );
+    }
+  }, [onConnected]);
   const flow = useBuilderConnectFlow({
     provisionAccount: true,
     trackingSource: "assistant_chat_builder_cta",
-    onConnected,
+    onConnected: handleConnected,
   });
   const { configured, orgName, connecting, error } = flow;
+  useEffect(() => {
+    const attempt = connectAttemptRef.current;
+    if (!attempt) return;
+    if (!flow.statusUnavailable) attempt.statusAvailableAfterStart = true;
+    if (!flow.terminalError) attempt.terminalErrorCleared = true;
+
+    const outcome =
+      flow.statusUnavailable &&
+      flow.errorKind === "status-read" &&
+      attempt.statusAvailableAfterStart
+        ? "status_read_failed"
+        : flow.terminalError && attempt.terminalErrorCleared
+          ? "connection_failed"
+          : null;
+    if (!outcome) return;
+    connectAttemptRef.current = null;
+    trackSetupFunnelEvent(
+      "integration_method_outcome",
+      "builder",
+      "connect",
+      outcome,
+    );
+  }, [flow.errorKind, flow.statusUnavailable, flow.terminalError]);
+
+  const startBuilderConnect = useCallback(
+    (provisionAccount: boolean) => {
+      connectAttemptRef.current = {
+        statusAvailableAfterStart: !flow.statusUnavailable,
+        terminalErrorCleared: !flow.terminalError,
+      };
+      flow.start({ provisionAccount });
+    },
+    [flow.start, flow.statusUnavailable, flow.terminalError],
+  );
 
   if (variant === "compact") {
     if (configured && !reconnect) {
@@ -254,10 +348,21 @@ export function BuilderConnectCta({
 
     return (
       <div className="agent-builder-setup-card__builder-cta flex min-w-0 flex-col items-start gap-1 sm:items-end">
-        <DeferredBuilderConnectPopover flow={flow}>
+        <DeferredBuilderConnectPopover
+          flow={flow}
+          onConnect={startBuilderConnect}
+        >
           <button
             type="button"
             disabled={connecting}
+            onClick={() =>
+              trackSetupFunnelEvent(
+                "integration_method_clicked",
+                "builder",
+                "click",
+                "started",
+              )
+            }
             className="agent-builder-setup-card__builder-button inline-flex h-8 shrink-0 items-center gap-1 whitespace-nowrap rounded-md bg-foreground px-3 text-[11px] font-medium text-background hover:opacity-90 disabled:cursor-wait disabled:opacity-60"
             aria-busy={connecting}
           >
@@ -277,7 +382,10 @@ export function BuilderConnectCta({
           </button>
         </DeferredBuilderConnectPopover>
         {error && (
-          <p className="max-w-[13rem] text-[10px] leading-snug text-destructive sm:text-end">
+          <p
+            {...SESSION_REPLAY_MASK_PROPS}
+            className="max-w-[13rem] text-[10px] leading-snug text-destructive sm:text-end"
+          >
             {error}
           </p>
         )}
@@ -318,12 +426,30 @@ export function BuilderConnectCta({
         <p className="text-[11px] text-muted-foreground mt-0.5 max-w-[220px]">
           {t("agentChat.setup.freeCredits")}
         </p>
-        {error && <p className="mt-1 text-[10px] text-destructive">{error}</p>}
+        {error && (
+          <p
+            {...SESSION_REPLAY_MASK_PROPS}
+            className="mt-1 text-[10px] text-destructive"
+          >
+            {error}
+          </p>
+        )}
       </div>
-      <DeferredBuilderConnectPopover flow={flow}>
+      <DeferredBuilderConnectPopover
+        flow={flow}
+        onConnect={startBuilderConnect}
+      >
         <button
           type="button"
           disabled={connecting}
+          onClick={() =>
+            trackSetupFunnelEvent(
+              "integration_method_clicked",
+              "builder",
+              "click",
+              "started",
+            )
+          }
           className="ms-auto inline-flex items-center gap-1 shrink-0 rounded-md bg-foreground px-3 py-1.5 text-[11px] font-medium no-underline text-background hover:opacity-90 disabled:opacity-60 disabled:cursor-wait"
           aria-busy={connecting}
         >
@@ -407,6 +533,15 @@ export function BuilderSetupContent({
           <BuilderConnectCta variant="compact" onConnected={onConnected} />
           <Link
             to={buildSettingsRoute(redesign.enabled ? "model" : "keys")}
+            state={{ providerSetupTrackingFlow: "chat_setup" }}
+            onClick={() =>
+              trackSetupFunnelEvent(
+                "integration_method_clicked",
+                "custom_keys",
+                "click",
+                "started",
+              )
+            }
             className={cn(
               "agent-builder-setup-card__key-button inline-flex shrink-0 items-center whitespace-nowrap rounded-md text-[11px] font-medium",
               sidebarLayout
@@ -445,6 +580,18 @@ export function BuilderSetupCard({
   const t = useT();
   const retryRequestedRef = useRef(false);
   const [retryRequested, setRetryRequested] = useState(false);
+  const exposureTrackedRef = useRef(false);
+
+  useEffect(() => {
+    if (exposureTrackedRef.current) return;
+    exposureTrackedRef.current = true;
+    trackSetupFunnelEvent(
+      "integration_setup_exposed",
+      "setup_card",
+      "view",
+      "exposed",
+    );
+  }, []);
 
   const handleRetry = useCallback(() => {
     if (!onRetry || retryRequestedRef.current) return;
@@ -732,7 +879,10 @@ export function RunErrorRecoveryCard({
               terminal: t("agentChat.error.failed"),
             })}
           </div>
-          <p className="mt-1 whitespace-pre-wrap break-words text-xs leading-relaxed text-muted-foreground">
+          <p
+            {...SESSION_REPLAY_MASK_PROPS}
+            className="mt-1 whitespace-pre-wrap break-words text-xs leading-relaxed text-muted-foreground"
+          >
             {localizeKnownChatErrorText(info.message, t)}
           </p>
           {shouldShowBuilderReconnect && !builderReconnectResolved && (
@@ -771,7 +921,10 @@ export function RunErrorRecoveryCard({
               {info.runId && <div>run: {info.runId}</div>}
               {info.errorCode && <div>code: {info.errorCode}</div>}
               {info.details && (
-                <pre className="mt-2 max-h-28 overflow-auto whitespace-pre-wrap break-words font-mono">
+                <pre
+                  {...SESSION_REPLAY_MASK_PROPS}
+                  className="mt-2 max-h-28 overflow-auto whitespace-pre-wrap break-words font-mono"
+                >
                   {info.details}
                 </pre>
               )}
@@ -898,12 +1051,20 @@ export function RunErrorRecoveryCard({
         </div>
       </div>
       {shouldShowBuilderReconnect && builderReconnect.error && (
-        <p className="mt-2 text-xs leading-relaxed text-red-500">
+        <p
+          {...SESSION_REPLAY_MASK_PROPS}
+          className="mt-2 text-xs leading-relaxed text-destructive"
+        >
           {builderReconnect.error}
         </p>
       )}
       {forkError && (
-        <p className="mt-2 text-xs leading-relaxed text-red-500">{forkError}</p>
+        <p
+          {...SESSION_REPLAY_MASK_PROPS}
+          className="mt-2 text-xs leading-relaxed text-destructive"
+        >
+          {forkError}
+        </p>
       )}
       {continueError && (
         <p className="mt-2 text-xs leading-relaxed text-destructive">
@@ -1102,7 +1263,14 @@ export function LoopLimitContinueCard({
           {t("agentChat.limit.ownerOnly")}
         </p>
       )}
-      {error && <p className="mt-2 text-[11px] text-destructive">{error}</p>}
+      {error && (
+        <p
+          {...SESSION_REPLAY_MASK_PROPS}
+          className="mt-2 text-[11px] text-destructive"
+        >
+          {error}
+        </p>
+      )}
     </div>
   );
 }

package/src/app/chat/chat/tool-call-display.spec.tsx

@@ -5,6 +5,7 @@ import {
   AgentNativeI18nProvider as CoreAgentNativeI18nProvider,
   type AgentNativeI18nProviderProps,
 } from "@agent-native/core/client/i18n";
+import { SESSION_REPLAY_BLOCK_ATTRIBUTE } from "@agent-native/core/client/session-replay-privacy";
 import type { AgentMcpAppPayload } from "@agent-native/core/mcp-client";
 import { act, useState, type ReactNode } from "react";
 import { createRoot, type Root } from "react-dom/client";
@@ -428,6 +429,14 @@ describe("ToolCallDisplay native renderers", () => {
 
     expect(disclosure?.getAttribute("aria-expanded")).toBe("true");
     expect(container.textContent).toContain(errorMessage);
+    expect(
+      Array.from(container.querySelectorAll("[data-an-mask]")).some(
+        (element) => element.textContent === errorMessage,
+      ),
+    ).toBe(true);
+    for (const button of container.querySelectorAll("button[aria-expanded]")) {
+      expect(button.closest("[data-an-mask]")).toBeNull();
+    }
   });
 
   it("shows regular tool errors only after explicitly expanding the call", () => {
@@ -456,6 +465,14 @@ describe("ToolCallDisplay native renderers", () => {
 
     expect(disclosure?.getAttribute("aria-expanded")).toBe("true");
     expect(container.textContent).toContain(errorMessage);
+    expect(
+      Array.from(container.querySelectorAll("[data-an-mask]")).some(
+        (element) => element.textContent === errorMessage,
+      ),
+    ).toBe(true);
+    for (const button of container.querySelectorAll("button[aria-expanded]")) {
+      expect(button.closest("[data-an-mask]")).toBeNull();
+    }
     expect(container.querySelector(".text-destructive")).toBeNull();
   });
 
@@ -489,6 +506,14 @@ describe("ToolCallDisplay native renderers", () => {
     act(() => disclosure?.click());
 
     expect(container.textContent).toContain(errorMessage);
+    expect(
+      Array.from(container.querySelectorAll("[data-an-mask]")).some(
+        (element) => element.textContent === errorMessage,
+      ),
+    ).toBe(true);
+    for (const button of container.querySelectorAll("button[aria-expanded]")) {
+      expect(button.closest("[data-an-mask]")).toBeNull();
+    }
   });
 
   it("bypasses native tool renderers for failures and keeps details collapsed", () => {
@@ -521,6 +546,14 @@ describe("ToolCallDisplay native renderers", () => {
     act(() => disclosure?.click());
 
     expect(container.textContent).toContain(errorMessage);
+    expect(
+      Array.from(container.querySelectorAll("[data-an-mask]")).some(
+        (element) => element.textContent === errorMessage,
+      ),
+    ).toBe(true);
+    for (const button of container.querySelectorAll("button[aria-expanded]")) {
+      expect(button.closest("[data-an-mask]")).toBeNull();
+    }
     expect(container.querySelector(".text-destructive")).toBeNull();
   });
 
@@ -599,6 +632,14 @@ describe("ToolCallDisplay native renderers", () => {
 
     expect(subtool?.getAttribute("aria-expanded")).toBe("true");
     expect(container.textContent).toContain(errorMessage);
+    expect(
+      Array.from(container.querySelectorAll("[data-an-mask]")).some(
+        (element) => element.textContent === errorMessage,
+      ),
+    ).toBe(true);
+    for (const button of container.querySelectorAll("button[aria-expanded]")) {
+      expect(button.closest("[data-an-mask]")).toBeNull();
+    }
   });
 
   it("keeps failed delegated subtools expandable without error text", () => {
@@ -802,6 +843,14 @@ describe("ToolCallDisplay native renderers", () => {
 
     expect(disclosure?.getAttribute("aria-expanded")).toBe("true");
     expect(container.textContent).toContain(errorMessage);
+    expect(
+      Array.from(container.querySelectorAll("[data-an-mask]")).some(
+        (element) => element.textContent === errorMessage,
+      ),
+    ).toBe(true);
+    for (const button of container.querySelectorAll("button[aria-expanded]")) {
+      expect(button.closest("[data-an-mask]")).toBeNull();
+    }
     expect(container.querySelector(".text-destructive")).toBeNull();
   });
 
@@ -1695,6 +1744,34 @@ describe("ToolCallDisplay native renderers", () => {
     expect(container.textContent).not.toContain("MCP APP");
   });
 
+  it.each([true, false])(
+    "blocks only an errored MCP App from replays (isError %s)",
+    (isError) => {
+      act(() => {
+        root.render(
+          <ToolCallDisplay
+            toolName="external-widget"
+            args={{}}
+            result={
+              isError
+                ? "Error running external-widget: Example Document failed."
+                : JSON.stringify({ ok: true })
+            }
+            mcpApp={mcpApp}
+            isRunning={false}
+            isError={isError}
+          />,
+        );
+      });
+
+      const app = container.querySelector('[data-testid="mcp-app"]');
+      expect(app).not.toBeNull();
+      expect(app?.closest(`[${SESSION_REPLAY_BLOCK_ATTRIBUTE}]`) !== null).toBe(
+        isError,
+      );
+    },
+  );
+
   it("renders MCP Apps when there is no native widget payload", () => {
     act(() => {
       root.render(

package/src/app/chat/chat/tool-call-display.tsx

@@ -51,6 +51,10 @@ import { AgentTaskCard } from "../AgentTaskCard.js";
 import { ConnectBuilderCard } from "../ConnectBuilderCard.js";
 import { FileStorageSetupPopover } from "../FileStorageSetupPopover.js";
 import { McpAppRenderer } from "../mcp-apps/McpAppRenderer.js";
+import {
+  SESSION_REPLAY_BLOCK_PROPS,
+  SESSION_REPLAY_MASK_PROPS,
+} from "../session-replay-privacy.js";
 import { useThinkingDisplay } from "../thinking-display.js";
 import {
   BashCell,
@@ -980,9 +984,13 @@ function ToolCallDisplayGeneric({
 
   return (
     <div className="group/tool my-0.5 w-full overflow-hidden">
-      {mcpApp && !(suppressInlineOpenApp && toolName === "open_app") && (
-        <McpAppRenderer app={mcpApp} className="mb-1.5" />
-      )}
+      {mcpApp &&
+        !(suppressInlineOpenApp && toolName === "open_app") && (
+          // The recorder keeps iframe attributes, and a snapshot's srcdoc can show the failure.
+          <div {...(isError ? SESSION_REPLAY_BLOCK_PROPS : {})}>
+            <McpAppRenderer app={mcpApp} className="mb-1.5" />
+          </div>
+        )}
       <button
         type="button"
         onClick={() => canExpand && setExpanded(!isExpanded)}
@@ -1079,7 +1087,10 @@ function ToolCallDisplayGeneric({
             />
           )}
           {isError ? (
-            <div className="max-h-56 overflow-auto whitespace-pre-wrap break-words rounded-md bg-muted/70 px-2.5 py-1 text-xs text-muted-foreground">
+            <div
+              {...SESSION_REPLAY_MASK_PROPS}
+              className="max-h-56 overflow-auto whitespace-pre-wrap break-words rounded-md bg-muted/70 px-2.5 py-1 text-xs text-muted-foreground"
+            >
               {result || t("agentChat.tool.failedWithoutDetails")}
             </div>
           ) : resultPayload ? (
@@ -1289,7 +1300,10 @@ function AgentCallCell({
             </div>
           )}
           {isError && errorText ? (
-            <div className="max-h-56 overflow-auto whitespace-pre-wrap break-words rounded-md bg-muted/70 px-2.5 py-1 text-xs text-muted-foreground">
+            <div
+              {...SESSION_REPLAY_MASK_PROPS}
+              className="max-h-56 overflow-auto whitespace-pre-wrap break-words rounded-md bg-muted/70 px-2.5 py-1 text-xs text-muted-foreground"
+            >
               {errorText}
             </div>
           ) : null}
@@ -1372,7 +1386,10 @@ function AgentActivityToolCallRow({
             />
           </button>
           <AnimatedCollapse open={open}>
-            <div className="max-h-56 overflow-auto whitespace-pre-wrap break-words rounded-md bg-muted/70 px-2.5 py-1 text-xs text-muted-foreground">
+            <div
+              {...SESSION_REPLAY_MASK_PROPS}
+              className="max-h-56 overflow-auto whitespace-pre-wrap break-words rounded-md bg-muted/70 px-2.5 py-1 text-xs text-muted-foreground"
+            >
               {failureDetails}
             </div>
           </AnimatedCollapse>

package/src/app/chat/chat-first/ChatFirstAgentActivityPanel.tsx

@@ -19,6 +19,7 @@ import {
 } from "@tabler/icons-react";
 import { useState } from "react";
 
+import { SESSION_REPLAY_MASK_PROPS } from "../session-replay-privacy.js";
 import { defaultChatFirstCopy } from "./copy.js";
 import type { ChatFirstCopy } from "./types.js";
 
@@ -111,7 +112,7 @@ export function ChatFirstAgentActivityPanel({
           data-chat-first-agents-error
         >
           <IconAlertCircle size={15} aria-hidden="true" />
-          <span>{error}</span>
+          <span {...SESSION_REPLAY_MASK_PROPS}>{error}</span>
           {onRefresh ? (
             <button
               type="button"