feat(chatbot): surface AI quota refusals as upgrade/top-up CTA (P1d) (#1777)

Closes the loop opened by the cloud-side pricing rework: when the token guardrail
refuses an AI request with a 429 (free design quota, free data-Q&A trial, or paid
allowance exhausted), the chat UI now shows a friendly upgrade / top-up CTA
instead of a red "Response failed" transport error.

The ai-sdk chat transport throws a plain Error whose `message` is the 429 body
text (no status code preserved), so the only signal is the JSON body.

- tool-display.ts: parseAiQuotaError() — strip retry/format prefixes, locate the
  JSON, match the three guardrail codes; null otherwise. + unit tests.
- ChatbotEnhanced.tsx: ErrorBanner renders an amber upgrade card with a CTA
  ("Upgrade plan" / "Buy a credit pack" for topUp; zh/en by locale) on a quota
  refusal; generic errors unchanged. New onUpgrade prop threaded through;
  FloatingChatbot forwards it automatically via {...chatbotProps}.
- marketplaceApi.ts: cloudPricingDeepLink() — deep-link to the cloud upgrade
  entry (envs list), mirroring cloudInstallDeepLink; centralized for re-pointing.
- AiChatPage.tsx + ConsoleFloatingChatbot.tsx: wire onUpgrade -> open cloud.

Pairs with cloud PR objectstack-ai/cloud#371 (P0+P1a+P1b). Tests: 5
parseAiQuotaError cases pass; changed files typecheck clean. Full browser E2E is
the T8 follow-up.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

packages/app-shell/src/console/ai/AiChatPage.tsx

@@ -51,6 +51,7 @@ import {
 import { AppHeader } from '../../layout/AppHeader';
 import { fetchPendingDraftCount } from '../../preview/draftStatus';
 import { getRuntimeConfig } from '../../runtime-config';
+import { cloudPricingDeepLink } from '../marketplace/marketplaceApi';
 import { useNavigationContext } from '../../context/NavigationContext';
 import {
   sanitizeChatMessagesForCache,
@@ -906,6 +907,7 @@ function ChatPane({
       >
       <ChatbotEnhanced
         className="min-h-0 flex-1 bg-background md:max-w-5xl"
+        onUpgrade={() => window.open(cloudPricingDeepLink(), '_blank', 'noopener,noreferrer')}
         surface="plain"
         maxHeight="100%"
         headerSlot={headerSlot}

packages/app-shell/src/console/marketplace/marketplaceApi.ts

@@ -354,6 +354,19 @@ export function cloudInstallDeepLink(packageId: string): string {
   return `${base}/apps/cloud-control/sys_package/${encodeURIComponent(packageId)}`;
 }
 
+/**
+ * Deep-link to the cloud upgrade entry point: the environments list, where each
+ * environment's "Upgrade Plan" action opens Stripe checkout. Surfaced from the
+ * tenant SPA when an AI quota refusal (429) offers an upgrade / top-up CTA.
+ * Centralized so the target can be re-pointed (dedicated pricing or credit-pack
+ * page) as the cloud billing UI evolves. Same `cloud-control` app slug as
+ * cloudInstallDeepLink above.
+ */
+export function cloudPricingDeepLink(): string {
+  const base = getCloudBase() || 'https://cloud.objectos.app';
+  return `${base}/apps/cloud-control/sys_environment`;
+}
+
 /**
  * Look up whether a package is already installed in the given environment.
  * Returns the installed version string when an `enabled=true` row exists,

packages/app-shell/src/layout/ConsoleFloatingChatbot.tsx

@@ -45,6 +45,7 @@ import {
 import { useAssistant, requestAssistantReview, emitCanvasInvalidate, type AssistantEditorContext } from '../assistant/assistantBus';
 import { fetchPendingDraftCount } from '../preview/draftStatus';
 import { getRuntimeConfig } from '../runtime-config';
+import { cloudPricingDeepLink } from '../console/marketplace/marketplaceApi';
 
 /**
  * Display names for the built-in platform agents. The backend ships English
@@ -537,6 +538,7 @@ function ChatbotInner({
   return (
     <>
       <FloatingChatbot
+        onUpgrade={() => window.open(cloudPricingDeepLink(), '_blank', 'noopener,noreferrer')}
         floatingConfig={{
           position: 'bottom-right',
           defaultOpen,

packages/plugin-chatbot/src/ChatbotEnhanced.tsx

@@ -24,6 +24,7 @@ import { AlertCircle, ArrowRight, Copy, Check, RefreshCw, CornerDownLeft, Bot, E
 import type { ChatStatus } from 'ai';
 import {
   humanizeToolName,
+  parseAiQuotaError,
   summarizeChatError,
   unwrapToolResult,
 } from './tool-display';
@@ -297,6 +298,12 @@ export interface ChatbotEnhancedProps extends React.HTMLAttributes<HTMLDivElemen
   onStop?: () => void;
   /** Reload / retry the last assistant message */
   onReload?: () => void;
+  /**
+   * Called when the user clicks the upgrade / top-up CTA shown for an AI quota
+   * refusal (429 from the cloud token guardrail). Hosts typically open the cloud
+   * billing/pricing page. When omitted, no CTA button is shown.
+   */
+  onUpgrade?: () => void;
   disabled?: boolean;
   /** Whether the assistant is currently generating a response */
   isLoading?: boolean;
@@ -746,6 +753,7 @@ const ChatbotEnhanced = React.forwardRef<HTMLDivElement, ChatbotEnhancedProps>(
       onClear,
       onStop,
       onReload,
+      onUpgrade,
       disabled = false,
       isLoading = false,
       error,
@@ -1566,7 +1574,7 @@ const ChatbotEnhanced = React.forwardRef<HTMLDivElement, ChatbotEnhancedProps>(
         </Conversation>
 
         {error ? (
-          <ErrorBanner error={error} onReload={onReload} />
+          <ErrorBanner error={error} onReload={onReload} onUpgrade={onUpgrade} />
         ) : null}
 
         <div
@@ -2101,12 +2109,51 @@ function getToolSummaryStatus(
 function ErrorBanner({
   error,
   onReload,
+  onUpgrade,
 }: {
   error: Error;
   onReload?: () => void;
+  onUpgrade?: () => void;
 }) {
+  const quota = React.useMemo(() => parseAiQuotaError(error), [error]);
   const { summary, details } = React.useMemo(() => summarizeChatError(error), [error]);
   const [expanded, setExpanded] = React.useState(false);
+
+  // AI quota refusal (429 from the cloud token guardrail) -> friendly upgrade /
+  // top-up CTA instead of a red "Response failed" banner.
+  if (quota) {
+    const isZh =
+      typeof navigator !== 'undefined' && !!navigator.language?.toLowerCase().startsWith('zh');
+    const text =
+      (isZh ? quota.message : quota.messageEn ?? quota.message) ||
+      (isZh ? 'AI \u989d\u5ea6\u5df2\u7528\u5b8c\u3002' : 'You have reached your AI quota.');
+    const cta = quota.topUp
+      ? (isZh ? '\u8d2d\u4e70\u989d\u5ea6\u5305' : 'Buy a credit pack')
+      : (isZh ? '\u5347\u7ea7\u65b9\u6848' : 'Upgrade plan');
+    const title = isZh ? '\u9700\u8981\u5347\u7ea7' : 'Upgrade needed';
+    return (
+      <div className="border-t bg-background px-3 py-2 text-sm" role="alert">
+        <div className="rounded-md border border-amber-300/40 bg-amber-50/60 px-3 py-2 text-foreground dark:bg-amber-950/20">
+          <div className="flex items-start gap-2">
+            <div className="min-w-0 flex-1">
+              <div className="font-medium leading-snug text-foreground">{title}</div>
+              <div className="mt-0.5 break-words leading-snug text-muted-foreground">{text}</div>
+            </div>
+            {onUpgrade ? (
+              <button
+                type="button"
+                onClick={onUpgrade}
+                className="inline-flex h-7 shrink-0 items-center rounded-md border border-amber-400/50 bg-background px-2 text-xs font-medium text-amber-700 hover:bg-amber-100/60 dark:text-amber-300"
+              >
+                {cta}
+              </button>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    );
+  }
+
   return (
     <div
       className="border-t bg-background px-3 py-2 text-sm"

packages/plugin-chatbot/src/tool-display.test.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { parseAiQuotaError } from './tool-display';
+
+describe('parseAiQuotaError', () => {
+  const body = (extra: Record<string, unknown>) =>
+    JSON.stringify({ message: 'quota', messageEn: 'Quota used up', ...extra });
+
+  it('recognizes the free design quota refusal', () => {
+    const r = parseAiQuotaError(new Error(body({ error: 'ai_design_quota_exhausted', upgrade: true })));
+    expect(r).toMatchObject({ code: 'ai_design_quota_exhausted', upgrade: true, topUp: false });
+  });
+
+  it('recognizes the free data-chat trial refusal', () => {
+    const r = parseAiQuotaError(new Error(body({ error: 'ai_data_chat_trial_exhausted', upgrade: true })));
+    expect(r?.code).toBe('ai_data_chat_trial_exhausted');
+  });
+
+  it('recognizes the paid allowance refusal with topUp', () => {
+    const r = parseAiQuotaError(new Error(body({ error: 'ai_allowance_exhausted', upgrade: false, topUp: true })));
+    expect(r).toMatchObject({ code: 'ai_allowance_exhausted', upgrade: false, topUp: true });
+    expect(r?.messageEn).toBe('Quota used up');
+  });
+
+  it('strips the ai-sdk "Failed after N attempts" retry prefix', () => {
+    const r = parseAiQuotaError(
+      new Error(`Failed after 2 attempts. Last error: ${body({ error: 'ai_allowance_exhausted' })}`),
+    );
+    expect(r?.code).toBe('ai_allowance_exhausted');
+  });
+
+  it('returns null for unrelated errors', () => {
+    expect(parseAiQuotaError(new Error('network timeout'))).toBeNull();
+    expect(parseAiQuotaError(new Error(JSON.stringify({ error: 'something_else' })))).toBeNull();
+    expect(parseAiQuotaError(undefined)).toBeNull();
+    expect(parseAiQuotaError('')).toBeNull();
+  });
+});

packages/plugin-chatbot/src/tool-display.ts

@@ -144,3 +144,65 @@ export function summarizeChatError(err: unknown): {
     details: stripped.length > sentence.length ? stripped : undefined,
   };
 }
+
+/** AI quota refusal codes emitted by the cloud token guardrail (HTTP 429). */
+export type AiQuotaCode =
+  | 'ai_design_quota_exhausted'
+  | 'ai_data_chat_trial_exhausted'
+  | 'ai_allowance_exhausted';
+
+export interface AiQuotaError {
+  code: AiQuotaCode;
+  /** Localized (zh) message from the backend. */
+  message: string;
+  /** English message from the backend. */
+  messageEn?: string;
+  /** Free tier -> upgrade to a paid plan. */
+  upgrade: boolean;
+  /** Paid tier -> buy a credit top-up pack. */
+  topUp: boolean;
+}
+
+const AI_QUOTA_CODES = new Set<string>([
+  'ai_design_quota_exhausted',
+  'ai_data_chat_trial_exhausted',
+  'ai_allowance_exhausted',
+]);
+
+/**
+ * Recognize the cloud AI token guardrail's 429 quota refusals so the chat UI can
+ * show a friendly upgrade / top-up CTA instead of a generic "response failed".
+ *
+ * The ai-sdk chat transport throws a plain Error whose `message` is the response
+ * body text (no HTTP status is preserved), so the only signal is the JSON body:
+ * strip the same retry/format prefixes summarizeChatError handles, locate the
+ * JSON object, and match its `error` code. Returns null for anything else.
+ */
+export function parseAiQuotaError(err: unknown): AiQuotaError | null {
+  const raw = err instanceof Error ? err.message : String(err ?? '');
+  if (!raw) return null;
+  const stripped = raw
+    .replace(/^Failed after \d+ attempts?\.\s*Last error:\s*/i, '')
+    .replace(/^Invalid error response format:\s*/i, '')
+    .trim();
+  const start = stripped.indexOf('{');
+  const end = stripped.lastIndexOf('}');
+  if (start < 0 || end <= start) return null;
+  let body: any;
+  try {
+    body = JSON.parse(stripped.slice(start, end + 1));
+  } catch {
+    return null;
+  }
+  if (!body || typeof body.error !== 'string' || !AI_QUOTA_CODES.has(body.error)) {
+    return null;
+  }
+  return {
+    code: body.error as AiQuotaCode,
+    message: typeof body.message === 'string' ? body.message : '',
+    messageEn: typeof body.messageEn === 'string' ? body.messageEn : undefined,
+    upgrade: body.upgrade === true,
+    topUp: body.topUp === true,
+  };
+}
+