@datalayer/agent-runtimes 1.3.10 → 1.3.13

package/README.md

@@ -10,8 +10,7 @@
 
 # 🤖 🚀 Agent Runtimes
 
-[![Github Actions Status](https://github.com/datalayer/agent-runtimes/actions/workflows/build.yml/badge.svg)](https://github.com/datalayer/agent-runtimes/actions/workflows/build.yml)
-[![Netlify Status](https://api.netlify.com/api/v1/badges/f7f9e08a-884f-4f76-b20d-666d5873716c/deploy-status)](https://app.netlify.com/projects/agent-runtimes/deploys)
+[![Github Actions Status](https://github.com/datalayer/agent-runtimes/actions/workflows/build.yaml/badge.svg)](https://github.com/datalayer/agent-runtimes/actions/workflows/build.yaml)
 [![PyPI - Version](https://img.shields.io/pypi/v/agent-runtimes)](https://pypi.org/project/agent-runtimes)
 
 **Agent Runtimes** is a unified library for deploying, managing, and interacting with AI agents across multiple protocols and frameworks. It provides both a Python server for hosting agents and React components for seamless integration into web and desktop applications.

package/lib/AgentNode.js

@@ -819,8 +819,8 @@ export function AgentNode() {
             const aiAgentsUrl = getConfigUrlFromDocument('aiAgentsUrl') ||
                 import.meta.env?.VITE_DATALAYER_AI_AGENTS_URL ||
                 'https://r1.datalayer.run';
-            const jupyterMcpServerUrl = getConfigUrlFromDocument('jupyterMcpServerUrl') ||
-                import.meta.env?.VITE_DATALAYER_JUPYTER_MCP_SERVER_URL ||
+            const datalayerMcpServerUrl = getConfigUrlFromDocument('datalayerMcpServerUrl') ||
+                import.meta.env?.VITE_DATALAYER_MCP_SERVER_URL ||
                 'https://mcp.datalayer.run/mcp';
             // Seed all per-service URLs to match the main UI login behavior.
             const coreApi = coreStore.getState();
@@ -832,7 +832,7 @@ export function AgentNode() {
                 libraryUrl: iamUrl,
                 aiAgentsUrl,
                 aiInferenceUrl: aiInferenceUrl,
-                jupyterMcpServerUrl,
+                datalayerMcpServerUrl,
                 otelUrl: iamUrl,
                 growthUrl: iamUrl,
                 successUrl: iamUrl,

package/lib/api/runtimes/environments.d.ts

@@ -1,5 +1,5 @@
 import type { EnvironmentData, ListEnvironmentsResponse } from '../../models/EnvironmentDTO';
-import type { ICreateEnvironmentBuildsRequest, ICreateEnvironmentRequest, ICreateEnvironmentVersionRequest, IDatalayerEnvironment, IEnvironmentArtifactsPage, IEnvironmentBuildLogChunk, IEnvironmentBuildLogPage, IEnvironmentBuildRecord, IEnvironmentBuildsCreated, IEnvironmentBuildsPage, IEnvironmentFork, IEnvironmentPublicationRecord, IEnvironmentRecord, IEnvironmentsError, IEnvironmentsPageQuery, IEnvironmentTrial, IEnvironmentValidationReport, IEnvironmentVersionRecord, IEnvironmentVersionsPage, IForkEnvironmentVersionRequest, IListEnvironmentsQuery, IPromoteEnvironmentVersionRequest, ITrialEnvironmentVersionRequest, IUpdateEnvironmentRequest, IUpdateEnvironmentVersionRequest, IValidateEnvironmentVersionRequest } from '../../models/Environment';
+import type { ICreateEnvironmentBuildsRequest, ICreateEnvironmentRequest, ICreateEnvironmentVersionRequest, IDatalayerEnvironment, IEnvironmentArtifactsPage, IEnvironmentBuildLogChunk, IEnvironmentBuildLogPage, IEnvironmentBuildRecord, IEnvironmentBuildsCreated, IEnvironmentBuildsPage, IEnvironmentFork, IEnvironmentPublicationRecord, IEnvironmentQuotas, IEnvironmentRecord, IEnvironmentVersionSandboxes, IEnvironmentsError, IEnvironmentsPageQuery, IEnvironmentTrial, IEnvironmentValidationReport, IEnvironmentVersionRecord, IEnvironmentVersionsPage, IForkEnvironmentVersionRequest, IListEnvironmentsQuery, IPromoteEnvironmentVersionRequest, ITrialEnvironmentVersionRequest, IUpdateEnvironmentRequest, IUpdateEnvironmentVersionRequest, IValidateEnvironmentVersionRequest } from '../../models/Environment';
 /** What every environments call may carry. */
 export interface IEnvironmentsRequestOptions {
     /** Sent as `X-Correlation-Id`; a refusal answers with it. */
@@ -197,6 +197,27 @@ export declare const createEnvironmentBuilds: (token: string, versionUid: string
  * @returns Promise resolving to one page of builds
  */
 export declare const listEnvironmentBuilds: (token: string, versionUid: string, page?: IEnvironmentsPageQuery, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentBuildsPage>;
+/**
+ * The sandboxes running a version now: yours by uid, anybody else's counted (E2-19).
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the version's live sandboxes
+ */
+export declare const getEnvironmentVersionSandboxes: (token: string, versionUid: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentVersionSandboxes>;
+/**
+ * An owner's build quotas and what it holds against each (E1-13, E2-19).
+ * @param token - Authentication token
+ * @param owner - The caller's own when empty; an organization's by its uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the limits and the holdings
+ */
+export declare const getEnvironmentQuotas: (token: string, owner?: {
+    ownerType?: "user" | "organization";
+    ownerUid?: string;
+}, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentQuotas>;
 /**
  * List a version's artifacts, one per variant and region.
  * @param token - Authentication token

package/lib/api/runtimes/environments.js

@@ -293,6 +293,37 @@ export const listEnvironmentBuilds = async (token, versionUid, page = {}, option
     validateToken(token);
     return send(token, 'GET', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/builds`, { ...page }), options);
 };
+/**
+ * The sandboxes running a version now: yours by uid, anybody else's counted (E2-19).
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the version's live sandboxes
+ */
+export const getEnvironmentVersionSandboxes = async (token, versionUid, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    return send(token, 'GET', registryUrl(baseUrl, `/environment-versions/${segment(versionUid, 'Version UID')}/sandboxes`), options);
+};
+/**
+ * An owner's build quotas and what it holds against each (E1-13, E2-19).
+ * @param token - Authentication token
+ * @param owner - The caller's own when empty; an organization's by its uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the limits and the holdings
+ */
+export const getEnvironmentQuotas = async (token, owner = {}, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    const query = {};
+    if (owner.ownerType) {
+        query.ownerType = owner.ownerType;
+    }
+    if (owner.ownerUid) {
+        query.ownerUid = owner.ownerUid;
+    }
+    return send(token, 'GET', registryUrl(baseUrl, '/environment-quotas', query), options);
+};
 /**
  * List a version's artifacts, one per variant and region.
  * @param token - Authentication token

package/lib/api/runtimes/healthz.js

@@ -36,9 +36,11 @@ export const ping = async (baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
         // Check if it's a response error with status code information
         if (error.response) {
             const status = error.response.status;
-            throw new Error(`Health check failed: Service unhealthy (status ${status}) - ${error.message}`);
+            throw new Error(`Health check failed: Service unhealthy (status ${status}) - ${error.message}`, { cause: error });
         }
         // Re-throw other errors (network errors, etc.)
-        throw new Error(`Health check failed: ${error.message}`);
+        throw new Error(`Health check failed: ${error.message}`, {
+            cause: error,
+        });
     }
 };

package/lib/api/spacer/healthz.js

@@ -36,9 +36,11 @@ export const ping = async (baseUrl = DEFAULT_SERVICE_URLS.SPACER) => {
         // Check if it's a response error with status code information
         if (error.response) {
             const status = error.response.status;
-            throw new Error(`Health check failed: Service unhealthy (status ${status}) - ${error.message}`);
+            throw new Error(`Health check failed: Service unhealthy (status ${status}) - ${error.message}`, { cause: error });
         }
         // Re-throw other errors (network errors, etc.)
-        throw new Error(`Health check failed: ${error.message}`);
+        throw new Error(`Health check failed: ${error.message}`, {
+            cause: error,
+        });
     }
 };

package/lib/chat/ChatFloating.d.ts

@@ -49,6 +49,13 @@ export interface ChatFloatingProps extends ChatCommonProps {
     buttonTooltip?: string;
     /** Brand color override. Defaults to the theme's `accent.emphasis` token. */
     brandColor?: string;
+    /**
+     * A soft light breathing around the button while the chat is closed, as
+     * if it were alive (see `ButtonGlow`). Still, and dimmer, for a reader who
+     * asks the system for reduced motion.
+     * @default true
+     */
+    buttonGlow?: boolean;
     /** Offset from edge (in pixels) */
     offset?: number;
     /** Animation duration (in ms) */
@@ -92,5 +99,5 @@ export interface ChatFloatingProps extends ChatCommonProps {
  * ChatFloating component
  * A floating chat window built on ChatBase
  */
-export declare function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose, escapeToClose, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip, brandColor, offset, animationDuration, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, defaultViewMode, onViewModeChange, sidebarMountPoint, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, showContextRing, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, }: ChatFloatingProps): React.JSX.Element;
+export declare function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose, escapeToClose, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip, brandColor, buttonGlow, offset, animationDuration, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, defaultViewMode, onViewModeChange, sidebarMountPoint, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, showContextRing, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, }: ChatFloatingProps): React.JSX.Element;
 export default ChatFloating;

package/lib/chat/ChatFloating.js

@@ -23,6 +23,7 @@ import { XIcon, CommentDiscussionIcon, GrabberIcon, } from '@primer/octicons-rea
 import { AiAgentIcon } from '@datalayer/icons-react';
 import { createPortal } from 'react-dom';
 import { ChatBase } from './base/ChatBase';
+import { ButtonGlow } from './display/ButtonGlow';
 import { useViewportDrag } from './useViewportDrag';
 import { disabledChatViewModes, resolveMountPoint } from './viewModes';
 import { useChatOpen, useChatMessages, useChatStore, } from '../stores/chatStore';
@@ -46,7 +47,7 @@ function useIsMobile(breakpoint = 640) {
  * ChatFloating component
  * A floating chat window built on ChatBase
  */
-export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode = true, title = 'Chat', description = 'Start a conversation with the AI agent.', position = 'bottom-right', defaultOpen = false, width = 400, height = 550, showHeader = true, showButton = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = '/', showPoweredBy = true, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, sidebarMountPoint = null, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, showContextRing = false, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation = false, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching = false, launchingMessage, }) {
+export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode = true, title = 'Chat', description = 'Start a conversation with the AI agent.', position = 'bottom-right', defaultOpen = false, width = 400, height = 550, showHeader = true, showButton = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = '/', showPoweredBy = true, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, buttonGlow = true, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, sidebarMountPoint = null, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, showContextRing = false, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation = false, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching = false, launchingMessage, }) {
     // Store-based state
     const storeIsOpen = useChatOpen();
     const storeMessages = useChatMessages();
@@ -555,7 +556,9 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                 }, children: _jsxs(Box, { sx: {
                         position: 'relative',
                         display: 'inline-flex',
-                    }, onMouseEnter: () => setIsHovered(true), onMouseLeave: () => setIsHovered(false), children: [_jsx(Tooltip, { text: `${buttonTooltip}${shortcutHint ? ` (${shortcutHint})` : ''}`, direction: position.includes('right') ? 'w' : 'e', children: _jsx(IconButton, { icon: buttonIcon
+                        // The glow's halos go behind the button, not behind the page.
+                        isolation: 'isolate',
+                    }, onMouseEnter: () => setIsHovered(true), onMouseLeave: () => setIsHovered(false), children: [buttonGlow && _jsx(ButtonGlow, { color: brandColor }), _jsx(Tooltip, { text: `${buttonTooltip}${shortcutHint ? ` (${shortcutHint})` : ''}`, direction: position.includes('right') ? 'w' : 'e', children: _jsx(IconButton, { icon: buttonIcon
                                     ? buttonIcon
                                     : CommentDiscussionIcon, "aria-label": buttonTooltip, onClick: handleToggle, size: "large", sx: {
                                     width: 56,

package/lib/chat/base/ChatBase.js

@@ -31,7 +31,7 @@ import { useChatStore } from '../../stores/chatStore';
 import { useConversationStore } from '../../stores/conversationStore';
 import { generateMessageId, createUserMessage, createAssistantMessage, } from '../../types/messages';
 import { AgentDetails } from '../../agents/AgentDetails';
-import { AI_MODEL_CATALOGUE } from '../../specs/models';
+import { AI_MODEL_CATALOGUE, DEFAULT_MODEL } from '../../specs/models';
 import { internalQueryClient, isToolCallMessage, convertHistoryToDisplayItems, createProtocolAdapter, getApiBaseFromConfig, sanitizeAssistantContent, } from '../../utils';
 import { useConfig, useSkills, useSkillActions, useContextSnapshot, useSandbox, } from '../../hooks';
 import { useAgentRuntimeWebSocket } from '../../hooks/useAgentRuntimes';
@@ -48,6 +48,7 @@ import { InputPrompt } from '../prompt/InputPrompt';
 import { isFloatingChatViewMode } from '../viewModes';
 import { ToolApprovalBanner, ToolApprovalDialog, } from '../tools';
 import { EphemeralNotebook } from '../notebook/EphemeralNotebook';
+import { initialModelId, isOffered, usableModels } from './modelChoice';
 // EphemeralDocument statically imports `@datalayer/jupyter-lexical` (which
 // initialises Lumino-backed nodes on load). Lazy-load it so notebook-only chats
 // never pull lexical into the bundle or trigger its module side effects.
@@ -1378,9 +1379,10 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         ? (protocol?.options).model
         : undefined;
     const offeredModels = useMemo(() => {
+        // Only what can actually be called — see `modelChoice` for the rule.
         const fromConfig = availableModels || configQuery.data?.models;
         if (fromConfig?.length) {
-            return fromConfig;
+            return usableModels(fromConfig);
         }
         /*
          * The catalogue, filtered to what is worth offering.
@@ -1402,7 +1404,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             provider: model.provider,
         }));
         if (catalogued.length > 0) {
-            return catalogued;
+            return usableModels(catalogued);
         }
         return browserModel
             ? [{ id: browserModel, name: browserModel, provider: 'inference' }]
@@ -1721,7 +1723,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         const timer = setTimeout(adjustTextareaHeight, 0);
         return () => clearTimeout(timer);
     }, [adjustTextareaHeight]);
-    // ---- Initialize model and tools when config is available ----
+    // ---- The model, whenever what is offered changes ----
     useEffect(() => {
         /*
          * `offeredModels`, not the two sources it is built from.
@@ -1731,28 +1733,40 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
          * sources, so that model was offered by the menu and never selected. The
          * menu draws nothing without a selection, so a browser agent had a model
          * list of one and no model control at all.
+         *
+         * Re-picked, not picked once. Before the server has answered, the offer
+         * is the browser's catalogue, and the chat chose from it — the first row,
+         * Alibaba, which the catalogue marks available because the platform is
+         * entitled to it. The server then answered with the one model this
+         * process can call, the guess was not in it, and nothing looked again:
+         * the trigger read "none selected" while every turn was still sent to
+         * Alibaba and came back asking for its key. A selection stands only while
+         * it is offered and usable; otherwise the preferred model — the agent's
+         * own, from the server — or the first usable one takes its place.
          */
-        if (offeredModels.length > 0 && !selectedModel) {
-            const modelsList = offeredModels;
-            const preferredModel = initialModel || configQuery.data?.defaultModel;
-            if (preferredModel) {
-                const modelExists = modelsList.some(m => m.id === preferredModel);
-                if (modelExists) {
-                    setSelectedModel(preferredModel);
-                }
-                else {
-                    const firstAvailableModel = modelsList.find(m => m.isAvailable !== false);
-                    const firstModel = firstAvailableModel || modelsList[0];
-                    if (firstModel)
-                        setSelectedModel(firstModel.id);
-                }
-            }
-            else {
-                const firstAvailableModel = modelsList.find(m => m.isAvailable !== false);
-                const firstModel = firstAvailableModel || modelsList[0];
-                if (firstModel)
-                    setSelectedModel(firstModel.id);
-            }
+        if (offeredModels.length === 0 || isOffered(offeredModels, selectedModel)) {
+            return;
+        }
+        // The host's word first, then the server's default, then the platform's:
+        // the first row of a catalogue is an order of listing, not a choice, and
+        // opening on it sent the first message to Alibaba while the footer —
+        // drawn from the host's own model — said Claude.
+        const opening = initialModelId(offeredModels, initialModel || configQuery.data?.defaultModel || DEFAULT_MODEL);
+        if (opening && opening !== selectedModel) {
+            setSelectedModel(opening);
+        }
+    }, [
+        offeredModels,
+        selectedModel,
+        initialModel,
+        configQuery.data?.defaultModel,
+    ]);
+    // ---- Initialize tools when config is available ----
+    const toolsInitializedRef = useRef(false);
+    useEffect(() => {
+        // Once: a later change to the offer must not undo what the reader toggled.
+        if (offeredModels.length > 0 && !toolsInitializedRef.current) {
+            toolsInitializedRef.current = true;
             const allToolIds = configQuery.data?.builtinTools?.map(tool => tool.id) || [];
             setEnabledTools(allToolIds);
             if (configQuery.data?.mcpServers) {

package/lib/chat/base/modelChoice.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Which models a chat offers, and which one it opens on.
+ *
+ * Two rules, kept out of `ChatBase` so they can be read and tested without
+ * rendering a chat:
+ *
+ * - **Only what can be called is offered.** A server answers with its whole
+ *   catalogue and a flag per model, and the menu used to draw all of it, most
+ *   rows greyed out with a reason. Thirty models to choose two from reads as
+ *   a broken menu, and the one thing it guarantees is that a reader's first
+ *   click lands on something that cannot answer.
+ * - **The default has to be one of them.** A default naming a model this
+ *   deployment cannot use — a spec claiming the default while marked
+ *   unavailable — opened every chat on it, and the first message came back
+ *   as the provider's complaint about a missing key.
+ *
+ * @module chat/base/modelChoice
+ */
+import type { ModelConfig } from '../../types/chat';
+/** Whether a model can be picked: the flag says no, or says nothing. */
+export declare const isUsable: (model: ModelConfig) => boolean;
+/**
+ * The models to offer: the usable ones.
+ *
+ * When none is usable the list is kept whole. An empty menu says nothing,
+ * while the rows and their reasons say which key is missing.
+ */
+export declare function usableModels(models: ModelConfig[]): ModelConfig[];
+/** Whether `id` is on offer and usable — the selection may stand. */
+export declare const isOffered: (offered: ModelConfig[], id?: string) => boolean;
+/**
+ * The model a chat opens on.
+ *
+ * The preferred one when it is offered *and* usable; otherwise the first
+ * usable one; otherwise the first there is. `undefined` when there is none.
+ */
+export declare function initialModelId(offered: ModelConfig[], preferred?: string | null): string | undefined;
+/**
+ * One row of `/api/v1/configure/models`, as the server writes it.
+ *
+ * Snake case and its own flag names: the route is read by more than this
+ * chat, and its shape is the server's to keep.
+ */
+export type ServerCatalogueModel = {
+    id: string;
+    name?: string;
+    available?: boolean;
+    missing_env_vars?: string[];
+    reason?: string;
+    warning?: string | null;
+};
+/**
+ * The server's catalogue in the chat's shape.
+ *
+ * The route says `available`; the chat, the menu and the rules above read
+ * `isAvailable`. Handed over unmapped, every row looked usable, the menu
+ * offered all thirty-one, and the first message of a chat that opened before
+ * its spec was known went to the first row — Alibaba, and its missing key.
+ */
+export declare function readServerCatalogue(payload: {
+    models?: ServerCatalogueModel[];
+} | null | undefined): ModelConfig[];

package/lib/chat/base/modelChoice.js

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Whether a model can be picked: the flag says no, or says nothing. */
+export const isUsable = (model) => model.isAvailable !== false;
+/**
+ * The models to offer: the usable ones.
+ *
+ * When none is usable the list is kept whole. An empty menu says nothing,
+ * while the rows and their reasons say which key is missing.
+ */
+export function usableModels(models) {
+    const usable = models.filter(isUsable);
+    return usable.length > 0 ? usable : models;
+}
+/** Whether `id` is on offer and usable — the selection may stand. */
+export const isOffered = (offered, id) => Boolean(id) && offered.some(m => m.id === id && isUsable(m));
+/**
+ * The model a chat opens on.
+ *
+ * The preferred one when it is offered *and* usable; otherwise the first
+ * usable one; otherwise the first there is. `undefined` when there is none.
+ */
+export function initialModelId(offered, preferred) {
+    if (preferred && offered.some(m => m.id === preferred && isUsable(m))) {
+        return preferred;
+    }
+    const first = offered.find(isUsable) ?? offered[0];
+    return first?.id;
+}
+/**
+ * The server's catalogue in the chat's shape.
+ *
+ * The route says `available`; the chat, the menu and the rules above read
+ * `isAvailable`. Handed over unmapped, every row looked usable, the menu
+ * offered all thirty-one, and the first message of a chat that opened before
+ * its spec was known went to the first row — Alibaba, and its missing key.
+ */
+export function readServerCatalogue(payload) {
+    return (payload?.models ?? []).map(model => {
+        const missing = model.missing_env_vars ?? [];
+        const reason = model.reason ??
+            (missing.length > 0 ? `Set ${missing.join(', ')}` : undefined) ??
+            model.warning ??
+            undefined;
+        return {
+            id: model.id,
+            name: model.name ?? model.id,
+            isAvailable: model.available !== false,
+            ...(reason && model.available === false
+                ? { unavailableReason: reason }
+                : {}),
+        };
+    });
+}

package/lib/chat/display/ButtonGlow.d.ts

@@ -0,0 +1,9 @@
+export interface ButtonGlowProps {
+    /**
+     * The colour of the light: the button's own. A theme token or any CSS
+     * colour; the theme's `accent.emphasis` when absent.
+     */
+    color?: string;
+}
+export declare function ButtonGlow({ color }: ButtonGlowProps): import("react").JSX.Element;
+export default ButtonGlow;

package/lib/chat/display/ButtonGlow.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A soft light breathing around a round button, as if it were alive.
+ *
+ * Two blurred halos in the button's colour swell and fade on cycles of
+ * different lengths, 3.4 s and 5.3 s, so the light drifts rather than
+ * blinks: the two never line up the same way twice in a row. For a reader
+ * who asks the system for less motion, the halos hold still, a little dimmer.
+ *
+ * The halos sit behind the button: the parent must be `position: relative`
+ * and make a stacking context of its own (`isolation: 'isolate'`), or they
+ * would slip behind the page instead.
+ *
+ * @module chat/display/ButtonGlow
+ */
+import { Box } from '@datalayer/primer-addons';
+const halo = (color) => ({
+    position: 'absolute',
+    inset: 0,
+    borderRadius: '50%',
+    bg: color || 'accent.emphasis',
+    zIndex: -1,
+    pointerEvents: 'none',
+    willChange: 'transform, opacity',
+});
+export function ButtonGlow({ color }) {
+    return (_jsxs(_Fragment, { children: [_jsx(Box, { "aria-hidden": true, "data-button-glow": "breath", sx: {
+                    ...halo(color),
+                    filter: 'blur(10px)',
+                    animation: 'agentRuntimesGlowBreath 3.4s ease-in-out infinite',
+                    '@keyframes agentRuntimesGlowBreath': {
+                        '0%, 100%': { transform: 'scale(0.9)', opacity: 0.35 },
+                        '50%': { transform: 'scale(1.25)', opacity: 0.7 },
+                    },
+                    '@media (prefers-reduced-motion: reduce)': {
+                        animation: 'none',
+                        transform: 'scale(1.1)',
+                        opacity: 0.4,
+                    },
+                } }), _jsx(Box, { "aria-hidden": true, "data-button-glow": "aura", sx: {
+                    ...halo(color),
+                    filter: 'blur(18px)',
+                    animation: 'agentRuntimesGlowAura 5.3s ease-in-out infinite',
+                    '@keyframes agentRuntimesGlowAura': {
+                        '0%, 100%': { transform: 'scale(1)', opacity: 0.15 },
+                        '40%': { transform: 'scale(1.55)', opacity: 0.4 },
+                        '70%': { transform: 'scale(1.3)', opacity: 0.25 },
+                    },
+                    '@media (prefers-reduced-motion: reduce)': {
+                        animation: 'none',
+                        transform: 'scale(1.3)',
+                        opacity: 0.2,
+                    },
+                } })] }));
+}
+export default ButtonGlow;

package/lib/chat/display/EmptyState.js

@@ -50,6 +50,9 @@ export function ChatEmptyState({ emptyState, brandIcon, description, suggestions
                 cursor: 'pointer',
                 display: 'inline-flex',
                 alignItems: 'center',
+                // A short opener sits in the middle of its fixed-width chip, not
+                // against its left edge with the rest of the chip empty.
+                justifyContent: 'center',
                 width: SUGGESTION_CHIP_WIDTH,
                 flex: `0 0 ${SUGGESTION_CHIP_WIDTH}px`,
                 '&:hover': {
@@ -57,7 +60,7 @@ export function ChatEmptyState({ emptyState, brandIcon, description, suggestions
                     color: 'var(--button-primary-fgColor-rest)',
                     borderColor: 'accent.emphasis',
                 },
-            }, onClick: () => handleSuggestionClick(suggestion), children: _jsx(Truncate, { title: suggestion.message, maxWidth: "100%", sx: { minWidth: 0 }, children: suggestion.title }) }, index))) }));
+            }, onClick: () => handleSuggestionClick(suggestion), children: _jsx(Truncate, { inline: true, title: suggestion.message, maxWidth: "100%", sx: { minWidth: 0 }, children: suggestion.title }) }, index))) }));
     return (_jsx(ThemeProvider, { children: _jsxs(Box, { sx: {
                 display: 'flex',
                 flexDirection: 'column',

package/lib/chat/header/ChatHeaderBase.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Heading, IconButton, Label, Text, Tooltip, Truncate, } from '@primer/react';
+import { Heading, IconButton, Label, Text, Truncate } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { KernelIndicator } from '@datalayer/jupyter-react';
-import { PlusIcon, TrashIcon, GearIcon, CommentDiscussionIcon, DeviceMobileIcon, SidebarExpandIcon, GrabberIcon, InfoIcon, } from '@primer/octicons-react';
-import { CHAT_VIEW_MODES, SIDEBAR_NEEDS_MOUNT_POINT } from '../viewModes';
+import { PlusIcon, TrashIcon, GearIcon, InfoIcon, } from '@primer/octicons-react';
+import { ChatViewModeToggle } from './ChatViewModeToggle';
 import { AiAgentIcon } from '@datalayer/icons-react';
 import { EphemeralSurfaceControl } from '../EphemeralSurfaceControl';
 export function toRuntimeExecutionState(runtimeStatus) {
@@ -29,16 +29,6 @@ export function toRuntimeExecutionState(runtimeStatus) {
     return undefined;
 }
 // ---------------------------------------------------------------------------
-// Props
-// ---------------------------------------------------------------------------
-/** The drawing of each mode in the header's toggle. */
-const VIEW_MODE_ICONS = {
-    floating: CommentDiscussionIcon,
-    'floating-small': DeviceMobileIcon,
-    'floating-draggable': GrabberIcon,
-    sidebar: SidebarExpandIcon,
-};
-// ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
 export function ChatBaseHeader({ title, subtitle, disableReason, brandIcon, headerContent, headerActions, showInformation, onInformationClick, padding, kernelIndicatorState, kernelIndicatorPlacement = 'left', runtimeStatus, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, headerButtons, messageCount, onNewChat, onClear, chatViewMode, onChatViewModeChange, disabledViewModes = [], showEphemeralSurfaceControl = false, enableEphemeralNotebookOption = false, enableEphemeralDocumentOption = false, ephemeralSurfaceMode = 'none', onEphemeralSurfaceModeChange, }) {
@@ -90,47 +80,5 @@ export function ChatBaseHeader({ title, subtitle, disableReason, brandIcon, head
                                         color: 'fg.muted',
                                         minWidth: 0,
                                         maxWidth: '100%',
-                                    }, children: _jsx(Truncate, { title: subtitle, maxWidth: "40ch", children: subtitle }) }))] })), disableReason && (_jsx(Label, { variant: "attention", sx: { flexShrink: 0 }, children: disableReason })), headerContent, showInformation && (_jsx(IconButton, { icon: InfoIcon, "aria-label": "Information", variant: "invisible", size: "small", onClick: onInformationClick })), kernelIndicatorPlacement === 'center' && kernelIndicatorElement] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, flexShrink: 0 }, children: [kernelIndicatorPlacement === 'right' && kernelIndicatorElement, headerButtons?.showNewChat && (_jsx(IconButton, { icon: PlusIcon, "aria-label": "New chat", variant: "invisible", size: "small", onClick: onNewChat })), headerButtons?.showClear && messageCount > 0 && (_jsx(IconButton, { icon: TrashIcon, "aria-label": "Clear messages", variant: "invisible", size: "small", onClick: onClear })), headerButtons?.showSettings && (_jsx(IconButton, { icon: GearIcon, "aria-label": "Settings", variant: "invisible", size: "small", onClick: headerButtons.onSettings })), showEphemeralSurfaceControl && (_jsx(EphemeralSurfaceControl, { mode: ephemeralSurfaceMode, onChange: onEphemeralSurfaceModeChange, enableNotebook: enableEphemeralNotebookOption, enableDocument: enableEphemeralDocumentOption })), chatViewMode && onChatViewModeChange && (_jsx(Box, { sx: {
-                                display: 'inline-flex',
-                                alignItems: 'center',
-                                bg: 'neutral.muted',
-                                borderRadius: '6px',
-                                p: '2px',
-                                gap: '1px',
-                            }, children: CHAT_VIEW_MODES.map(({ mode, label }) => {
-                                const ModeIcon = VIEW_MODE_ICONS[mode];
-                                const selected = chatViewMode === mode;
-                                /* Greyed rather than left out: the person sees the mode
-                                   exists, and that this page has no place for it. */
-                                const disabled = disabledViewModes.includes(mode);
-                                return (_jsx(Tooltip, { text: disabled && mode === 'sidebar'
-                                        ? `${label} — ${SIDEBAR_NEEDS_MOUNT_POINT}`
-                                        : label, direction: "n", children: _jsx(Box, { as: "button", "aria-label": label, "aria-disabled": disabled || undefined, onClick: () => {
-                                            if (!disabled) {
-                                                onChatViewModeChange(mode);
-                                            }
-                                        }, sx: {
-                                            display: 'inline-flex',
-                                            alignItems: 'center',
-                                            justifyContent: 'center',
-                                            width: 26,
-                                            height: 24,
-                                            borderRadius: '4px',
-                                            border: 'none',
-                                            cursor: disabled ? 'not-allowed' : 'pointer',
-                                            opacity: disabled ? 0.45 : 1,
-                                            bg: selected ? 'canvas.default' : 'transparent',
-                                            boxShadow: selected ? 'shadow.small' : 'none',
-                                            color: selected ? 'fg.default' : 'fg.muted',
-                                            transition: 'all 0.15s ease',
-                                            '&:hover': disabled
-                                                ? {}
-                                                : {
-                                                    color: 'fg.default',
-                                                    bg: selected
-                                                        ? 'canvas.default'
-                                                        : 'neutral.subtle',
-                                                },
-                                        }, children: _jsx(ModeIcon, { size: 14 }) }) }, mode));
-                            }) })), headerActions] })] }) }));
+                                    }, children: _jsx(Truncate, { title: subtitle, maxWidth: "40ch", children: subtitle }) }))] })), disableReason && (_jsx(Label, { variant: "attention", sx: { flexShrink: 0 }, children: disableReason })), headerContent, showInformation && (_jsx(IconButton, { icon: InfoIcon, "aria-label": "Information", variant: "invisible", size: "small", onClick: onInformationClick })), kernelIndicatorPlacement === 'center' && kernelIndicatorElement] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, flexShrink: 0 }, children: [kernelIndicatorPlacement === 'right' && kernelIndicatorElement, headerButtons?.showNewChat && (_jsx(IconButton, { icon: PlusIcon, "aria-label": "New chat", variant: "invisible", size: "small", onClick: onNewChat })), headerButtons?.showClear && messageCount > 0 && (_jsx(IconButton, { icon: TrashIcon, "aria-label": "Clear messages", variant: "invisible", size: "small", onClick: onClear })), headerButtons?.showSettings && (_jsx(IconButton, { icon: GearIcon, "aria-label": "Settings", variant: "invisible", size: "small", onClick: headerButtons.onSettings })), showEphemeralSurfaceControl && (_jsx(EphemeralSurfaceControl, { mode: ephemeralSurfaceMode, onChange: onEphemeralSurfaceModeChange, enableNotebook: enableEphemeralNotebookOption, enableDocument: enableEphemeralDocumentOption })), chatViewMode && onChatViewModeChange && (_jsx(ChatViewModeToggle, { value: chatViewMode, onChange: onChatViewModeChange, disabledModes: disabledViewModes })), headerActions] })] }) }));
 }

