@agent-native/toolkit 0.203.2-nightly-20261007213109 → 0.204.0

package/src/app/onboarding/FirstRunOnboarding.spec.tsx

@@ -587,6 +587,159 @@ describe("FirstRunOnboarding", () => {
     expect(flow.cancel).toHaveBeenCalledOnce();
   });
 
+  it("keeps Cancel during a failed status poll without offering a fake retry", () => {
+    const flow = {
+      hasFetchedStatus: true,
+      statusResolved: false,
+      configured: false,
+      agentNativeProvisioningEnabled: true,
+      connecting: false,
+      statusUnavailable: true,
+      terminalError: null,
+      error: "Couldn't check the Builder.io connection.",
+      start: vi.fn(),
+      cancel: vi.fn(),
+      retry: vi.fn(),
+    };
+    flow.start.mockImplementation(() => {
+      flow.connecting = true;
+    });
+    mocks.useBuilderConnectFlow.mockReturnValue(flow);
+
+    act(() => {
+      root.render(
+        <TooltipProvider>
+          <FirstRunOnboarding />
+        </TooltipProvider>,
+      );
+    });
+    act(() => {
+      document.body
+        .querySelector("[data-testid='first-run-role-skip']")
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    act(() => {
+      document.body
+        .querySelector("[data-testid='first-run-builder-create-account']")
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    expect(document.body.textContent).toContain(
+      "Couldn't check the Builder.io connection.",
+    );
+    expect(
+      document.body.querySelector('[data-testid="first-run-cancel-builder"]'),
+    ).not.toBeNull();
+    expect(
+      [...document.body.querySelectorAll("button")].some(
+        (button) => button.textContent === "Try again",
+      ),
+    ).toBe(false);
+
+    act(() => {
+      document.body
+        .querySelector<HTMLButtonElement>(
+          '[data-testid="first-run-cancel-builder"]',
+        )
+        ?.click();
+    });
+    expect(flow.cancel).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    {
+      mode: "provision",
+      choiceId: "first-run-builder-create-account",
+      provisionAccount: true,
+      failure: "transient status read failure",
+      statusUnavailable: true,
+      terminalError: null,
+      error: "Couldn't check the Builder.io connection.",
+    },
+    {
+      mode: "existing",
+      choiceId: "first-run-builder-sign-in",
+      provisionAccount: false,
+      failure: "transient status read failure",
+      statusUnavailable: true,
+      terminalError: null,
+      error: "Couldn't check the Builder.io connection.",
+    },
+    {
+      mode: "provision",
+      choiceId: "first-run-builder-create-account",
+      provisionAccount: true,
+      failure: "terminal connection error",
+      statusUnavailable: true,
+      terminalError: "Builder connection failed.",
+      error: "Builder connection failed.",
+    },
+    {
+      mode: "existing",
+      choiceId: "first-run-builder-sign-in",
+      provisionAccount: false,
+      failure: "terminal connection error",
+      statusUnavailable: true,
+      terminalError: "Builder connection failed.",
+      error: "Builder connection failed.",
+    },
+  ])(
+    "restarts the prior $mode mode after a $failure",
+    ({
+      choiceId,
+      provisionAccount,
+      statusUnavailable,
+      terminalError,
+      error,
+    }) => {
+      const start = vi.fn();
+      mocks.useBuilderConnectFlow.mockReturnValue({
+        hasFetchedStatus: true,
+        statusResolved: true,
+        configured: false,
+        agentNativeProvisioningEnabled: true,
+        connecting: false,
+        statusUnavailable,
+        terminalError,
+        error,
+        start,
+        cancel: vi.fn(),
+        retry: vi.fn(),
+      });
+
+      act(() => {
+        root.render(
+          <TooltipProvider>
+            <FirstRunOnboarding />
+          </TooltipProvider>,
+        );
+      });
+      act(() => {
+        document.body
+          .querySelector("[data-testid='first-run-role-skip']")
+          ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      });
+      act(() => {
+        document.body
+          .querySelector(`[data-testid='${choiceId}']`)
+          ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      });
+
+      expect(start).toHaveBeenCalledOnce();
+      expect(document.body.textContent).toContain(error);
+      act(() => {
+        [...document.body.querySelectorAll("button")]
+          .find((button) => button.textContent === "Try again")
+          ?.click();
+      });
+
+      expect(start).toHaveBeenCalledTimes(2);
+      expect(start).toHaveBeenLastCalledWith(
+        expect.objectContaining({ provisionAccount }),
+      );
+    },
+  );
+
   it("creates a Builder account from the primary button and shows its loading state", () => {
     const flow = {
       hasFetchedStatus: true,
@@ -760,7 +913,7 @@ describe("FirstRunOnboarding", () => {
     expect(JSON.stringify(outcome)).not.toContain("Error:");
   });
 
-  it("does not attach a stale Builder error to a later manual setup attempt", async () => {
+  it("does not attach a status-read failure to a manual setup attempt", async () => {
     const flow = {
       hasFetchedStatus: true,
       statusResolved: true,
@@ -768,8 +921,9 @@ describe("FirstRunOnboarding", () => {
       agentNativeProvisioningEnabled: true,
       accountExists: false,
       connecting: false,
-      error: null as string | null,
-      start: vi.fn(),
+      statusUnavailable: true,
+      terminalError: null,
+      error: "Couldn't check the Builder.io connection.",
     };
     let resolveCompletion: (() => void) | undefined;
     mocks.completeFirstRun.mockImplementation(
@@ -792,25 +946,6 @@ describe("FirstRunOnboarding", () => {
         .querySelector("[data-testid='first-run-role-skip']")
         ?.click();
     });
-    act(() => {
-      document.body
-        .querySelector("[data-testid='first-run-builder-create-account']")
-        ?.click();
-    });
-
-    flow.error = "stale Builder error";
-    act(() => {
-      root.render(
-        <TooltipProvider>
-          <FirstRunOnboarding />
-        </TooltipProvider>,
-      );
-    });
-    act(() => {
-      [...document.body.querySelectorAll("button")]
-        .find((button) => button.textContent === "Try again")
-        ?.click();
-    });
 
     await act(async () => {
       document.body
@@ -818,7 +953,7 @@ describe("FirstRunOnboarding", () => {
         ?.click();
       await Promise.resolve();
     });
-    flow.error = "stale Builder error changed";
+    flow.error = "Builder status still unavailable.";
     act(() => {
       root.render(
         <TooltipProvider>
@@ -1534,7 +1669,7 @@ describe("FirstRunOnboarding", () => {
     expect(document.body.textContent).not.toMatch(/\bProduct\b/);
   });
 
-  it("keeps the create-account CTA actionable after a failed status read", () => {
+  it("keeps setup choices clear and actionable after a failed status read", () => {
     const start = vi.fn();
     const retry = vi.fn();
     mocks.useBuilderConnectFlow.mockReturnValue({
@@ -1544,7 +1679,8 @@ describe("FirstRunOnboarding", () => {
       agentNativeProvisioningEnabled: true,
       accountExists: false,
       connecting: false,
-      error: "Couldn't reach Builder to check your account. Retrying.",
+      statusUnavailable: true,
+      error: "Couldn't check the Builder.io connection.",
       retry,
       start,
     });
@@ -1565,8 +1701,8 @@ describe("FirstRunOnboarding", () => {
     expect(
       document.body.querySelector(
         '[data-testid="first-run-builder-status-error"]',
-      )?.textContent,
-    ).toContain("Couldn't reach Builder");
+      ),
+    ).toBeNull();
 
     const cta = document.body.querySelector(
       '[data-testid="first-run-builder-create-account"]',

package/src/app/onboarding/FirstRunOnboarding.tsx

@@ -464,10 +464,14 @@ export function FirstRunOnboarding({
       trackFirstRunSetupOutcome(attempt, "failed", "account_exists");
       return;
     }
-    if (connectFlow.error) {
+    if (connectFlow.terminalError) {
       trackFirstRunSetupOutcome(attempt, "failed", "connection_error");
     }
-  }, [connectFlow.accountExists, connectFlow.connecting, connectFlow.error]);
+  }, [
+    connectFlow.accountExists,
+    connectFlow.connecting,
+    connectFlow.terminalError,
+  ]);
   const canActivateBuilderFreeCredits =
     connectFlow.agentNativeProvisioningEnabled;
   const retryOnboardingCompletion = useCallback(() => {
@@ -746,15 +750,6 @@ export function FirstRunOnboarding({
                     {t("agentChat.onboarding.builderSignInWithAccount")}
                   </button>
                 </div>
-                {connectFlow.error && !connectFlow.statusResolved && (
-                  <p
-                    role="status"
-                    data-testid="first-run-builder-status-error"
-                    className="text-center text-xs text-destructive"
-                  >
-                    {connectFlow.error}
-                  </p>
-                )}
               </section>
 
               <section className="flex flex-col gap-5 rounded-2xl border border-border bg-card p-6">
@@ -996,18 +991,40 @@ export function FirstRunOnboarding({
                 {t("common.cancel")}
               </button>
             )}
-            {connectFlow.error && (
-              <div className="mt-4 flex flex-col items-center gap-2">
-                <p className="text-xs text-destructive">{connectFlow.error}</p>
-                <button
-                  type="button"
-                  className={secondaryButtonClass}
-                  onClick={() => setScreen("choice")}
-                >
-                  Try again
-                </button>
-              </div>
+            {connectFlow.statusUnavailable &&
+              connectFlow.connecting &&
+              !connectFlow.terminalError && (
+                <p className="mt-4 text-xs text-destructive" role="alert">
+                  {t(
+                    "agentChat.settingsShell.integrations.builderStatusFailed",
+                  )}
+                </p>
+              )}
+            {connectFlow.terminalError && connectFlow.connecting && (
+              <p className="mt-4 text-xs text-destructive" role="alert">
+                {connectFlow.terminalError}
+              </p>
             )}
+            {!connectFlow.connecting &&
+              (connectFlow.statusUnavailable || connectFlow.terminalError) && (
+                <div className="mt-4 flex flex-col items-center gap-2">
+                  <p className="text-xs text-destructive" role="alert">
+                    {connectFlow.terminalError ??
+                      t(
+                        "agentChat.settingsShell.integrations.builderStatusFailed",
+                      )}
+                  </p>
+                  <button
+                    type="button"
+                    className={secondaryButtonClass}
+                    onClick={() =>
+                      handleBuilder(builderConnectionMode === "provision")
+                    }
+                  >
+                    Try again
+                  </button>
+                </div>
+              )}
           </>
         )}
       </div>

package/src/app/settings/useBuilderStatus.spec.tsx

@@ -103,6 +103,12 @@ function BuilderConnectProbeContent({
       <output data-testid="credential-source">
         {flow.credentialSource ?? "none"}
       </output>
+      <output data-testid="status-unavailable">
+        {flow.statusUnavailable ? "unavailable" : "available"}
+      </output>
+      <output data-testid="terminal-error">
+        {flow.terminalError ?? "none"}
+      </output>
       <output>{flow.error ?? ""}</output>
     </div>
   );
@@ -1644,8 +1650,15 @@ describe("useBuilderConnectFlow", () => {
     await flushAfterPaint();
 
     expect(container.textContent).toContain("not-configured idle unresolved");
+    expect(
+      container.querySelector('[data-testid="status-unavailable"]')
+        ?.textContent,
+    ).toBe("unavailable");
+    expect(
+      container.querySelector('[data-testid="terminal-error"]')?.textContent,
+    ).toBe("none");
     expect(container.textContent).toContain(
-      "Couldn't reach Builder to check your account.",
+      "Couldn't check the Builder.io connection.",
     );
 
     await act(async () => {
@@ -1655,7 +1668,16 @@ describe("useBuilderConnectFlow", () => {
     });
 
     expect(container.textContent).toContain("not-configured idle resolved");
-    expect(container.textContent).not.toContain("Couldn't reach Builder");
+    expect(
+      container.querySelector('[data-testid="status-unavailable"]')
+        ?.textContent,
+    ).toBe("available");
+    expect(
+      container.querySelector('[data-testid="terminal-error"]')?.textContent,
+    ).toBe("none");
+    expect(container.textContent).not.toContain(
+      "Couldn't check the Builder.io connection.",
+    );
   });
 
   it("shows the chooser without navigating when status cannot be resolved", async () => {

package/src/app/settings/useBuilderStatus.ts

@@ -268,6 +268,10 @@ export interface BuilderConnectFlow {
   orgName: string | null;
   connecting: boolean;
   error: string | null;
+  /** The most recent terminal Builder connection attempt error, if any. */
+  terminalError: string | null;
+  /** The most recent Builder connection-status read failed. */
+  statusUnavailable: boolean;
   accountExists: boolean;
   hasFetchedStatus: boolean;
   start: (options?: BuilderConnectStartOptions) => void;
@@ -281,8 +285,6 @@ const POLL_TIMEOUT_MS = 5 * 60 * 1000;
 export const POPUP_CLOSED_CONFIRMATION_GRACE_MS = 20_000;
 const POPUP_LOAD_TIMEOUT_MS = 20_000;
 const STATUS_FETCH_ABORT_MS = 10_000;
-const BUILDER_STATUS_UNAVAILABLE_MESSAGE =
-  "Couldn't reach Builder to check your account. Retrying.";
 const CALLBACK_SUCCESS_STATUS_RETRY_MS = 500;
 const CALLBACK_SUCCESS_STATUS_RETRIES = 10;
 const BUILDER_CONNECT_PARAM = "_an_connect";
@@ -841,6 +843,7 @@ export function useBuilderConnectFlow(
   const [orgName, setOrgName] = useState<string | null>(null);
   const [connecting, setConnecting] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [statusUnavailable, setStatusUnavailable] = useState(false);
   const [accountExists, setAccountExists] = useState(false);
   const [hasFetchedStatus, setHasFetchedStatus] = useState(false);
   const [statusResolved, setStatusResolved] = useState(false);
@@ -868,6 +871,14 @@ export function useBuilderConnectFlow(
   } | null>(null);
   const retryStatusRef = useRef<() => boolean>(() => false);
   const statusUnavailableRef = useRef(false);
+  const markStatusUnavailable = useCallback(() => {
+    statusUnavailableRef.current = true;
+    setStatusUnavailable(true);
+  }, []);
+  const markStatusAvailable = useCallback(() => {
+    statusUnavailableRef.current = false;
+    setStatusUnavailable(false);
+  }, []);
   const statusPollFailuresRef = useRef(0);
   const mountedRef = useRef(true);
   const notifiedConnectedRef = useRef(false);
@@ -1018,6 +1029,7 @@ export function useBuilderConnectFlow(
       setOrgName(null);
       setConnecting(false);
       setError(null);
+      markStatusAvailable();
       setAccountExists(false);
       setHasFetchedStatus(false);
       setStatusResolved(false);
@@ -1039,13 +1051,11 @@ export function useBuilderConnectFlow(
       setHasFetchedStatus(true);
       setStatusReadSettledCount((count) => count + 1);
       if (!s) {
-        statusUnavailableRef.current = true;
-        setError(BUILDER_STATUS_UNAVAILABLE_MESSAGE);
+        markStatusUnavailable();
         return;
       }
       if (statusUnavailableRef.current) {
-        statusUnavailableRef.current = false;
-        setError(null);
+        markStatusAvailable();
       }
       setStatusResolved(true);
       setConfigured(!!s.configured);
@@ -1123,7 +1133,13 @@ export function useBuilderConnectFlow(
       document.removeEventListener("visibilitychange", onVisible);
       window.removeEventListener("agent-engine:configured-changed", refreshNow);
     };
-  }, [enabled, fetchStatus, notifyProvisionedAccount]);
+  }, [
+    enabled,
+    fetchStatus,
+    markStatusAvailable,
+    markStatusUnavailable,
+    notifyProvisionedAccount,
+  ]);
 
   const retry = useCallback(() => retryStatusRef.current(), []);
   const cancel = useCallback(() => {
@@ -1254,6 +1270,11 @@ export function useBuilderConnectFlow(
         const freshProvisioningCredentials = async () => {
           // coercion-ok: no fresh token is sent as none and refused as provision_token_invalid
           const status = await fetchStatus();
+          if (!status) {
+            markStatusUnavailable();
+            return null;
+          }
+          markStatusAvailable();
           if (!status?.agentNativeProvisioningEnabled) return null;
           const freshUrl = status?.connectUrl ?? null;
           const freshConnectToken = freshUrl
@@ -1283,7 +1304,9 @@ export function useBuilderConnectFlow(
           if (!credentials) {
             connectStartedAtRef.current = null;
             setConnecting(false);
-            setError(t("agentChat.settingsShell.builder.setupStartFailed"));
+            if (!statusUnavailableRef.current) {
+              setError(t("agentChat.settingsShell.builder.setupStartFailed"));
+            }
             return;
           }
           let result = await activate(credentials);
@@ -1317,6 +1340,8 @@ export function useBuilderConnectFlow(
             // attempt with a retryable error.
             const status = await fetchStatus();
             if (!isCurrentAttempt()) return;
+            if (status) markStatusAvailable();
+            else markStatusUnavailable();
             if (
               status &&
               isBuilderConnectComplete(status, connectTargetRef.current)
@@ -1393,11 +1418,12 @@ export function useBuilderConnectFlow(
             cancelledConnectAttemptIdRef.current !== connectAttemptId;
           if (!isCurrentAttempt()) return;
           if (!status) {
+            markStatusUnavailable();
             connectStartedAtRef.current = null;
             setConnecting(false);
-            setError(BUILDER_STATUS_UNAVAILABLE_MESSAGE);
             return;
           }
+          markStatusAvailable();
           setHasFetchedStatus(true);
           setStatusResolved(true);
           setConfigured(!!status.configured);
@@ -1432,7 +1458,7 @@ export function useBuilderConnectFlow(
           ) {
             connectStartedAtRef.current = null;
             setConnecting(false);
-            setError(BUILDER_STATUS_UNAVAILABLE_MESSAGE);
+            setError(t("agentChat.settingsShell.builder.setupStartFailed"));
             return;
           }
           const result = await openDesktopConnectUrl({
@@ -1445,7 +1471,10 @@ export function useBuilderConnectFlow(
           if (!result?.ok) {
             connectStartedAtRef.current = null;
             setConnecting(false);
-            setError(result?.error ?? BUILDER_STATUS_UNAVAILABLE_MESSAGE);
+            setError(
+              result?.error ??
+                t("agentChat.settingsShell.builder.setupStartFailed"),
+            );
           }
         })();
       } else {
@@ -1474,6 +1503,8 @@ export function useBuilderConnectFlow(
             ) {
               return;
             }
+            if (s) markStatusAvailable();
+            else markStatusUnavailable();
             if (s) {
               setHasFetchedStatus(true);
               setStatusResolved(true);
@@ -1537,6 +1568,8 @@ export function useBuilderConnectFlow(
               }
               return;
             }
+            if (s) markStatusAvailable();
+            else markStatusUnavailable();
             if (s) {
               setHasFetchedStatus(true);
               setStatusResolved(true);
@@ -1619,6 +1652,8 @@ export function useBuilderConnectFlow(
       enabled,
       t,
       fetchStatus,
+      markStatusAvailable,
+      markStatusUnavailable,
       transport,
       agentNativeProvisioningEnabled,
       agentNativeProvisioningToken,
@@ -1645,14 +1680,12 @@ export function useBuilderConnectFlow(
         statusPollFailuresRef.current = 0;
       } else {
         statusPollFailuresRef.current += 1;
-        statusUnavailableRef.current = true;
-        setError(BUILDER_STATUS_UNAVAILABLE_MESSAGE);
+        markStatusUnavailable();
       }
       const orgName = s?.orgName ?? null;
       if (s) {
         if (statusUnavailableRef.current) {
-          statusUnavailableRef.current = false;
-          setError(null);
+          markStatusAvailable();
         }
         setHasFetchedStatus(true);
         setStatusResolved(true);
@@ -1862,6 +1895,7 @@ export function useBuilderConnectFlow(
         return;
       }
       if (!s) return;
+      markStatusAvailable();
       if (!isBuilderConnectComplete(s, connectTargetRef.current)) {
         const connectError = isCurrentConnectError(s?.connectError, started)
           ? s?.connectError
@@ -1981,7 +2015,7 @@ export function useBuilderConnectFlow(
       channel?.close();
       window.removeEventListener("message", handler);
     };
-  }, [fetchStatus, notifyProvisionedAccount]);
+  }, [fetchStatus, markStatusAvailable, notifyProvisionedAccount]);
 
   return {
     configured,
@@ -1999,7 +2033,13 @@ export function useBuilderConnectFlow(
     builderEnabled,
     orgName,
     connecting,
-    error,
+    terminalError: error,
+    error:
+      error ??
+      (statusUnavailable
+        ? t("agentChat.settingsShell.integrations.builderStatusFailed")
+        : null),
+    statusUnavailable,
     accountExists,
     hasFetchedStatus,
     start,