@agent-native/toolkit 0.207.0-nightly-20261011153008 → 0.207.0

package/src/app/i18n/catalogs/zh-TW.ts

@@ -146,8 +146,16 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.builderActivateTitle": "啟用免費額度",
   "onboarding.builderAccountExistsTitle": "您已有 Builder.io 帳戶",
   "onboarding.builderAccountExistsDescription": "登入以使用您的帳戶。",
+  "onboarding.builderActivationChecking": "正在確認是否可以建立新帳戶。",
+  "onboarding.builderActivationUnavailable":
+    "此應用程式未啟用新帳戶建立功能。你仍可連結現有帳戶。",
+  "onboarding.builderActivationUnavailableInMode":
+    "此模式無法啟用新帳戶。你仍可連結現有帳戶。",
+  "onboarding.builderActivationCheckFailed":
+    "無法確認此應用程式是否可以建立新帳戶。",
+
   "onboarding.builderActivationDescription":
-    "按一下即可建立或連接 Builder.io 帳戶，取得免費額度。",
+    "建立新帳戶以啟用免費點數，或使用現有帳戶繼續。",
   "onboarding.builderOrgActivationDescription":
     "我們會一鍵建立您的 Builder.io 帳戶，讓您的組織可以使用。",
   "onboarding.builderCreateAndActivate": "建立並啟用",
@@ -155,7 +163,7 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.builderTerms": "服務條款",
   "onboarding.builderPrivacy": "隱私權政策",
   "onboarding.builderConsentAnd": "和",
-  "onboarding.builderExistingAccount": "使用 Builder.io",
+  "onboarding.builderExistingAccount": "我有 Builder.io 帳戶",
   "onboarding.builderActivating": "正在啟用 Builder.io 免費額度",
   "onboarding.builderConnecting": "正在設定 Builder.io 免費額度",
   "onboarding.builderProvisioningDescription":