package/lib/chat/header/ChatViewModeToggle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The segmented toggle for how a chat is shown — the four modes of
+ * `CHAT_VIEW_MODES`, drawn as icons in a pill, the current one raised.
+ *
+ * It grew up in the chat header, and lives apart from it so the same
+ * control can stand elsewhere: a composer floating over a page as a
+ * draggable card carries it in its own footer, where the person deciding
+ * how the chat should sit has the chat under their hands. The rules — the
+ * order, the words, which modes are greyed out — stay in `viewModes.ts`;
+ * this is only their drawing.
+ *
+ * @module chat/header/ChatViewModeToggle
+ */
+import type { JSX } from 'react';
+import { type Icon } from '@primer/octicons-react';
+import type { ChatViewMode } from '../../types/chat';
+/** The drawing of each mode. */
+export declare const VIEW_MODE_ICONS: Record<ChatViewMode, Icon>;
+export type ChatViewModeToggleProps = {
+    /** The mode the chat is in now. */
+    value?: ChatViewMode;
+    /** The mode the person picked. */
+    onChange: (mode: ChatViewMode) => void;
+    /** Modes shown greyed out: the sidebar, when the host has no mount point. */
+    disabledModes?: readonly ChatViewMode[];
+    /** Where the tooltips open. Above by default; below for a control at the top of its window. */
+    tooltipDirection?: 'n' | 's';
+};
+export declare function ChatViewModeToggle({ value, onChange, disabledModes, tooltipDirection, }: ChatViewModeToggleProps): JSX.Element;