@object-ui/app-shell 7.1.0 → 7.2.0

package/dist/environment/useEnvironmentEntitlements.js

@@ -0,0 +1,108 @@
+/**
+ * useEnvironmentEntitlements — resolve the org's environment-capacity state so
+ * the `sys_environment` list can present the right "create" affordance up front.
+ *
+ * Two signals, in priority order:
+ *   1. AUTHORITATIVE — GET /cloud/environment-entitlements (org-scoped, computed
+ *      by the same helper the create guard uses). Gives plan + dev-create
+ *      capability precisely, including the seat-scaled / subscription cases the
+ *      client can't derive from rows.
+ *   2. FALLBACK — when that endpoint is unavailable (older control plane / error),
+ *      derive `hasProductionEnv` from the org's env rows via the data API (which
+ *      is org-scoped on the control plane). This keeps the critical
+ *      "set up your production environment" path working without a backend deploy;
+ *      free-vs-paid is left unknown, and a stray create POST is caught by the
+ *      entitlement dialog safety net.
+ *
+ * Returns `null` when disabled (not the environment list) so callers can cheaply
+ * branch. Re-resolves when `refreshKey` changes (e.g. after a create).
+ */
+import { useEffect, useState } from 'react';
+import { useAuth } from '@object-ui/auth';
+import { DEFAULT_UPGRADE_URL, } from './entitlements';
+const TERMINAL_STATUSES = new Set(['archived', 'failed']);
+/** Mirror of the server `classifyEnvironmentType`: explicit type, else default→prod. */
+function classifyEnvironmentType(row) {
+    const t = String(row?.environment_type ?? '').trim().toLowerCase();
+    if (t === 'production' || t === 'prod')
+        return 'production';
+    if (t)
+        return 'development';
+    return row?.is_default === true || row?.is_default === 1 ? 'production' : 'development';
+}
+export function useEnvironmentEntitlements(opts) {
+    const { enabled, dataSource, authFetch, apiBase, refreshKey } = opts;
+    const { activeOrganization } = useAuth();
+    const orgId = activeOrganization?.id;
+    const [state, setState] = useState(null);
+    useEffect(() => {
+        if (!enabled) {
+            setState(null);
+            return;
+        }
+        let cancelled = false;
+        const fromSummary = async () => {
+            try {
+                const base = (apiBase || '').replace(/\/+$/, '');
+                const qs = orgId ? `?organizationId=${encodeURIComponent(orgId)}` : '';
+                const res = await authFetch(`${base}/api/v1/cloud/environment-entitlements${qs}`, {
+                    method: 'GET',
+                    credentials: 'include',
+                });
+                if (!res.ok)
+                    return null;
+                const json = await res.json().catch(() => null);
+                const data = (json?.data ?? json);
+                if (!data || typeof data !== 'object')
+                    return null;
+                return {
+                    ready: true,
+                    hasProductionEnv: data.hasProductionEnv === true,
+                    canCreateDevelopmentEnv: data.development?.canCreate,
+                    plan: data.plan,
+                    upgradeUrl: data.upgradeUrl || DEFAULT_UPGRADE_URL,
+                    contactSalesUrl: data.contactSalesUrl,
+                    source: 'summary',
+                };
+            }
+            catch {
+                return null;
+            }
+        };
+        const fromRows = async () => {
+            try {
+                const params = { $top: 200 };
+                if (orgId)
+                    params.$filter = { organization_id: orgId };
+                const res = await dataSource.find('sys_environment', params);
+                const rows = Array.isArray(res) ? res : res?.data ?? [];
+                const active = rows.filter((r) => !TERMINAL_STATUSES.has(String(r?.status ?? '')));
+                const hasProductionEnv = active.some((r) => classifyEnvironmentType(r) === 'production');
+                return {
+                    ready: true,
+                    hasProductionEnv,
+                    canCreateDevelopmentEnv: undefined,
+                    upgradeUrl: DEFAULT_UPGRADE_URL,
+                    source: 'derived',
+                };
+            }
+            catch {
+                return {
+                    ready: false,
+                    hasProductionEnv: false,
+                    canCreateDevelopmentEnv: undefined,
+                    upgradeUrl: DEFAULT_UPGRADE_URL,
+                    source: 'unknown',
+                };
+            }
+        };
+        (async () => {
+            const summary = await fromSummary();
+            const next = summary ?? (await fromRows());
+            if (!cancelled)
+                setState(next);
+        })();
+        return () => { cancelled = true; };
+    }, [enabled, orgId, apiBase, authFetch, dataSource, refreshKey]);
+    return state;
+}

package/dist/hooks/useActionModal.js

@@ -23,8 +23,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { useCallback, useState } from 'react';
 import { Button, Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, Drawer, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, cn, } from '@object-ui/components';
-import { SchemaRenderer } from '@object-ui/react';
+import { SchemaRenderer, useMetadata } from '@object-ui/react';
 import { ModalForm } from '@object-ui/plugin-form';
