feat(console): hide the AI surface at runtime when the server serves no AI (Community Edition) (#1987)

* feat(console): hide the AI surface at runtime when the server serves no AI agent (Community Edition)

A self-host Community Edition runtime (framework + this MIT console, WITHOUT
the closed `@objectstack/service-ai-studio` package) serves no `ask`/`build`
agent. The console must hide its AI UI via runtime, server-pushed gating — no
build-time edition flag, no tree-shake, no relicensing; the AI code stays MIT.

Several entry points rendered unconditionally and `/ai` could dead-end on an
agent-less echo chat. This completes the gating.

Key correctness point — gate on the AGENT CATALOG, not discovery:
the `ask`/`build` agent personas moved to the cloud-only service-ai-studio, but
the open-source framework keeps a HEADLESS `@objectstack/service-ai` that still
`registerService('ai')`s. So a CE runtime reports `services.ai` as available in
`/api/v1/discovery` (verified live: enabled=true, status=available) while the
agent catalog is empty. Gating on `isAiEnabled` would leave the FAB / "Ask AI"
visible with nothing to talk to. `GET /api/v1/ai/agents` (non-empty) is the real
"is there an agent to answer?" signal — and what the Home CTAs already use.

- Add `useAiSurfaceEnabled()` — one source of truth, driven by the agent
  catalog (`useAgents`). Handles the "fetch not started yet" frame so route
  guards don't flash a redirect. Replaces the duplicated FAB checks.
- Add `RequireAiSurface` route guard; wrap the `/ai*` routes in App.tsx. When no
  agent is served it redirects to /home (waits for the catalog first). Cloud
  installs pass straight through.
- Gate the top-bar AI link (AppHeader) and the two designer "Ask AI" buttons
  (ObjectFormCanvas) on the same signal.
- AiChatPage: render a graceful "AI unavailable" state (Back-to-home + Retry on
  error) when the catalog resolves empty, instead of the autoResponse echo chat.
- ConsoleLayout / HomeLayout FAB now use the shared signal; HomePage reuses the
  shared `resolveAiApiBase`.

Verified live against a real framework runtime: with services.ai reporting
AVAILABLE but an empty agent catalog, the FAB, top-bar link and Home CTAs are
all hidden and /ai redirects to home; with an agent served, the FAB shows and
/ai loads the real chat. Plus unit tests for the catalog signal (incl. the
not-yet-fetched latch), the guard redirect, and the designer-button hiding.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore: add changeset for CE AI runtime gating

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/ce-ai-runtime-gating.md

@@ -0,0 +1,23 @@
+---
+"@object-ui/app-shell": minor
+---
+
+feat(console): hide the AI surface at runtime when the server serves no AI agent (Community Edition)
+
+A self-host Community Edition runtime (framework + this MIT console, without the
+cloud `@objectstack/service-ai-studio` package) serves no `ask`/`build` agent.
+The console now hides every AI entry point via runtime, server-pushed gating —
+no build-time edition flag, no tree-shake.
+
+Crucially, gating is driven off the **agent catalog** (`GET /api/v1/ai/agents`),
+not the discovery `services.ai` flag: the open-source framework keeps a headless
+`@objectstack/service-ai` that still reports `services.ai` as available, so a CE
+runtime can report AI "available" while serving zero agents. The catalog is the
+real "is there an agent to answer?" signal.
+
+- New `useAiSurfaceEnabled()` hook + `RequireAiSurface` route guard (exported).
+- `/ai*` routes redirect to home when no agent is served; the FAB, top-bar AI
+  link and the metadata designers' "Ask AI" buttons hide; `AiChatPage` shows a
+  graceful "AI unavailable" state instead of an agent-less echo chat.
+- Fully additive for cloud installs — when an agent is served, every AI surface
+  renders and works as before.

apps/console/src/App.tsx

@@ -23,6 +23,7 @@ import {
   ConsoleShell,
   ConnectedShell,
   RequireOrganization,
+  RequireAiSurface,
   SystemRedirect,
   LoadingFallback,
   ConsoleToaster,
@@ -263,20 +264,27 @@ export function App() {
               back-compat redirects: bare `/ai` → the default agent surface, and
               a single-segment `/ai/:agent` that is actually a legacy bare
               conversation id → `/ai/:agent/:conversationId`.
+
+              `RequireAiSurface` keeps these from dead-ending on a runtime that
+              serves no AI (Community Edition): with AI unavailable a stale
+              bookmark / external link redirects to home instead of mounting a
+              chat with no agent to talk to. Cloud installs pass straight
+              through. Purely additive runtime gating — same server signal the
+              floating-chat FAB has always used.
             */}
             <Route path="/ai" element={
               <ProtectedRoute>
-                <DefaultAiChatPage />
+                <RequireAiSurface><DefaultAiChatPage /></RequireAiSurface>
               </ProtectedRoute>
             } />
             <Route path="/ai/:agent" element={
               <ProtectedRoute>
-                <DefaultAiChatPage />
+                <RequireAiSurface><DefaultAiChatPage /></RequireAiSurface>
               </ProtectedRoute>
             } />
             <Route path="/ai/:agent/:conversationId" element={
               <ProtectedRoute>
-                <DefaultAiChatPage />
+                <RequireAiSurface><DefaultAiChatPage /></RequireAiSurface>
               </ProtectedRoute>
             } />
             <Route path="/apps/:appName/*" element={

packages/app-shell/src/console/ConsoleShell.tsx

@@ -18,6 +18,7 @@ import { SchemaRendererProvider } from '@object-ui/react';
 import { createObjectStackUserStateAdapter } from '@object-ui/data-objectstack';
 import { AdapterProvider, useAdapter } from '../providers/AdapterProvider';
 import { MetadataProvider, useMetadata } from '../providers/MetadataProvider';
+import { useAiSurfaceEnabled } from '../hooks/useAiSurface';
 import { PreviewModeProvider } from '../preview/PreviewModeContext';
 import { NavigationProvider } from '../context/NavigationContext';
 import { FavoritesProvider } from '../context/FavoritesProvider';
@@ -182,6 +183,31 @@ export function RequireOrganization({ children }: { children: ReactNode }) {
   return <>{children}</>;
 }
 
+/**
+ * RequireAiSurface — gate for the `/ai*` routes. The console is edition-agnostic
+ * (MIT, runtime-gated): a Community Edition runtime serves no AI agent, so a
+ * stale `/ai` bookmark or external link must not land on a broken/empty chat.
+ * When the server serves no agent it redirects to `redirectTo` (home) instead.
+ *
+ * Availability is the live agent catalog (see {@link useAiSurfaceEnabled}) — the
+ * same signal every other AI entry point now gates on, so the route is reachable
+ * from exactly the entry points that are visible (no shown CTA that bounces back
+ * to home, no hidden FAB to a working route). Waits for the catalog to resolve
+ * before deciding so the redirect never flashes on first paint.
+ */
+export function RequireAiSurface({
+  children,
+  redirectTo = '/home',
+}: {
+  children: ReactNode;
+  redirectTo?: string;
+}) {
+  const { enabled, isLoading } = useAiSurfaceEnabled();
+  if (isLoading) return <LoadingFallback />;
+  if (!enabled) return <Navigate to={redirectTo} replace />;
+  return <>{children}</>;
+}
+
 /**
  * AuthenticatedRoute — convenience wrapper composing AuthGuard + ConnectedShell
  * (+ optional RequireOrganization). Covers the common case for protected

packages/app-shell/src/console/__tests__/RequireAiSurface.test.tsx

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter, Routes, Route } from 'react-router-dom';
+import { RequireAiSurface } from '../ConsoleShell';
+import { useAiSurfaceEnabled } from '../../hooks/useAiSurface';
+
+// The guard gates purely on the AI-surface signal (the agent catalog); that
+// hook's own plumbing is covered by useAiSurface.test.ts.
+vi.mock('../../hooks/useAiSurface', () => ({
+  useAiSurfaceEnabled: vi.fn(() => ({ enabled: true, isLoading: false })),
+}));
+const mockSurface = vi.mocked(useAiSurfaceEnabled);
+
+function renderGuardedAi() {
+  return render(
+    <MemoryRouter initialEntries={['/ai']}>
+      <Routes>
+        <Route
+          path="/ai"
+          element={
+            <RequireAiSurface>
+              <div>AI CHAT</div>
+            </RequireAiSurface>
+          }
+        />
+        <Route path="/home" element={<div>HOME</div>} />
+      </Routes>
+    </MemoryRouter>,
+  );
+}
+
+describe('RequireAiSurface', () => {
+  beforeEach(() => {
+    mockSurface.mockReturnValue({ enabled: true, isLoading: false });
+  });
+
+  it('renders the AI surface when the server serves agents (cloud install)', () => {
+    renderGuardedAi();
+    expect(screen.getByText('AI CHAT')).toBeInTheDocument();
+    expect(screen.queryByText('HOME')).not.toBeInTheDocument();
+  });
+
+  it('redirects to home when no agents are served (Community Edition) — no dead-end chat', () => {
+    mockSurface.mockReturnValue({ enabled: false, isLoading: false });
+    renderGuardedAi();
+    expect(screen.queryByText('AI CHAT')).not.toBeInTheDocument();
+    expect(screen.getByText('HOME')).toBeInTheDocument();
+  });
+
+  it('waits (neither chat nor redirect) while the agent catalog is still resolving', () => {
+    mockSurface.mockReturnValue({ enabled: false, isLoading: true });
+    renderGuardedAi();
+    expect(screen.queryByText('AI CHAT')).not.toBeInTheDocument();
+    expect(screen.queryByText('HOME')).not.toBeInTheDocument();
+  });
+});

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

@@ -31,6 +31,9 @@ import {
   SheetDescription,
   SheetHeader,
   SheetTitle,
+  Empty,
+  EmptyTitle,
+  EmptyDescription,
   cn,
 } from '@object-ui/components';
 import { PanelLeft, PanelLeftClose, PanelLeftOpen, Share2 } from 'lucide-react';
@@ -493,8 +496,16 @@ export function AiChatPage({ apiBase: apiBaseProp, defaultAgent: defaultAgentPro
   const env = (import.meta as any).env ?? {};
   const envDefaultAgent = env.VITE_AI_DEFAULT_AGENT as string | undefined;
 
-  const { agents, isLoading: agentsLoading, error: agentsError } = useAgents({ apiBase });
+  const { agents, isLoading: agentsLoading, error: agentsError, refetch: refetchAgents } =
+    useAgents({ apiBase });
   const catalogNames = useMemo(() => agents.map((a) => a.name), [agents]);
+  // Catalog resolved with no agent to talk to. The `/ai` route guard already
+  // redirects when discovery reports AI unavailable (Community Edition), so this
+  // is the secondary safety net: a deployment that reports AI enabled but serves
+  // no agent (misconfig), a transient `/agents` failure, or a `VITE_AI_BASE_URL`
+  // server that returns an empty list. Either way, degrade to a graceful state
+  // instead of the agent-less echo chat (autoResponse) that ChatPane falls into.
+  const noAgents = !agentsLoading && agents.length === 0;
 
   // Is the first path segment an agent? It is when it resolves to one (friendly
   // alias / new id / legacy id). When it doesn't, it's a legacy bare
@@ -739,40 +750,55 @@ export function AiChatPage({ apiBase: apiBaseProp, defaultAgent: defaultAgentPro
   return (
     <div className="flex h-svh w-full flex-col bg-background" data-testid="ai-chat-page">
       <header className="sticky top-0 z-30 flex h-14 w-full shrink-0 items-center gap-2 border-b bg-background/95 px-2 backdrop-blur sm:px-4">
-        <Button
-          variant="ghost"
-          size="icon"
-          className="h-8 w-8 shrink-0 md:hidden"
-          onClick={() => setMobileChatsOpen(true)}
-          aria-label={t('console.ai.openChats')}
-          data-testid="ai-chat-mobile-sidebar-trigger"
-        >
-          <PanelLeft className="h-4 w-4" />
-        </Button>
-        <Button
-          variant="ghost"
-          size="icon"
-          className="hidden h-8 w-8 shrink-0 md:inline-flex"
-          onClick={toggleChatsCollapsed}
-          aria-label={
-            chatsCollapsed
-              ? t('console.ai.showChats', { defaultValue: 'Show chats' })
-              : t('console.ai.hideChats', { defaultValue: 'Hide chats' })
-          }
-          title={
-            chatsCollapsed
-              ? t('console.ai.showChats', { defaultValue: 'Show chats' })
-              : t('console.ai.hideChats', { defaultValue: 'Hide chats' })
-          }
-          data-testid="ai-chat-collapse-sidebar-trigger"
-          aria-pressed={chatsCollapsed}
-        >
-          {chatsCollapsed ? <PanelLeftOpen className="h-4 w-4" /> : <PanelLeftClose className="h-4 w-4" />}
-        </Button>
+        {/* Chat-list toggles are meaningless with no agent/conversations, so
+            hide them in the graceful no-agents state. */}
+        {!noAgents && (
+          <>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-8 w-8 shrink-0 md:hidden"
+              onClick={() => setMobileChatsOpen(true)}
+              aria-label={t('console.ai.openChats')}
+              data-testid="ai-chat-mobile-sidebar-trigger"
+            >
+              <PanelLeft className="h-4 w-4" />
+            </Button>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="hidden h-8 w-8 shrink-0 md:inline-flex"
+              onClick={toggleChatsCollapsed}
+              aria-label={
+                chatsCollapsed
+                  ? t('console.ai.showChats', { defaultValue: 'Show chats' })
+                  : t('console.ai.hideChats', { defaultValue: 'Hide chats' })
+              }
+              title={
+                chatsCollapsed
+                  ? t('console.ai.showChats', { defaultValue: 'Show chats' })
+                  : t('console.ai.hideChats', { defaultValue: 'Hide chats' })
+              }
+              data-testid="ai-chat-collapse-sidebar-trigger"
+              aria-pressed={chatsCollapsed}
+            >
+              {chatsCollapsed ? <PanelLeftOpen className="h-4 w-4" /> : <PanelLeftClose className="h-4 w-4" />}
+            </Button>
+          </>
+        )}
         <div className="min-w-0 flex-1">
           <AppHeader variant="home" />
         </div>
       </header>
+      {noAgents ? (
+        <AiUnavailable
+          hasError={Boolean(agentsError)}
+          onRetry={refetchAgents}
+          onHome={() => navigate('/home')}
+          t={t}
+        />
+      ) : (
+      <>
       <Sheet open={mobileChatsOpen} onOpenChange={setMobileChatsOpen}>
         <SheetContent side="left" className="w-[320px] p-0 sm:max-w-[360px]" data-testid="ai-chat-mobile-sidebar">
           <SheetHeader className="sr-only">
@@ -829,6 +855,58 @@ export function AiChatPage({ apiBase: apiBaseProp, defaultAgent: defaultAgentPro
           />
         </main>
       </div>
+      </>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Graceful state for `/ai` when the agent catalog resolved empty — shown
+ * instead of an agent-less echo chat. `hasError` distinguishes "AI not enabled
+ * on this deployment" (Community Edition) from "couldn't reach the AI service"
+ * (offline/misconfig), which also offers a retry. Either way there's a way out
+ * (back to home), so the route never dead-ends.
+ */
+function AiUnavailable({
+  hasError,
+  onRetry,
+  onHome,
+  t,
+}: {
+  hasError: boolean;
+  onRetry: () => void;
+  onHome: () => void;
+  t: (key: string, options?: Record<string, unknown>) => string;
+}) {
+  return (
+    <div className="flex flex-1 items-center justify-center p-6" data-testid="ai-unavailable">
+      <Empty>
+        <EmptyTitle>
+          {t('console.ai.unavailableTitle', { defaultValue: 'AI assistant unavailable' })}
+        </EmptyTitle>
+        <EmptyDescription>
+          {hasError
+            ? t('console.ai.unavailableError', {
+                defaultValue:
+                  "Couldn't reach the AI service. It may be temporarily offline — try again, or head back home.",
+              })
+            : t('console.ai.unavailableDescription', {
+                defaultValue:
+                  "This deployment doesn't have an AI assistant enabled. Everything else works as usual.",
+              })}
+        </EmptyDescription>
+        <div className="mt-6 flex flex-col items-center gap-3 sm:flex-row">
+          {hasError && (
+            <Button variant="outline" onClick={onRetry} data-testid="ai-unavailable-retry">
+              {t('console.ai.unavailableRetry', { defaultValue: 'Try again' })}
+            </Button>
+          )}
+          <Button onClick={onHome} data-testid="ai-unavailable-home">
+            {t('console.ai.unavailableHome', { defaultValue: 'Back to home' })}
+          </Button>
+        </div>
+      </Empty>
     </div>
   );
 }

packages/app-shell/src/console/home/HomeLayout.tsx

@@ -11,7 +11,7 @@
 import React, { useEffect } from 'react';
 import { useNavigationContext } from '../../context/NavigationContext';
 import { AppHeader } from '../../layout/AppHeader';
-import { useDiscovery } from '@object-ui/react';
+import { useAiSurfaceEnabled } from '../../hooks/useAiSurface';
 import { useObjectTranslation } from '@object-ui/i18n';
 
 // Lightweight FAB stub — the heavy chat chunk graph only downloads on
@@ -29,13 +29,11 @@ interface HomeLayoutProps {
 
 export function HomeLayout({ children, userId }: HomeLayoutProps) {
   const { setContext } = useNavigationContext();
-  const { isAiEnabled } = useDiscovery();
   const { t } = useObjectTranslation();
-  // Render the chatbot whenever AI is reachable. If the developer has explicitly
-  // configured `VITE_AI_BASE_URL`, trust that opt-in even when discovery
-  // reports AI as disabled (e.g. framework started without `--preset full`).
-  const aiBaseUrlConfigured = Boolean(import.meta.env?.VITE_AI_BASE_URL);
-  const showChatbot = isAiEnabled || aiBaseUrlConfigured;
+  // Render the chatbot only when the server serves AI (or an explicit
+  // `VITE_AI_BASE_URL` opt-in is set) — same runtime signal as the rest of the
+  // console's AI surface. See useAiSurfaceEnabled.
+  const { enabled: showChatbot } = useAiSurfaceEnabled();
 
   useEffect(() => {
     setContext('home');

packages/app-shell/src/console/home/HomePage.tsx

@@ -31,15 +31,7 @@ import { Empty, EmptyTitle, EmptyDescription, Button } from '@object-ui/componen
 import { Sparkles, ShieldAlert, X, UploadCloud, MessageSquareText } from 'lucide-react';
 import { useMetadataClient } from '../../views/metadata-admin/useMetadata';
 import { usePublishAllDrafts } from '../../preview/usePublishAllDrafts';
-
-/** Resolve the AI service base, mirroring AiChatPage/ConsoleFloatingChatbot. */
-function resolveAiApiBase(): string {
-  const env = (import.meta as any).env ?? {};
-  const fromEnv = env.VITE_AI_BASE_URL as string | undefined;
-  if (fromEnv) return fromEnv.replace(/\/$/, '');
-  const serverUrl = (env.VITE_SERVER_URL as string | undefined) ?? '';
-  return `${serverUrl.replace(/\/$/, '')}/api/v1/ai`;
-}
+import { resolveAiApiBase } from '../../hooks/useAiSurface';
 
 /**
  * Which AI home CTAs to surface, driven by the live agent catalog (the single