@@ -1161,6 +1169,12 @@ const messages: ToolkitAgentChatTranslation = {
   "selection.attached": "已附加所選內容的 {{formattedCount}} 個字元",
   "selection.attached_other": "已附加所選內容的 {{formattedCount}} 個字元",
   "selection.clear": "清除所選內容的上下文",
+  "setup.addKeyInSettings": "在設定中新增金鑰",
+  "setup.addKeyInSettingsDescription": "供你的個人帳戶或組織使用。",
+  "setup.setEnvironmentVariable": "設定環境變數",
+  "setup.setEnvironmentVariableDescription":
+    "此應用程式的所有使用者共用一個供應商金鑰。",
+
   "setup.addOwnKeys": "加入您自己的金鑰",
   "setup.builderCredits":
     "Builder.io 提供免費額度，您也可以使用自己的 API 金鑰。",

package/src/app/onboarding/OnboardingBanner.tsx

@@ -1,6 +1,12 @@
+import { useT } from "@agent-native/core/client/i18n";
 import { useOnboarding } from "@agent-native/core/client/onboarding/use-onboarding";
-import { IconChecklist, IconChevronRight } from "@tabler/icons-react";
-import React from "react";
+import { Button } from "@agent-native/toolkit/ui/button";
+import {
+  IconChecklist,
+  IconChevronRight,
+  IconLoader2,
+} from "@tabler/icons-react";
+import React, { useState } from "react";
 
 interface OnboardingBannerProps {
   onContinue?: () => void;
@@ -11,9 +17,55 @@ export function OnboardingBanner({
   onContinue,
   className,
 }: OnboardingBannerProps) {
-  const { loading, totalCount, completeCount, allComplete, dismissed } =
-    useOnboarding();
-  if (loading || totalCount === 0 || allComplete || dismissed) return null;
+  const {
+    loading,
+    totalCount,
+    completeCount,
+    allComplete,
+    dismissed,
+    error,
+    summaryKnown,
+    refresh,
+  } = useOnboarding();
+  const t = useT();
+  const [retrying, setRetrying] = useState(false);
+
+  if (
+    loading ||
+    (summaryKnown && (dismissed || (totalCount > 0 && allComplete)))
+  ) {
+    return null;
+  }
+  if (error && (!summaryKnown || totalCount > 0)) {
+    const retry = async () => {
+      setRetrying(true);
+      try {
+        await refresh();
+      } finally {
+        setRetrying(false);
+      }
+    };
+
+    return (
+      <div role="alert" className={className} style={styles.error}>
+        <span>{t("agentChat.common.chunkLoadFailed")}</span>
+        <Button
+          type="button"
+          variant="outline"
+          size="xs"
+          data-testid="onboarding-summary-retry"
+          disabled={retrying}
+          onClick={() => void retry()}
+        >
+          {retrying ? (
+            <IconLoader2 className="animate-spin" aria-hidden />
+          ) : null}
+          {t("agentChat.common.retry")}
+        </Button>
+      </div>
+    );
+  }
+  if (!summaryKnown || totalCount === 0) return null;
 
   return (
     <button
@@ -38,6 +90,19 @@ export function OnboardingBanner({
 }
 
 const styles: Record<string, React.CSSProperties> = {
+  error: {
+    display: "flex",
+    flexWrap: "wrap",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 8,
+    width: "100%",
+    padding: "8px 12px",
+    borderBottom: "1px solid hsl(var(--border) / 0.7)",
+    background: "hsl(var(--muted) / 0.25)",
+    color: "hsl(var(--muted-foreground))",
+    fontSize: 12,
+  },
   root: {
     display: "flex",
     alignItems: "center",

package/src/app/onboarding/OnboardingPanel.save-scope.spec.tsx

@@ -8,15 +8,26 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 let steps: OnboardingStepStatus[] = [];
+let onboardingError: string | null = null;
+let dismissed = false;
+let summaryKnown = true;
+let refresh = vi.fn(async () => {});
 vi.mock("@agent-native/core/client/onboarding/use-onboarding", () => ({
   createOnboardingCorrelationId: () => "test-onboarding-correlation-id",
   trackOnboardingEvent: vi.fn(),
   useOnboarding: () => ({
     steps,
     currentStepId: steps[0]?.id ?? null,
-    dismissed: false,
+    completeCount: steps.filter((step) => step.complete).length,
+    totalCount: steps.length,
+    allComplete:
+      steps.length > 0 &&
+      steps.filter((step) => step.required).every((step) => step.complete),
+    dismissed,
+    summaryKnown,
     loading: false,
-    refresh: async () => {},
+    error: onboardingError,
+    refresh,
     complete: vi.fn(),
     dismiss: vi.fn(),
   }),
@@ -28,6 +39,7 @@ vi.mock("@agent-native/core/client/use-dev-mode", () => ({
   useDevMode: () => ({ isDevMode: false }),
 }));
 
+import { OnboardingBanner } from "./OnboardingBanner.js";
 import { OnboardingPanel } from "./OnboardingPanel.js";
 
 function json(body: unknown): Response {
@@ -69,9 +81,30 @@ afterEach(() => {
   container?.remove();
   root = null;
   container = null;
+  steps = [];
+  onboardingError = null;
+  dismissed = false;
+  summaryKnown = true;
+  refresh = vi.fn(async () => {});
   vi.unstubAllGlobals();
 });
 
+async function renderOnboarding(child: React.ReactNode): Promise<void> {
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  await act(async () => {
+    root!.render(
+      <QueryClientProvider client={queryClient}>
+        <TooltipProvider>{child}</TooltipProvider>
+      </QueryClientProvider>,
+    );
+  });
+}
+
 async function saveAs(
   role: "member" | "admin",
   saveTo?: "scoped-secrets",
@@ -156,4 +189,112 @@ describe("onboarding form save scope", () => {
     const [secretSave] = await saveAs("admin", "scoped-secrets");
     expect(secretSave.body.scope).toBe("workspace");
   });
+
+  it("shows retry only when the initial summary is unavailable", async () => {
+    steps = [formStep()];
+    onboardingError = "summary: 503";
+    summaryKnown = false;
+    refresh = vi.fn(async () => {});
+    await renderOnboarding(<OnboardingPanel />);
+
+    const retry = container?.querySelector<HTMLButtonElement>(
+      '[data-testid="onboarding-summary-retry"]',
+    );
+    expect(container?.querySelector('[role="alert"]')).not.toBeNull();
+    expect(container?.textContent).not.toContain("Example keys");
+    expect(retry).not.toBeNull();
+    await act(async () => retry?.click());
+    expect(refresh).toHaveBeenCalledOnce();
+  });
+
+  it("keeps known steps visible while showing a summary retry state", async () => {
+    steps = [formStep()];
+    onboardingError = "summary: 503";
+    await renderOnboarding(<OnboardingPanel />);
+
+    expect(container?.querySelector('[role="alert"]')).not.toBeNull();
+    expect(container?.textContent).toContain("Example keys");
+    expect(
+      container?.querySelector('[data-testid="onboarding-summary-retry"]'),
+    ).not.toBeNull();
+  });
+
+  it("shows a retry-only banner when the initial summary is unavailable", async () => {
+    steps = [formStep()];
+    onboardingError = "summary: 503";
+    summaryKnown = false;
+    refresh = vi.fn(async () => {});
+    await renderOnboarding(<OnboardingBanner />);
+
+    const retry = container?.querySelector<HTMLButtonElement>(
+      '[data-testid="onboarding-summary-retry"]',
+    );
+    expect(container?.querySelector('[role="alert"]')).not.toBeNull();
+    expect(container?.textContent).not.toContain("Example keys");
+    expect(container?.textContent).not.toContain("Continue");
+    expect(retry).not.toBeNull();
+    await act(async () => retry?.click());
+    expect(refresh).toHaveBeenCalledOnce();
+  });
+
+  it("shows a retry action on the banner for a known active summary", async () => {
+    steps = [formStep()];
+    onboardingError = "summary: 503";
+    summaryKnown = true;
+    refresh = vi.fn(async () => {});
+    await renderOnboarding(<OnboardingBanner />);
+
+    const retry = container?.querySelector<HTMLButtonElement>(
+      '[data-testid="onboarding-summary-retry"]',
+    );
+    expect(container?.querySelector('[role="alert"]')).not.toBeNull();
+    expect(retry).not.toBeNull();
+    await act(async () => retry?.click());
+    expect(refresh).toHaveBeenCalledOnce();
+  });
+
+  it("hides summary errors after onboarding is dismissed", async () => {
+    dismissed = true;
+    summaryKnown = true;
+    onboardingError = "summary: 503";
+
+    await renderOnboarding(
+      <>
+        <OnboardingBanner />
+        <OnboardingPanel />
+      </>,
+    );
+    expect(container?.querySelector('[role="alert"]')).toBeNull();
+  });
+
+  it("hides summary errors after all required steps are complete", async () => {
+    steps = [{ ...formStep(), complete: true }];
+    summaryKnown = true;
+    onboardingError = "summary: 503";
+
+    await renderOnboarding(
+      <>
+        <OnboardingBanner />
+        <OnboardingPanel />
+      </>,
+    );
+    expect(container?.querySelector('[role="alert"]')).toBeNull();
+  });
+
+  it("keeps the retry notice visible while the panel is collapsed", async () => {
+    steps = [formStep()];
+    summaryKnown = true;
+    onboardingError = "summary: 503";
+    await renderOnboarding(<OnboardingPanel />);
+
+    const collapse = container?.querySelector<HTMLButtonElement>(
+      '[aria-label="Collapse onboarding"]',
+    );
+    await act(async () => collapse?.click());
+
+    expect(container?.querySelector('[role="alert"]')).not.toBeNull();
+    expect(
+      container?.querySelector('[data-testid="onboarding-summary-retry"]'),
+    ).not.toBeNull();
+  });
 });

package/src/app/onboarding/OnboardingPanel.tsx

@@ -12,6 +12,7 @@ import type {
   OnboardingMethod,
   OnboardingStepStatus,
 } from "@agent-native/core/onboarding/types";
+import { Button } from "@agent-native/toolkit/ui/button";
 import {
   Tooltip,
   TooltipContent,
@@ -56,10 +57,13 @@ export function OnboardingPanel({
     currentStepId: rawCurrentStepId,
     dismissed,
     loading,
+    error,
+    summaryKnown,
     refresh,
     complete,
     dismiss,
   } = onboarding;
+  const t = useT();
   const DEV_ONLY_STEP_IDS = new Set(["database", "auth"]);
   const steps = isDevMode
     ? rawSteps
@@ -75,6 +79,7 @@ export function OnboardingPanel({
   const checklistVisible =
     !loading && totalCount > 0 && (previewMode || (!dismissed && !allComplete));
   const [expanded, setExpanded] = useState(true);
+  const [retrying, setRetrying] = useState(false);
   const stepViewRef = useRef<{ key: string; id: string } | null>(null);
 
   useEffect(() => {
@@ -102,12 +107,58 @@ export function OnboardingPanel({
     });
   }, [checklistVisible, currentStepId, expanded, previewMode, steps]);
 
-  if (loading || totalCount === 0) return null;
-  if (!previewMode) {
-    if (dismissed) return null;
-    if (allComplete) return null;
-  }
+  const handleRetry = async () => {
+    setRetrying(true);
+    try {
+      await refresh();
+    } finally {
+      setRetrying(false);
+    }
+  };
+  const errorNotice =
+    error &&
+    (previewMode ||
+      !summaryKnown ||
+      (totalCount > 0 && !dismissed && !allComplete)) ? (
+      <div role="alert" style={styles.errorNotice}>
+        <span>{t("agentChat.common.chunkLoadFailed")}</span>
+        <Button
+          type="button"
+          variant="outline"
+          size="xs"
+          data-testid="onboarding-summary-retry"
+          disabled={retrying}
+          onClick={() => void handleRetry()}
+        >
+          {retrying ? (
+            <IconLoader2 className="animate-spin" aria-hidden />
+          ) : null}
+          {t("agentChat.common.retry")}
+        </Button>
+      </div>
+    ) : null;
 
+  if (loading) return null;
+  if (!previewMode && !summaryKnown) {
+    if (!errorNotice) return null;
+    return (
+      <div className={className} style={styles.errorOnly}>
+        {errorNotice}
+      </div>
+    );
+  }
+  if (!previewMode && (dismissed || (totalCount > 0 && allComplete))) {
+    return null;
+  }
+  if (error && totalCount === 0) {
+    if (!errorNotice) return null;
+    return (
+      <div className={className} style={styles.errorOnly}>
+        {errorNotice}
+      </div>
+    );
+  }
+  if (totalCount === 0) return null;
   if (!expanded) {
     return (
       <div className={className} style={styles.compactBanner}>
@@ -139,6 +190,7 @@ export function OnboardingPanel({
           </TooltipTrigger>
           <TooltipContent>Expand setup</TooltipContent>
         </Tooltip>
+        {errorNotice}
       </div>
     );
   }
@@ -174,6 +226,8 @@ export function OnboardingPanel({
         </Tooltip>
       </div>
 
+      {errorNotice}
+
       <div style={styles.list}>
         {steps.map((step) => (
           <StepCard
@@ -853,6 +907,19 @@ function badgeStyle(
 }
 
 const styles: Record<string, React.CSSProperties> = {
+  errorOnly: {
+    borderBottom: "1px solid hsl(var(--border) / 0.7)",
+    background: "hsl(var(--muted) / 0.25)",
+    fontSize: 12,
+  },
+  errorNotice: {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 8,
+    padding: "8px 12px",
+    color: "hsl(var(--muted-foreground))",
+  },
   root: {
     borderBottom: "1px solid hsl(var(--border) / 0.7)",
     background: "hsl(var(--muted) / 0.25)",