+import { resolveFormViewLayout } from '../utils/recordFormNavigation';
 const SIZE_CLASS = {
     sm: 'sm:max-w-sm',
     default: 'sm:max-w-lg',
@@ -56,6 +57,10 @@ export function normalizeModalSchema(schema) {
 }
 export function useActionModal(dataSource) {
     const [state, setState] = useState(null);
+    // Object metadata — degrades to an empty list outside a MetadataProvider
+    // (see useMetadata). Used to resolve the object's default form view so the
+    // create/edit modal honors its curated sections + field selection/order.
+    const { objects } = useMetadata();
     const close = useCallback((r) => {
         setState((s) => {
             s?.resolve(r);
@@ -73,6 +78,14 @@ export function useActionModal(dataSource) {
                 close({ success: false });
         };
         if (d.objectName && !d.content) {
+            // Honor the object's default FORM VIEW (curated sections + field
+            // selection/order + master-detail subforms) unless the action descriptor
+            // passed an explicit field list. Without this the modal falls back to the
+            // raw object schema — every field, in schema order. Mirrors the global
+            // New/Edit modal in AppContent so action-opened forms stay consistent.
+            const viewLayout = (d.fields || d.sections)
+                ? {}
+                : resolveFormViewLayout(objects.find((o) => o?.name === d.objectName));
             modalElement = (_jsx(ModalForm, { schema: {
                     type: 'object-form',
                     formType: 'modal',
@@ -82,6 +95,7 @@ export function useActionModal(dataSource) {
                     title: d.title,
                     description: d.description,
                     fields: d.fields,
+                    ...viewLayout,
                     modalSize: d.size,
                     open: true,
                     onOpenChange,

package/dist/hooks/useAiSurface.d.ts

@@ -0,0 +1,59 @@
+/**
+ * useAiSurfaceEnabled
+ *
+ * Single source of truth for "should the in-UI AI surface be shown — for THIS
+ * user, on this deployment?". The console ships under MIT and is edition- and
+ * seat-agnostic at build time; it decides purely at runtime from what the
+ * server reports — no `VITE_EDITION` flag, no tree-shake.
+ *
+ * The signal is **the agent catalog** (`GET /api/v1/ai/agents`): the surface
+ * shows iff that returns >= 1 agent. The catalog is the right signal because it
+ * is the ONLY one that is BOTH edition- AND user-aware:
+ *
+ *   • The route is access-filtered server-side (ADR-0049 / ADR-0068): it returns
+ *     only the agents the CALLER may chat. A user WITHOUT the per-user AI seat
+ *     (the `ai_seat` permission) gets an EMPTY catalog -> the whole AI surface
+ *     hides for them, instead of showing a button that 403s on click. The
+ *     deployment-wide discovery `services.ai` flag CANNOT express this — it is
+ *     identical for every user — which is exactly why we do NOT gate on it.
+ *   • It is ALSO the honest edition signal: a Community-Edition runtime that
+ *     ships no `@objectstack/service-ai` registers no AI service and persists no
+ *     agents -> empty catalog -> hidden. (The old "headless service reports
+ *     available in CE" worry is moot: empty catalog hides the surface either way.)
+ *
+ * ⚠️  Do NOT "simplify" this back to `discovery.services.ai` (isAiEnabled): that
+ * reintroduces the per-user gap — seat-less users would see the FAB / links and
+ * hit 403 on click. The per-user AI-seat gate (ADR-0068) DEPENDS on this catalog
+ * signal. (This reverts objectui#1992, which dropped the per-user dimension.)
+ *
+ * The `VITE_AI_BASE_URL` opt-in flows through naturally: {@link resolveAiApiBase}
+ * points the catalog fetch at the configured server, so an external AI server
+ * with reachable agents lights the surface up and an agent-less one keeps it hidden.
+ *
+ * `isLoading` is surfaced so the `/ai` route guard can wait for the catalog to
+ * resolve before redirecting — otherwise a stale bookmark would flash a redirect
+ * to home before the fetch even starts. Entry-point buttons (FAB, top-bar link,
+ * designer "Ask AI") ignore it: staying hidden during the brief load is the
+ * correct, flash-free behaviour for a control that must not appear unless AI can
+ * actually answer.
+ *
+ * @module
+ */
+/**
+ * Resolve the AI service base URL, mirroring AiChatPage / the Home CTAs:
+ * an explicit `VITE_AI_BASE_URL` wins, otherwise `${VITE_SERVER_URL}/api/v1/ai`.
+ * Shared so every catalog fetch (route guard, layouts, Home) hits the same URL.
+ */
+export declare function resolveAiApiBase(): string;
+export interface AiSurfaceState {
+    /** True when the AI UI should render — the CALLER can reach >= 1 agent (access-filtered). */
+    enabled: boolean;
+    /** True until the agent catalog has resolved; route guards wait on this. */
+    isLoading: boolean;
+}
+/**
+ * Whether the console's AI surface (FAB, `/ai` routes, "Ask AI" affordances)
+ * should be shown FOR THE CURRENT USER, driven off the access-filtered agent
+ * catalog (empty for seat-less users -> AI hidden; ADR-0068).
+ */
+export declare function useAiSurfaceEnabled(): AiSurfaceState;

package/dist/hooks/useAiSurface.js

@@ -0,0 +1,78 @@
+/**
+ * useAiSurfaceEnabled
+ *
+ * Single source of truth for "should the in-UI AI surface be shown — for THIS
+ * user, on this deployment?". The console ships under MIT and is edition- and
+ * seat-agnostic at build time; it decides purely at runtime from what the
+ * server reports — no `VITE_EDITION` flag, no tree-shake.
+ *
+ * The signal is **the agent catalog** (`GET /api/v1/ai/agents`): the surface
+ * shows iff that returns >= 1 agent. The catalog is the right signal because it
+ * is the ONLY one that is BOTH edition- AND user-aware:
+ *
+ *   • The route is access-filtered server-side (ADR-0049 / ADR-0068): it returns
+ *     only the agents the CALLER may chat. A user WITHOUT the per-user AI seat
+ *     (the `ai_seat` permission) gets an EMPTY catalog -> the whole AI surface
+ *     hides for them, instead of showing a button that 403s on click. The
+ *     deployment-wide discovery `services.ai` flag CANNOT express this — it is
+ *     identical for every user — which is exactly why we do NOT gate on it.
+ *   • It is ALSO the honest edition signal: a Community-Edition runtime that
+ *     ships no `@objectstack/service-ai` registers no AI service and persists no
+ *     agents -> empty catalog -> hidden. (The old "headless service reports
+ *     available in CE" worry is moot: empty catalog hides the surface either way.)
+ *
+ * ⚠️  Do NOT "simplify" this back to `discovery.services.ai` (isAiEnabled): that
+ * reintroduces the per-user gap — seat-less users would see the FAB / links and
+ * hit 403 on click. The per-user AI-seat gate (ADR-0068) DEPENDS on this catalog
+ * signal. (This reverts objectui#1992, which dropped the per-user dimension.)
+ *
+ * The `VITE_AI_BASE_URL` opt-in flows through naturally: {@link resolveAiApiBase}
+ * points the catalog fetch at the configured server, so an external AI server
+ * with reachable agents lights the surface up and an agent-less one keeps it hidden.
+ *
+ * `isLoading` is surfaced so the `/ai` route guard can wait for the catalog to
+ * resolve before redirecting — otherwise a stale bookmark would flash a redirect
+ * to home before the fetch even starts. Entry-point buttons (FAB, top-bar link,
+ * designer "Ask AI") ignore it: staying hidden during the brief load is the
+ * correct, flash-free behaviour for a control that must not appear unless AI can
+ * actually answer.
+ *
+ * @module
+ */
+import { useRef } from 'react';
+import { useAgents } from '@object-ui/plugin-chatbot';
+/**
+ * Resolve the AI service base URL, mirroring AiChatPage / the Home CTAs:
+ * an explicit `VITE_AI_BASE_URL` wins, otherwise `${VITE_SERVER_URL}/api/v1/ai`.
+ * Shared so every catalog fetch (route guard, layouts, Home) hits the same URL.
+ */
+export function resolveAiApiBase() {
+    const env = import.meta.env ?? {};
+    const fromEnv = env.VITE_AI_BASE_URL;
+    if (fromEnv)
+        return fromEnv.replace(/\/$/, '');
+    const serverUrl = env.VITE_SERVER_URL ?? '';
+    return `${serverUrl.replace(/\/$/, '')}/api/v1/ai`;
+}
+/**
+ * Whether the console's AI surface (FAB, `/ai` routes, "Ask AI" affordances)
+ * should be shown FOR THE CURRENT USER, driven off the access-filtered agent
+ * catalog (empty for seat-less users -> AI hidden; ADR-0068).
+ */
+export function useAiSurfaceEnabled() {
+    const { agents, isLoading } = useAgents({ apiBase: resolveAiApiBase() });
+    // useAgents starts `isLoading=false` and only kicks off the fetch in an effect
+    // a tick later, so the first render's empty list means "not fetched yet", not
+    // "no agents". Latch whether a fetch has actually been in flight so the route
+    // guard treats that initial frame as loading (not a definitive empty → redirect).
+    const fetchStartedRef = useRef(false);
+    if (isLoading)
+        fetchStartedRef.current = true;
+    const enabled = agents.length > 0;
+    return {
+        enabled,
+        // Agents present → resolved/available. Otherwise we're loading until a fetch
+        // has both started and finished with an empty result.
+        isLoading: enabled ? false : isLoading || !fetchStartedRef.current,
+    };
+}

package/dist/hooks/useConsoleActionRuntime.d.ts

@@ -23,6 +23,7 @@
 import React from 'react';
 import { createAuthenticatedFetch } from '@object-ui/auth';
 import type { ActionContext, ActionDef, ActionResult, ConfirmationHandler, NavigationHandler, ParamCollectionHandler, ResultDialogHandler, ToastHandler } from '@object-ui/core';
+import { type EntitlementDialogSpec } from '../environment/entitlements';
 export interface ConsoleActionRuntimeOptions {
     /** Adapter for generic CRUD / execute calls. */
     dataSource: any;
@@ -45,6 +46,8 @@ export interface ConsoleActionRuntime {
     serverActionHandler: (action: ActionDef, context?: ActionContext) => Promise<ActionResult>;
     /** Authenticated fetch wrapper (Bearer + tenant + cookies). */
     authFetch: ReturnType<typeof createAuthenticatedFetch>;
+    /** Open the shared environment entitlement (upgrade / limit) dialog. */
+    openEntitlementDialog: (spec: EntitlementDialogSpec) => void;
     /** Props to spread onto `<ActionProvider>`. */
     actionProviderProps: {
         context: Record<string, any>;

package/dist/hooks/useConsoleActionRuntime.js

@@ -33,6 +33,9 @@ import { ActionParamDialog } from '../views/ActionParamDialog';
 import { ActionResultDialog } from '../views/ActionResultDialog';
 import { FlowRunner } from '../views/FlowRunner';
 import { resolveActionParams } from '../utils/resolveActionParams';
+import { EnvironmentEntitlementDialog } from '../environment/EnvironmentEntitlementDialog';
+import { entitlementDialogFromError } from '../environment/entitlements';
+import { resolvePageVarTokens } from '../utils/resolvePageVarTokens';
 const FALLBACK_USER = { id: 'current-user', name: 'Demo User', isPlatformAdmin: false };
 export function useConsoleActionRuntime(opts) {
     const { dataSource, objects, objectName, onRefresh } = opts;
@@ -60,6 +63,9 @@ export function useConsoleActionRuntime(opts) {
     const [resultDialogState, setResultDialogState] = useState({ open: false });
     // A paused `screen`-node flow awaiting user input.
     const [screenFlow, setScreenFlow] = useState(null);
+    // Plan/capacity gate dialog (upgrade / limit), shared by the env-list toolbar
+    // (proactive) and the api-action error path below (reactive safety net).
+    const [entitlementDialog, setEntitlementDialog] = useState({ open: false });
     // Guards against double-firing a server action (slow SSO handoff, etc.).
     const serverActionInFlight = useRef(new Set());
     const resultDialogHandler = useCallback((spec, data) => new Promise((resolve) => {
@@ -133,7 +139,10 @@ export function useConsoleActionRuntime(opts) {
     }, [navigate]);
     // Authenticated fetch for direct backend calls. Declared before apiHandler.
     const authFetch = useMemo(() => createAuthenticatedFetch(), []);
-    const apiHandler = useCallback(async (action) => {
+    const openEntitlementDialog = useCallback((spec) => {
+        setEntitlementDialog({ open: true, spec });
+    }, []);
+    const apiHandler = useCallback(async (action, context) => {
         try {
             const target = action.target || action.name;
             const params = action.params || {};
@@ -148,6 +157,12 @@ export function useConsoleActionRuntime(opts) {
                 const rawParams = { ...params };
                 const rowRecord = rawParams._rowRecord;
                 delete rawParams._rowRecord;
+                // Resolve `{{page.<var>}}` tokens against the live page-variable snapshot
+                // (published into the action context by PageVariableActionBridge). This is
+                // what lets a pure-SDUI form submit the values its inputs wrote into page
+                // variables; whole-value tokens preserve type. See resolvePageVarTokens.
+                const pageVars = (context?.pageVariables ?? undefined);
+                const resolvedParams = resolvePageVarTokens(rawParams, pageVars);
                 // Interpolate `{field}` tokens in the target URL from the row record.
                 let resolvedTarget = targetStr;
                 if (rowRecord && /\{[a-z_][a-z0-9_]*\}/i.test(resolvedTarget)) {
@@ -160,7 +175,7 @@ export function useConsoleActionRuntime(opts) {
                 const wrap = action.bodyShape && typeof action.bodyShape === 'object' && action.bodyShape.wrap
                     ? action.bodyShape.wrap
                     : undefined;
-                const body = wrap ? { [wrap]: rawParams } : { ...rawParams };
+                const body = wrap ? { [wrap]: resolvedParams } : { ...resolvedParams };
                 if (rowRecord && action.recordIdParam) {
                     const rowField = action.recordIdField || 'id';
                     const rowValue = rowRecord[rowField];
@@ -172,7 +187,7 @@ export function useConsoleActionRuntime(opts) {
                     body.organizationId = activeOrganization.id;
                 }
                 if (action.bodyExtra && typeof action.bodyExtra === 'object') {
-                    Object.assign(body, action.bodyExtra);
+                    Object.assign(body, resolvePageVarTokens(action.bodyExtra, pageVars));
                 }
                 const method = (action.method || 'POST').toUpperCase();
                 const init = {
@@ -185,12 +200,23 @@ export function useConsoleActionRuntime(opts) {
                 }
                 const res = await authFetch(url, init);
                 if (!res.ok) {
-                    let detail = `HTTP ${res.status}`;
+                    let body = null;
                     try {
-                        const j = await res.json();
-                        detail = j?.error || j?.message || detail;
+                        body = await res.json();
                     }
                     catch { /* response body not JSON */ }
+                    // Plan/capacity gates (e.g. creating an environment the org's plan
+                    // doesn't include) come back as coded 403s. Surface them as a friendly
+                    // upgrade/limit DIALOG with a CTA — never a generic red error toast.
+                    // Returning success:false WITHOUT an `error` suppresses the runner's
+                    // error toast (ActionRunner.handlePostExecution); the dialog owns the
+                    // messaging.
+                    const entitlementSpec = entitlementDialogFromError(body);
+                    if (entitlementSpec) {
+                        openEntitlementDialog(entitlementSpec);
+                        return { success: false };
+                    }
+                    const detail = body?.error || body?.message || `HTTP ${res.status}`;
                     return { success: false, error: detail };
                 }
                 const data = await res.json().catch(() => ({}));
@@ -251,7 +277,7 @@ export function useConsoleActionRuntime(opts) {
         catch (error) {
             return { success: false, error: error.message };
         }
-    }, [dataSource, objApiName, authFetch, activeOrganization, refresh]);
+    }, [dataSource, objApiName, authFetch, activeOrganization, refresh, openEntitlementDialog]);
     // Flow action handler — POST to /api/v1/automation/{name}/trigger.
     // `context` is the shared ActionRunner context (registered handlers are
     // invoked as `handler(action, runnerContext)`).
@@ -537,7 +563,8 @@ export function useConsoleActionRuntime(opts) {
                 } }), _jsx(ActionResultDialog, { state: resultDialogState, onAcknowledge: () => {
                     resultDialogState.resolve?.();
                     setResultDialogState({ open: false });
-                } }), _jsx(FlowRunner, { state: screenFlow, authFetch: authFetch, baseUrl: import.meta.env.VITE_SERVER_URL || '', dataSource: dataSource, objects: objects, onClose: () => setScreenFlow(null), onComplete: () => { setScreenFlow(null); refresh(); } })] }));
+                } }), _jsx(FlowRunner, { state: screenFlow, authFetch: authFetch, baseUrl: import.meta.env.VITE_SERVER_URL || '', dataSource: dataSource, objects: objects, onClose: () => setScreenFlow(null), onComplete: () => { setScreenFlow(null); refresh(); } }), _jsx(EnvironmentEntitlementDialog, { state: entitlementDialog, apiBase: import.meta.env.VITE_SERVER_URL || '', onOpenChange: (open) => { if (!open)
+                    setEntitlementDialog({ open: false }); } })] }));
     return {
         confirmHandler,
         toastHandler,
@@ -548,6 +575,7 @@ export function useConsoleActionRuntime(opts) {
         flowHandler,
         serverActionHandler,
         authFetch,
+        openEntitlementDialog,
         actionProviderProps,
         dialogs,
     };

package/dist/index.d.ts

@@ -19,7 +19,9 @@ export type { AppShellProps, } from './types';
 export type { MetadataState, MetadataContextValue, MetadataTypeStatus, } from './providers/MetadataProvider';
 export type { ExpressionContextValue, } from './providers/ExpressionProvider';
 export type { RecentItem, } from './hooks/useRecentItems';
-export { ConsoleShell, ConnectedShell, RequireOrganization, AuthenticatedRoute, RootRedirect, SystemRedirect, LoadingFallback, } from './console/ConsoleShell';
+export { ConsoleShell, ConnectedShell, RequireOrganization, RequireAiSurface, AuthenticatedRoute, RootRedirect, SystemRedirect, LoadingFallback, } from './console/ConsoleShell';
+export { useAiSurfaceEnabled } from './hooks/useAiSurface';
+export type { AiSurfaceState } from './hooks/useAiSurface';
 export { ConsoleLayout, AppHeader, AppSidebar, UnifiedSidebar, AppSwitcher, ConnectionStatus, ActivityFeed, LocaleSwitcher, ModeToggle, AuthPageLayout, } from './layout';
 export type { ActivityItem } from './layout';
 export { CommandPalette, KeyboardShortcutsDialog, OnboardingWalkthrough, ConditionalAuthWrapper, ConsoleToaster, RouteFader, toastWithUndo, type ToastWithUndoOptions, ErrorBoundary, LoadingScreen, ThemeProvider, useTheme, } from './chrome';

package/dist/index.js

@@ -18,7 +18,11 @@ export { getPendingRequests, isIdle, subscribeSettle, whenIdle, withSettleSignal
 export { useRecentItems } from './hooks/useRecentItems';
 // Console building blocks — compose these in your App.tsx to build the console
 // routing tree. See examples/console-starter/src/App.tsx for a minimal example.
-export { ConsoleShell, ConnectedShell, RequireOrganization, AuthenticatedRoute, RootRedirect, SystemRedirect, LoadingFallback, } from './console/ConsoleShell';
+export { ConsoleShell, ConnectedShell, RequireOrganization, RequireAiSurface, AuthenticatedRoute, RootRedirect, SystemRedirect, LoadingFallback, } from './console/ConsoleShell';
+// Runtime AI-availability signal — the single source of truth every AI entry
+// point gates on (FAB, /ai routes, designer "Ask AI"). Server-pushed, no
+// build-time edition flag. See ./hooks/useAiSurface.
+export { useAiSurfaceEnabled } from './hooks/useAiSurface';
 // Layout chrome
 export { ConsoleLayout, AppHeader, AppSidebar, UnifiedSidebar, AppSwitcher, ConnectionStatus, ActivityFeed, LocaleSwitcher, ModeToggle, AuthPageLayout, } from './layout';
 // Top-level chrome (dialogs, providers, error boundaries)

package/dist/layout/AppHeader.js

@@ -20,7 +20,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  */
 import { useLocation, useParams, Link, useNavigate } from 'react-router-dom';
 import { Button, DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuGroup, Avatar, AvatarImage, AvatarFallback, cn, } from '@object-ui/components';
-import { Search, HelpCircle, ChevronDown, Check, Lock, LogOut, Boxes, Layers, Bot, User, BookOpen, ExternalLink, Keyboard, } from 'lucide-react';
+import { Search, HelpCircle, ChevronDown, Check, Lock, LogOut, Boxes, Plus, Layers, Bot, User, BookOpen, ExternalLink, Keyboard, } from 'lucide-react';
 import { useState, useEffect, useCallback, useRef } from 'react';
 import { useOffline } from '@object-ui/react';
 import { PresenceAvatars, useTenantPresence } from '@object-ui/collaboration';
@@ -39,6 +39,7 @@ import { useMobileViewSwitcher } from './MobileViewSwitcherContext';
 import { useNavigationContext } from '../context/NavigationContext';
 import { useCommandPalette } from '../context/CommandPaletteProvider';
 import { useUrlOverlay } from '../hooks/useUrlOverlay';
+import { useAiSurfaceEnabled } from '../hooks/useAiSurface';
 import { getProductName } from '../runtime-config';
 import { LocalizedSidebarTrigger } from './LocalizedSidebarTrigger';
 function humanizeSlug(slug) {
@@ -64,8 +65,12 @@ export function AppHeader({ variant, appName, objects, connectionState, presence
     // Click-reachable entry for the keyboard-shortcuts dialog (was `?`-key only).
     // Shares the `?shortcuts=1` URL param with KeyboardShortcutsDialog (C2/C3).
     const { openOverlay: openShortcuts } = useUrlOverlay('shortcuts');
-    const { user, signOut, isAuthEnabled, organizations, activeOrganization, isOrganizationsLoading, } = useAuth();
+    const { user, signOut, isAuthEnabled, organizations, activeOrganization, isOrganizationsLoading, getAuthConfig, } = useAuth();
     const dataSource = useAdapter();
+    // Runtime AI gating: hide the top-bar AI entry point when the server serves
+    // no AI (Community Edition) so it can't dead-end on a chat with no agent.
+    // Same signal as the FAB and the `/ai` route guard.
+    const { enabled: aiEnabled } = useAiSurfaceEnabled();
     const { t } = useObjectTranslation();
     const { objectLabel, dashboardLabel, pageLabel, reportLabel, viewLabel, appLabel } = useObjectLabel();
     const { apps: metadataApps, dashboards: metadataDashboards, pages: metadataPages, reports: metadataReports } = useMetadata();
@@ -432,6 +437,25 @@ export function AppHeader({ variant, appName, objects, connectionState, presence
     const activeActivities = activities ?? apiActivities ?? [];
     const orgList = organizations ?? [];
     const hasOrgSection = isOrganizationsLoading || orgList.length > 0 || !!activeOrganization;
+    // Mirror the server's `beforeCreateOrganization` gate so the "Create
+    // workspace" entry only shows where multi-org self-service is enabled.
+    // Default to allowed until the config resolves (avoids hiding it on slow
+    // networks); the server still enforces.
+    const [multiOrgDisabled, setMultiOrgDisabled] = useState(false);
+    useEffect(() => {
+        let cancelled = false;
+        getAuthConfig?.()
+            .then((cfg) => {
+            if (!cancelled)
+                setMultiOrgDisabled(cfg?.features?.multiOrgEnabled === false);
+        })
+            .catch(() => {
+            /* leave default — server still enforces */
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [getAuthConfig]);
     // Build path segments (only used in `app` variant)
     const pathParts = location.pathname.split('/').filter(Boolean);
     const appNameFromRoute = params.appName || pathParts[1];
@@ -545,10 +569,10 @@ export function AppHeader({ variant, appName, objects, connectionState, presence
                                                     if (!isActive)
                                                         mobileSwitcher.onChange(v.id);
                                                 }, className: "gap-2", children: [v.icon ? (_jsx("span", { className: "shrink-0 text-muted-foreground [&>svg]:h-4 [&>svg]:w-4", children: v.icon })) : null, _jsx("span", { className: "flex-1 truncate", children: v.label }), v.locked ? (_jsx(Lock, { className: "h-3 w-3 shrink-0 text-muted-foreground", "aria-hidden": true })) : null, isActive ? (_jsx(Check, { className: "h-4 w-4 shrink-0 text-foreground", "aria-hidden": true })) : null] }, v.id));
-                                        }) })] })) : (_jsx("span", { className: "text-sm font-medium sm:hidden truncate min-w-0 ml-1", children: mobileSwitcher.triggerLabel ?? mobileSwitcher.views[0].label }))) : (_jsx("span", { className: "text-sm font-medium sm:hidden truncate min-w-0 ml-1", children: lastSegmentLabel }))] }))] }), _jsxs("div", { className: "flex items-center gap-0.5 sm:gap-1 shrink-0 [&>*+*[data-topbar-group]]:ml-1 [&>[data-topbar-group]+[data-topbar-group]]:border-l [&>[data-topbar-group]+[data-topbar-group]]:border-border/60 [&>[data-topbar-group]+[data-topbar-group]]:pl-1 sm:[&>[data-topbar-group]+[data-topbar-group]]:pl-2 sm:[&>[data-topbar-group]+[data-topbar-group]]:ml-2", children: [!isOnline && (_jsxs("div", { className: "flex items-center gap-1 px-2 py-1 rounded-full bg-yellow-100 dark:bg-yellow-900/30 text-yellow-800 dark:text-yellow-200 text-xs font-medium", children: [_jsx("span", { className: "h-2 w-2 rounded-full bg-yellow-500 animate-pulse" }), t('topbar.offline', { defaultValue: 'Offline' })] })), isApp && connectionState && _jsx(ConnectionStatus, { state: connectionState }), isApp && activeUsers.length > 0 && (_jsx("div", { className: "hidden md:flex items-center shrink-0", title: t('topbar.usersOnline', { defaultValue: 'Users currently online' }), children: _jsx(PresenceAvatars, { users: activeUsers, size: "sm", maxVisible: 3, showStatus: true }) })), _jsxs("div", { "data-topbar-group": true, className: "flex items-center gap-0.5 sm:gap-1 shrink-0", children: [_jsxs("button", { type: "button", "data-testid": "action:command-palette:open", "aria-label": t('console.search', { defaultValue: 'Search…' }), "aria-keyshortcuts": "Meta+K Control+K", onClick: openCommandPalette, className: "hidden lg:flex relative items-center gap-2 w-48 xl:w-64 h-8 px-3 text-sm rounded-md border bg-muted/50 text-muted-foreground hover:bg-muted transition-colors", children: [_jsx(Search, { className: "h-3.5 w-3.5 shrink-0" }), _jsx("span", { className: "flex-1 text-left text-xs", children: t('console.search', { defaultValue: 'Search…' }) }), _jsxs("kbd", { className: "pointer-events-none inline-flex h-5 items-center gap-0.5 rounded border bg-background px-1.5 text-[10px] font-medium text-muted-foreground", children: [_jsx("span", { className: "text-xs", children: "\u2318" }), "K"] })] }), _jsx(Button, { variant: "ghost", size: "icon", className: "lg:hidden h-8 w-8 shrink-0", "data-testid": "action:command-palette:open-mobile", onClick: openCommandPalette, "aria-label": t('console.search', { defaultValue: 'Search…' }), children: _jsx(Search, { className: "h-4 w-4" }) })] }), _jsxs("div", { "data-topbar-group": true, className: "flex items-center gap-0.5 shrink-0", children: [_jsx(InboxPopover, { notifications: notifications, unreadCount: unreadCount, pendingApprovalsCount: pendingApprovalsCount, activities: activeActivities, onMarkAllRead: markAllRead, onMarkRead: markNotificationRead }), _jsx(Button, { variant: "ghost", size: "icon", className: "h-8 w-8 shrink-0", asChild: true, "aria-label": t('topbar.aiAssistant', { defaultValue: 'AI Assistant' }), children: _jsx(Link, { to: "/ai", children: _jsx(Bot, { className: "h-4 w-4" }) }) }), _jsxs(DropdownMenu, { onOpenChange: (open) => { if (open)
+                                        }) })] })) : (_jsx("span", { className: "text-sm font-medium sm:hidden truncate min-w-0 ml-1", children: mobileSwitcher.triggerLabel ?? mobileSwitcher.views[0].label }))) : (_jsx("span", { className: "text-sm font-medium sm:hidden truncate min-w-0 ml-1", children: lastSegmentLabel }))] }))] }), _jsxs("div", { className: "flex items-center gap-0.5 sm:gap-1 shrink-0 [&>*+*[data-topbar-group]]:ml-1 [&>[data-topbar-group]+[data-topbar-group]]:border-l [&>[data-topbar-group]+[data-topbar-group]]:border-border/60 [&>[data-topbar-group]+[data-topbar-group]]:pl-1 sm:[&>[data-topbar-group]+[data-topbar-group]]:pl-2 sm:[&>[data-topbar-group]+[data-topbar-group]]:ml-2", children: [!isOnline && (_jsxs("div", { className: "flex items-center gap-1 px-2 py-1 rounded-full bg-yellow-100 dark:bg-yellow-900/30 text-yellow-800 dark:text-yellow-200 text-xs font-medium", children: [_jsx("span", { className: "h-2 w-2 rounded-full bg-yellow-500 animate-pulse" }), t('topbar.offline', { defaultValue: 'Offline' })] })), isApp && connectionState && _jsx(ConnectionStatus, { state: connectionState }), isApp && activeUsers.length > 0 && (_jsx("div", { className: "hidden md:flex items-center shrink-0", title: t('topbar.usersOnline', { defaultValue: 'Users currently online' }), children: _jsx(PresenceAvatars, { users: activeUsers, size: "sm", maxVisible: 3, showStatus: true }) })), _jsxs("div", { "data-topbar-group": true, className: "flex items-center gap-0.5 sm:gap-1 shrink-0", children: [_jsxs("button", { type: "button", "data-testid": "action:command-palette:open", "aria-label": t('console.search', { defaultValue: 'Search…' }), "aria-keyshortcuts": "Meta+K Control+K", onClick: openCommandPalette, className: "hidden lg:flex relative items-center gap-2 w-48 xl:w-64 h-8 px-3 text-sm rounded-md border bg-muted/50 text-muted-foreground hover:bg-muted transition-colors", children: [_jsx(Search, { className: "h-3.5 w-3.5 shrink-0" }), _jsx("span", { className: "flex-1 text-left text-xs", children: t('console.search', { defaultValue: 'Search…' }) }), _jsxs("kbd", { className: "pointer-events-none inline-flex h-5 items-center gap-0.5 rounded border bg-background px-1.5 text-[10px] font-medium text-muted-foreground", children: [_jsx("span", { className: "text-xs", children: "\u2318" }), "K"] })] }), _jsx(Button, { variant: "ghost", size: "icon", className: "lg:hidden h-8 w-8 shrink-0", "data-testid": "action:command-palette:open-mobile", onClick: openCommandPalette, "aria-label": t('console.search', { defaultValue: 'Search…' }), children: _jsx(Search, { className: "h-4 w-4" }) })] }), _jsxs("div", { "data-topbar-group": true, className: "flex items-center gap-0.5 shrink-0", children: [_jsx(InboxPopover, { notifications: notifications, unreadCount: unreadCount, pendingApprovalsCount: pendingApprovalsCount, activities: activeActivities, onMarkAllRead: markAllRead, onMarkRead: markNotificationRead }), aiEnabled && (_jsx(Button, { variant: "ghost", size: "icon", className: "h-8 w-8 shrink-0", asChild: true, "aria-label": t('topbar.aiAssistant', { defaultValue: 'AI Assistant' }), children: _jsx(Link, { to: "/ai", children: _jsx(Bot, { className: "h-4 w-4" }) }) })), _jsxs(DropdownMenu, { onOpenChange: (open) => { if (open)
                                     void loadHelpDocs(); }, children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx(Button, { variant: "ghost", size: "icon", className: "h-8 w-8 hidden md:flex shrink-0", "aria-label": t('sidebar.helpTooltip', { defaultValue: 'Help & Documentation' }), children: _jsx(HelpCircle, { className: "h-4 w-4" }) }) }), _jsxs(DropdownMenuContent, { align: "end", className: "min-w-56 rounded-lg", sideOffset: 4, children: [currentAppDocs.length > 0 && currentAppPackageId ? (_jsxs(DropdownMenuItem, { className: "cursor-pointer", onClick: () => navigate(currentAppDocs.length === 1
                                                     ? `/apps/${currentAppPackageId}/docs/${currentAppDocs[0].name}`
-                                                    : `/apps/${currentAppPackageId}/docs`), children: [_jsx(BookOpen, { className: "mr-2 h-4 w-4" }), t('help.appDocs', { defaultValue: "This app's docs" })] })) : null, _jsxs(DropdownMenuItem, { className: "cursor-pointer", onClick: () => navigate('/docs'), children: [_jsx(Layers, { className: "mr-2 h-4 w-4" }), t('help.allDocs', { defaultValue: 'All documentation' })] }), isApp ? (_jsxs(DropdownMenuItem, { className: "cursor-pointer", "data-testid": "action:keyboard-shortcuts:open", onClick: openShortcuts, children: [_jsx(Keyboard, { className: "mr-2 h-4 w-4" }), t('help.keyboardShortcuts', { defaultValue: 'Keyboard shortcuts' })] })) : null, _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { asChild: true, className: "cursor-pointer", children: _jsxs("a", { href: "https://docs.objectstack.ai", target: "_blank", rel: "noopener noreferrer", children: [_jsx(ExternalLink, { className: "mr-2 h-4 w-4" }), t('help.onlineDocs', { defaultValue: 'Online documentation' })] }) })] })] })] }), _jsxs("div", { "data-topbar-group": true, className: "flex items-center gap-0.5 shrink-0", children: ["        ", _jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx(Button, { variant: "ghost", size: "icon", className: "h-8 w-8 shrink-0 rounded-full", children: _jsxs(Avatar, { className: "h-7 w-7 rounded-full", children: [_jsx(AvatarImage, { src: user?.image, alt: user?.name ?? 'User' }), _jsx(AvatarFallback, { className: "rounded-full bg-primary text-primary-foreground text-xs", children: getUserInitials(user) })] }) }) }), _jsxs(DropdownMenuContent, { align: "end", className: "min-w-64 rounded-lg", sideOffset: 4, children: [_jsx(DropdownMenuLabel, { className: "p-0 font-normal", children: _jsxs("div", { className: "flex items-center gap-2 px-2 py-2", children: [_jsxs(Avatar, { className: "h-8 w-8 rounded-lg", children: [_jsx(AvatarImage, { src: user?.image, alt: user?.name ?? 'User' }), _jsx(AvatarFallback, { className: "rounded-lg bg-primary text-primary-foreground", children: getUserInitials(user) })] }), _jsxs("div", { className: "grid flex-1 text-left text-sm leading-tight", children: [_jsx("span", { className: "truncate font-semibold", children: user?.name ?? 'User' }), _jsx("span", { className: "truncate text-xs text-muted-foreground", children: user?.email ?? '' })] })] }) }), _jsx(DropdownMenuSeparator, {}), _jsxs(DropdownMenuGroup, { children: [_jsxs(DropdownMenuItem, { onClick: () => navigate('/apps/account/component/account/profile_card'), className: "cursor-pointer", children: [_jsx(User, { className: "mr-2 h-4 w-4" }), t('user.profile', { defaultValue: 'Profile' })] }), hasOrgSection && (_jsxs(DropdownMenuItem, { onClick: () => navigate('/organizations'), className: "cursor-pointer", children: [_jsx(Boxes, { className: "mr-2 h-4 w-4" }), t('organizations.mine', { defaultValue: 'My Organizations' })] })), (metadataApps || [])
+                                                    : `/apps/${currentAppPackageId}/docs`), children: [_jsx(BookOpen, { className: "mr-2 h-4 w-4" }), t('help.appDocs', { defaultValue: "This app's docs" })] })) : null, _jsxs(DropdownMenuItem, { className: "cursor-pointer", onClick: () => navigate('/docs'), children: [_jsx(Layers, { className: "mr-2 h-4 w-4" }), t('help.allDocs', { defaultValue: 'All documentation' })] }), isApp ? (_jsxs(DropdownMenuItem, { className: "cursor-pointer", "data-testid": "action:keyboard-shortcuts:open", onClick: openShortcuts, children: [_jsx(Keyboard, { className: "mr-2 h-4 w-4" }), t('help.keyboardShortcuts', { defaultValue: 'Keyboard shortcuts' })] })) : null, _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { asChild: true, className: "cursor-pointer", children: _jsxs("a", { href: "https://docs.objectstack.ai", target: "_blank", rel: "noopener noreferrer", children: [_jsx(ExternalLink, { className: "mr-2 h-4 w-4" }), t('help.onlineDocs', { defaultValue: 'Online documentation' })] }) })] })] })] }), _jsxs("div", { "data-topbar-group": true, className: "flex items-center gap-0.5 shrink-0", children: ["        ", _jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx(Button, { variant: "ghost", size: "icon", className: "h-8 w-8 shrink-0 rounded-full", children: _jsxs(Avatar, { className: "h-7 w-7 rounded-full", children: [_jsx(AvatarImage, { src: user?.image, alt: user?.name ?? 'User' }), _jsx(AvatarFallback, { className: "rounded-full bg-primary text-primary-foreground text-xs", children: getUserInitials(user) })] }) }) }), _jsxs(DropdownMenuContent, { align: "end", className: "min-w-64 rounded-lg", sideOffset: 4, children: [_jsx(DropdownMenuLabel, { className: "p-0 font-normal", children: _jsxs("div", { className: "flex items-center gap-2 px-2 py-2", children: [_jsxs(Avatar, { className: "h-8 w-8 rounded-lg", children: [_jsx(AvatarImage, { src: user?.image, alt: user?.name ?? 'User' }), _jsx(AvatarFallback, { className: "rounded-lg bg-primary text-primary-foreground", children: getUserInitials(user) })] }), _jsxs("div", { className: "grid flex-1 text-left text-sm leading-tight", children: [_jsx("span", { className: "truncate font-semibold", children: user?.name ?? 'User' }), _jsx("span", { className: "truncate text-xs text-muted-foreground", children: user?.email ?? '' })] })] }) }), _jsx(DropdownMenuSeparator, {}), _jsxs(DropdownMenuGroup, { children: [_jsxs(DropdownMenuItem, { onClick: () => navigate('/apps/account/component/account/profile_card'), className: "cursor-pointer", children: [_jsx(User, { className: "mr-2 h-4 w-4" }), t('user.profile', { defaultValue: 'Profile' })] }), hasOrgSection && (_jsxs(DropdownMenuItem, { onClick: () => navigate('/organizations?manage=1'), className: "cursor-pointer", children: [_jsx(Boxes, { className: "mr-2 h-4 w-4" }), t('organizations.mine', { defaultValue: 'My Organizations' })] })), hasOrgSection && !multiOrgDisabled && (_jsxs(DropdownMenuItem, { onClick: () => navigate('/organizations?create=1'), className: "cursor-pointer", "data-testid": "header-create-workspace", children: [_jsx(Plus, { className: "mr-2 h-4 w-4" }), t('organizations.create', { defaultValue: 'Create workspace' })] })), (metadataApps || [])
                                                         .filter((a) => a.active !== false && a.hidden === true && a.name !== 'account')
                                                         .map((app) => {
                                                         const AppIcon = getIcon(app.icon);

package/dist/layout/ConsoleFloatingChatbot.js

@@ -13,7 +13,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  */
 import React from 'react';
 import { useReconcileOnError } from '../hooks/useReconcileOnError';
-import { FloatingChatbot, useObjectChat, useAgents, useHitlInChat, resolveDefaultAgentName, uiMessagesToChatMessages, publishHealthFromResponse, agentRouteName, } from '@object-ui/plugin-chatbot';
+import { FloatingChatbot, useObjectChat, useAgents, useAiModels, useHitlInChat, resolveDefaultAgentName, uiMessagesToChatMessages, publishHealthFromResponse, agentRouteName, } from '@object-ui/plugin-chatbot';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Button, ShareDialog, } from '@object-ui/components';
 import { Share2, SquarePen } from 'lucide-react';
 import { useObjectTranslation } from '@object-ui/i18n';
@@ -257,6 +257,14 @@ function ChatbotInner({ appLabel, appName, objects, agents, agentsLoading, activ
     // the agent context so "add a priority field" acts on the open object,
     // and drives context-aware starter suggestions.
     const { editor } = useAssistant();
+    // ADR-0028: the plan-filtered AI-model allowlist this env offers in the
+    // picker (free / single-model envs return one entry → the footer picker
+    // hides itself). The selected id is sent with each turn; the backend
+    // validates it against the same allowlist and weights the quota by the
+    // chosen model's cost_weight.
+    const { models: aiModels, defaultModelId } = useAiModels({ apiBase });
+    const [selectedModelId, setSelectedModelId] = React.useState(undefined);
+    const effectiveModelId = selectedModelId ?? defaultModelId;
     // Replay persisted history when present.
     const hydratedHistory = React.useMemo(() => {
         if (!persistedMessages || persistedMessages.length === 0)
@@ -277,6 +285,9 @@ function ChatbotInner({ appLabel, appName, objects, agents, agentsLoading, activ
     const { messages, isLoading, error, sendMessage, stop, reload, clear, setMessages, } = useObjectChat({
         api: chatApi,
         conversationId,
+        // ADR-0028: the user's picked model (or the env default) — sent in each
+        // request body; the agent route validates it + routes the turn to it.
+        model: effectiveModelId,
         onError: handleChatError,
         body: {
             context: {
@@ -348,7 +359,10 @@ function ChatbotInner({ appLabel, appName, objects, agents, agentsLoading, activ
                     panelHeight: 560,
                     title: locale.title,
                     triggerSize: 56,
-                }, headerExtra: headerExtra, headerActions: headerActions, messages: messages, labels: locale.labels, showAvatars: true, hideClearBar: true, assistantAvatarFallback: locale.agentLabel, suggestions: messages.length === 0 ? (editorSuggestions ?? locale.suggestions) : undefined, placeholder: activeAgent
+                }, headerExtra: headerExtra, headerActions: headerActions, messages: messages, labels: locale.labels, 
+                // ADR-0028: model picker — ChatbotEnhanced renders the footer <select>
+                // only when 2+ models are offered, so free / single-model envs see none.
+                models: aiModels, selectedModelId: effectiveModelId, onModelChange: setSelectedModelId, showAvatars: true, hideClearBar: true, assistantAvatarFallback: locale.agentLabel, suggestions: messages.length === 0 ? (editorSuggestions ?? locale.suggestions) : undefined, placeholder: activeAgent
                     ? locale.placeholder
                     : agentsLoading
                         ? locale.loadingPlaceholder

package/dist/layout/ConsoleLayout.js

@@ -10,7 +10,6 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
  */
 import { useEffect } from 'react';
 import { AppShell } from '@object-ui/layout';
-import { useDiscovery } from '@object-ui/react';
 import { isBuildAgent } from '@object-ui/plugin-chatbot';
 // Lightweight FAB stub — the heavy chat chunk graph (plugin-chatbot,
 // shiki, streamdown, mermaid, @ai-sdk, ~20MB) only downloads on first
@@ -22,6 +21,7 @@ import { UnifiedSidebar } from './UnifiedSidebar';
 import { AppHeader } from './AppHeader';
 import { MobileViewSwitcherProvider } from './MobileViewSwitcherContext';
 import { useResponsiveSidebar } from '../hooks/useResponsiveSidebar';
+import { useAiSurfaceEnabled } from '../hooks/useAiSurface';
 import { useNavigationContext } from '../context/NavigationContext';
 import { CommandPaletteProvider } from '../context/CommandPaletteProvider';
 import { resolveI18nLabel } from '../utils';
@@ -35,11 +35,10 @@ function ConsoleLayoutInner({ children }) {
 // (moved to ./ConsoleFloatingChatbot.tsx for code-splitting)
 export function ConsoleLayout({ children, activeAppName, activeApp, onAppChange, objects, connectionState, userId, }) {
     const appLabel = resolveI18nLabel(activeApp?.label) || activeAppName;
-    const { isAiEnabled } = useDiscovery();
-    // Trust an explicit `VITE_AI_BASE_URL` 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;
+    // Runtime, server-pushed AI gating (shared with the `/ai` route guard and the
+    // top-bar AI link): show the chatbot only when the server actually serves AI,
+    // or when an explicit `VITE_AI_BASE_URL` opt-in points at an external server.
+    const { enabled: showChatbot } = useAiSurfaceEnabled();
     // AI Studio (AI-driven metadata authoring / "online development") can be
     // turned off per deployment. When off, suppress the metadata-authoring
     // assistant so the chatbot falls back to the generic data assistant — the