@datalayer/agent-runtimes 1.0.29 → 1.3.10

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

@@ -21,37 +21,37 @@ export declare const listRuntimes: (token: string, baseUrl?: string) => Promise<
 /**
  * Get details for a specific runtime instance.
  * @param token - Authentication token
- * @param podName - The unique pod name of the runtime
+ * @param runtimeName - The uid of the runtime
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @returns Promise resolving to runtime details
  * @throws {Error} If authentication token is missing or invalid
- * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} If the uid is missing or invalid
  * @throws {Error} With status 404 if the runtime is not found
  */
-export declare const getRuntime: (token: string, podName: string, baseUrl?: string) => Promise<RuntimeData>;
+export declare const getRuntime: (token: string, runtimeName: string, baseUrl?: string) => Promise<RuntimeData>;
 /**
  * Delete a runtime instance.
  * @param token - Authentication token
- * @param podName - The unique pod name of the runtime to delete
+ * @param runtimeName - The uid of the runtime to delete
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @returns Promise resolving when deletion is complete
  * @throws {Error} If authentication token is missing or invalid
- * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} If the uid is missing or invalid
  * @throws {Error} With status 404 if the runtime is not found
  */
-export declare const deleteRuntime: (token: string, podName: string, baseUrl?: string) => Promise<void>;
+export declare const deleteRuntime: (token: string, runtimeName: string, baseUrl?: string) => Promise<void>;
 /**
  * Update a runtime instance.
  * @param token - Authentication token
- * @param podName - The unique pod name of the runtime
+ * @param runtimeName - The uid of the runtime
  * @param from - The source to update from
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @returns Promise resolving to updated runtime details
  * @throws {Error} If authentication token is missing or invalid
- * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} If the uid is missing or invalid
  * @throws {Error} With status 404 if the runtime is not found
  */
-export declare const updateRuntime: (token: string, podName: string, from: string, baseUrl?: string) => Promise<RuntimeData>;
+export declare const updateRuntime: (token: string, runtimeName: string, from: string, baseUrl?: string) => Promise<RuntimeData>;
 /**
  * Response from the pause/resume runtime endpoints.
  * The server returns 202 Accepted and provides a checkpoint UID
@@ -76,9 +76,9 @@ export interface PauseRuntimeBody {
     /** Agentspec identifier */
     agent_spec_id?: string;
     /** Full agentspec payload to persist with the checkpoint */
-    agentspec?: Record<string, any>;
+    agentspec?: Record<string, unknown>;
     /** Additional metadata */
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
     /** Lightweight checkpoint message history */
     messages?: string[];
 }
@@ -90,14 +90,14 @@ export interface PauseRuntimeBody {
  * poll for status via the runtime-checkpoints API.
  *
  * @param token - Authentication token
- * @param podName - The unique pod name of the runtime to pause
+ * @param runtimeName - The uid of the runtime to pause
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @param body - Optional metadata to store in the checkpoint record
  * @returns Promise resolving with the checkpoint ID for status tracking
  * @throws {Error} If authentication token is missing or invalid
- * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} If the uid is missing or invalid
  */
-export declare const pauseRuntime: (token: string, podName: string, baseUrl?: string, body?: PauseRuntimeBody) => Promise<PauseResumeResponse>;
+export declare const pauseRuntime: (token: string, runtimeName: string, baseUrl?: string, body?: PauseRuntimeBody) => Promise<PauseResumeResponse>;
 /**
  * Optional body for the resume endpoint.
  * Contains information needed by the operator to restore from a checkpoint.
@@ -118,7 +118,7 @@ export interface ResumeRuntimeBody {
     /** Target node name */
     node_name?: string;
     /** Additional metadata */
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
 }
 /**
  * Persisted memory record returned by ``/api/runtimes/v1/memories``.
@@ -135,7 +135,7 @@ export interface RuntimeMemory {
     scope?: string | null;
     created_at?: string | null;
     updated_at?: string | null;
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
 }
 /**
  * Response payload for listing persisted runtime memories.
@@ -185,11 +185,11 @@ export declare const getRuntimeMemory: (token: string, memoryId: string, baseUrl
  * poll for status.
  *
  * @param token - Authentication token
- * @param podName - The unique pod name of the runtime to resume
+ * @param runtimeName - The uid of the runtime to resume
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @param body - Optional body with agent_spec_id and restore options
  * @returns Promise resolving with the checkpoint ID for status tracking
  * @throws {Error} If authentication token is missing or invalid
- * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} If the uid is missing or invalid
  */
-export declare const resumeRuntime: (token: string, podName: string, baseUrl?: string, body?: ResumeRuntimeBody) => Promise<PauseResumeResponse>;
+export declare const resumeRuntime: (token: string, runtimeName: string, baseUrl?: string, body?: ResumeRuntimeBody) => Promise<PauseResumeResponse>;

package/lib/api/runtimes/runtimes.js

@@ -12,6 +12,12 @@
 import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
 import { validateToken, validateRequiredString, } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * The status a failed request answered with, when it answered at all.
+ */
+function statusOf(error) {
+    return error.response?.status;
+}
 /**
  * Create a new runtime instance.
  * @param token - Authentication token
@@ -33,17 +39,17 @@ export const createRuntime = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.
         });
     }
     catch (error) {
-        // Handle specific error cases
-        if (error.response) {
-            const status = error.response.status;
-            const responseData = error.response.data || {};
+        const failure = error;
+        if (failure.response) {
+            const status = failure.response.status;
+            const responseData = failure.response.data || {};
             if (status === 404) {
                 // Environment not found
-                throw new Error(`Environment '${data.environment?.name || ''}' not found. ${responseData.message || 'Please check the environment name and try again.'}`);
+                throw new Error(`Environment '${data.environment?.name || ''}' not found. ${responseData.message || 'Please check the environment name and try again.'}`, { cause: error });
             }
             else if (status === 503) {
                 // No runtime available
-                throw new Error(`No runtime available. ${responseData.message || 'The service is temporarily unavailable or at capacity. Please try again later.'}`);
+                throw new Error(`No runtime available. ${responseData.message || 'The service is temporarily unavailable or at capacity. Please try again later.'}`, { cause: error });
             }
         }
         // Re-throw the original error for other cases
@@ -59,31 +65,29 @@ export const createRuntime = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.
  */
 export const listRuntimes = async (token, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
     validateToken(token);
-    const response = await requestDatalayerAPI({
+    // The API returns { success: true, message: string, runtimes: Runtime[] }
+    return await requestDatalayerAPI({
         url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes`,
         method: 'GET',
         token,
     });
-    // The API returns { success: true, message: string, runtimes: Runtime[] }
-    // The response already has the correct structure, just return it
-    return response;
 };
 /**
  * Get details for a specific runtime instance.
  * @param token - Authentication token
- * @param podName - The unique pod name of the runtime
+ * @param runtimeName - The uid of the runtime
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @returns Promise resolving to runtime details
  * @throws {Error} If authentication token is missing or invalid
- * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} If the uid is missing or invalid
  * @throws {Error} With status 404 if the runtime is not found
  */
-export const getRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+export const getRuntime = async (token, runtimeName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
     validateToken(token);
-    validateRequiredString(podName, 'Pod name');
+    validateRequiredString(runtimeName, 'Runtime uid');
     try {
         const response = await requestDatalayerAPI({
-            url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${podName}`,
+            url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${runtimeName}`,
             method: 'GET',
             token,
         });
@@ -93,24 +97,23 @@ export const getRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.
         if (response.runtime) {
             return {
                 ...response.runtime,
-                pod_name: response.runtime.pod_name || podName,
+                runtime_name: response.runtime.runtime_name || runtimeName,
             };
         }
         // Fallback to 'kernel' field (old API)
         if (response.kernel) {
             return {
                 ...response.kernel,
-                pod_name: response.kernel.pod_name || podName,
+                runtime_name: response.kernel.runtime_name || runtimeName,
             };
         }
         // Fallback if response structure is different
         return response;
     }
     catch (error) {
-        // Handle specific error cases
-        if (error.response && error.response.status === 404) {
+        if (statusOf(error) === 404) {
             // Runtime not found
-            throw new Error(`Runtime with pod name '${podName}' not found. Please check the pod name and try again.`);
+            throw new Error(`Runtime '${runtimeName}' not found. Check the uid and try again.`, { cause: error });
         }
         // Re-throw the original error for other cases
         throw error;
@@ -119,28 +122,27 @@ export const getRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.
 /**
  * Delete a runtime instance.
  * @param token - Authentication token
- * @param podName - The unique pod name of the runtime to delete
+ * @param runtimeName - The uid of the runtime to delete
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @returns Promise resolving when deletion is complete
  * @throws {Error} If authentication token is missing or invalid
- * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} If the uid is missing or invalid
  * @throws {Error} With status 404 if the runtime is not found
  */
-export const deleteRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+export const deleteRuntime = async (token, runtimeName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
     validateToken(token);
-    validateRequiredString(podName, 'Pod name');
+    validateRequiredString(runtimeName, 'Runtime uid');
     try {
         return await requestDatalayerAPI({
-            url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${podName}`,
+            url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${runtimeName}`,
             method: 'DELETE',
             token,
         });
     }
     catch (error) {
-        // Handle specific error cases
-        if (error.response && error.response.status === 404) {
+        if (statusOf(error) === 404) {
             // Runtime not found
-            throw new Error(`Runtime with pod name '${podName}' not found. Cannot delete a non-existent runtime.`);
+            throw new Error(`Runtime '${runtimeName}' not found. Cannot delete a non-existent runtime.`, { cause: error });
         }
         // Re-throw the original error for other cases
         throw error;
@@ -149,30 +151,29 @@ export const deleteRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_UR
 /**
  * Update a runtime instance.
  * @param token - Authentication token
- * @param podName - The unique pod name of the runtime
+ * @param runtimeName - The uid of the runtime
  * @param from - The source to update from
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @returns Promise resolving to updated runtime details
  * @throws {Error} If authentication token is missing or invalid
- * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} If the uid is missing or invalid
  * @throws {Error} With status 404 if the runtime is not found
  */
-export const updateRuntime = async (token, podName, from, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+export const updateRuntime = async (token, runtimeName, from, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
     validateToken(token);
-    validateRequiredString(podName, 'Pod name');
+    validateRequiredString(runtimeName, 'Runtime uid');
     try {
         return await requestDatalayerAPI({
-            url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${podName}`,
+            url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${runtimeName}`,
             method: 'PUT',
             token,
             body: { from },
         });
     }
     catch (error) {
-        // Handle specific error cases
-        if (error.response && error.response.status === 404) {
+        if (statusOf(error) === 404) {
             // Runtime not found
-            throw new Error(`Runtime with pod name '${podName}' not found. Cannot update a non-existent runtime.`);
+            throw new Error(`Runtime '${runtimeName}' not found. Cannot update a non-existent runtime.`, { cause: error });
         }
         // Re-throw the original error for other cases
         throw error;
@@ -186,18 +187,18 @@ export const updateRuntime = async (token, podName, from, baseUrl = DEFAULT_SERV
  * poll for status via the runtime-checkpoints API.
  *
  * @param token - Authentication token
- * @param podName - The unique pod name of the runtime to pause
+ * @param runtimeName - The uid of the runtime to pause
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @param body - Optional metadata to store in the checkpoint record
  * @returns Promise resolving with the checkpoint ID for status tracking
  * @throws {Error} If authentication token is missing or invalid
- * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} If the uid is missing or invalid
  */
-export const pauseRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES, body) => {
+export const pauseRuntime = async (token, runtimeName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES, body) => {
     validateToken(token);
-    validateRequiredString(podName, 'Pod name');
+    validateRequiredString(runtimeName, 'Runtime uid');
     return await requestDatalayerAPI({
-        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${encodeURIComponent(podName)}/pause`,
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${encodeURIComponent(runtimeName)}/pause`,
         method: 'POST',
         token,
         ...(body ? { body } : {}),
@@ -265,18 +266,18 @@ export const getRuntimeMemory = async (token, memoryId, baseUrl = DEFAULT_SERVIC
  * poll for status.
  *
  * @param token - Authentication token
- * @param podName - The unique pod name of the runtime to resume
+ * @param runtimeName - The uid of the runtime to resume
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @param body - Optional body with agent_spec_id and restore options
  * @returns Promise resolving with the checkpoint ID for status tracking
  * @throws {Error} If authentication token is missing or invalid
- * @throws {Error} If pod name is missing or invalid
+ * @throws {Error} If the uid is missing or invalid
  */
-export const resumeRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES, body) => {
+export const resumeRuntime = async (token, runtimeName, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES, body) => {
     validateToken(token);
-    validateRequiredString(podName, 'Pod name');
+    validateRequiredString(runtimeName, 'Runtime uid');
     return await requestDatalayerAPI({
-        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${encodeURIComponent(podName)}/resume`,
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes/${encodeURIComponent(runtimeName)}/resume`,
         method: 'POST',
         token,
         ...(body ? { body } : {}),

package/lib/api/spacer/notebooks.js

@@ -23,7 +23,7 @@ export const createNotebook = async (token, data, baseUrl = DEFAULT_SERVICE_URLS
     const formData = new FormData();
     formData.append('spaceId', data.spaceId);
     formData.append('name', data.name);
-    formData.append('notebookType', data.notebookType || 'jupyter'); // Required field
+    formData.append('notebookType', data.notebookType || 'jupyter-server'); // Required field
     formData.append('description', data.description || ''); // Required field - can be empty
     // Add file if provided
     if (data.file) {

package/lib/chat/Chat.d.ts

@@ -1,11 +1,23 @@
 import type { OAuthProvider, OAuthProviderConfig, Identity } from '../identity';
-import type { ChatCommonProps, Extension, Protocol } from '../types';
+import type { ChatCommonProps, Extension, Protocol, ProtocolConfig } from '../types';
 /**
  * Chat props — extends ChatCommonProps with transport-specific configuration.
  */
 export interface ChatProps extends ChatCommonProps {
-    /** Transport to use — REQUIRED (narrows protocol to string enum) */
-    protocol: Protocol;
+    /**
+     * Transport to use — REQUIRED.
+     *
+     * A `Protocol` string is the usual form: this component then builds the
+     * endpoint, the config endpoint and the auth token from `baseUrl` and
+     * `agentId`, which is what makes it convenient.
+     *
+     * A full `ProtocolConfig` is taken as given instead, for an adapter whose
+     * configuration cannot be derived from a base URL — the in-page harness
+     * carries live objects (its instructions, its tools, where to reach a model)
+     * rather than an address. `ChatFloating` has always accepted both; this is
+     * the same seam.
+     */
+    protocol: Protocol | ProtocolConfig;
     /** Extensions for chat features */
     extensions?: Extension[];
     /** Base URL of the server (for HTTP-based protocols) */
@@ -107,5 +119,5 @@ export interface ChatProps extends ChatCommonProps {
  * />
  * ```
  */
-export declare function Chat({ protocol: transport, extensions: _extensions, baseUrl, endpoint: endpointProp, configEndpoint: configEndpointProp, enableConfigQuery: enableConfigQueryProp, wsUrl, agentId, authToken: authTokenProp, placeholder, title, subtitle, brandIcon, autoConnect, streaming: _streaming, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height, showHeader, showNewChatButton, showClearButton, showModelSelector, showToolsMenu, showInput, disableInputPrompt, overlay, launching, launchingMessage, showSkillsMenu, codemodeEnabled, onToggleCodemode, showTokenUsage, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount, suggestions, submitOnSuggestionClick, description, headerContent, headerActions, autoFocus, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation, chatViewMode, onChatViewModeChange, frontendTools, enableEphemeralNotebook, initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange, enableEphemeralDocument, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, onToolCallStart, onToolCallComplete, renderToolResult, hideMessagesAfterToolUI, contextSnapshot, mcpStatusData, codemodeStatusData, sandboxStatusData, kernel, kernelIndicatorPlacement, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, themeVariant, colorMode, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, disableInternalJupyterTheme, }: ChatProps): import("react/jsx-runtime").JSX.Element;
+export declare function Chat({ protocol: transport, extensions: _extensions, baseUrl, endpoint: endpointProp, configEndpoint: configEndpointProp, enableConfigQuery: enableConfigQueryProp, wsUrl, agentId, authToken: authTokenProp, placeholder, title, subtitle, brandIcon, autoConnect, streaming: _streaming, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height, showHeader, showNewChatButton, showClearButton, showModelSelector, showToolsMenu, showInput, disableInputPrompt, disabled, disableReason, overlay, launching, launchingMessage, showSkillsMenu, codemodeEnabled, onToggleCodemode, showTokenUsage, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount, suggestions, submitOnSuggestionClick, description, headerContent, headerActions, autoFocus, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation, chatViewMode, onChatViewModeChange, frontendTools, enableEphemeralNotebook, initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange, enableEphemeralDocument, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, onToolCallStart, onToolCallComplete, renderToolResult, hideMessagesAfterToolUI, contextSnapshot, mcpStatusData, codemodeStatusData, sandboxStatusData, kernel, kernelIndicatorPlacement, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, themeVariant, colorMode, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, disableInternalJupyterTheme, }: ChatProps): import("react").JSX.Element;
 export default Chat;

package/lib/chat/Chat.js

@@ -85,7 +85,11 @@ function getEndpointPath(protocol, agentId) {
     }
 }
 /**
- * Map transport type to protocol type
+ * Map transport type to protocol type.
+ *
+ * Only `vercel-ai-jupyter` collapses: it is the same wire protocol reached
+ * through Jupyter's request machinery. Everything else, `browser-vercel-ai`
+ * included, is its own adapter and passes through.
  */
 function getProtocolType(protocol) {
     switch (protocol) {
@@ -136,7 +140,7 @@ function getProtocolType(protocol) {
  * />
  * ```
  */
-export function Chat({ protocol: transport, extensions: _extensions, baseUrl = 'http://localhost:8765', endpoint: endpointProp, configEndpoint: configEndpointProp, enableConfigQuery: enableConfigQueryProp, wsUrl, agentId, authToken: authTokenProp, placeholder = 'Type your message...', title, subtitle, brandIcon, autoConnect = true, streaming: _streaming = true, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height = '600px', showHeader = true, showNewChatButton = true, showClearButton = true, showModelSelector = true, showToolsMenu = true, showInput = true, disableInputPrompt = false, overlay, launching = false, launchingMessage, showSkillsMenu = true, codemodeEnabled = false, onToggleCodemode, showTokenUsage = true, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount = true, suggestions, submitOnSuggestionClick = true, description, headerContent, headerActions, autoFocus = false, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation = true, chatViewMode, onChatViewModeChange, frontendTools, enableEphemeralNotebook, initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange, enableEphemeralDocument, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, onToolCallStart, onToolCallComplete, renderToolResult, hideMessagesAfterToolUI = false, contextSnapshot, mcpStatusData, codemodeStatusData, sandboxStatusData, kernel, kernelIndicatorPlacement, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, themeVariant, colorMode, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, disableInternalJupyterTheme = false, }) {
+export function Chat({ protocol: transport, extensions: _extensions, baseUrl = 'http://localhost:8765', endpoint: endpointProp, configEndpoint: configEndpointProp, enableConfigQuery: enableConfigQueryProp, wsUrl, agentId, authToken: authTokenProp, placeholder = 'Type your message...', title, subtitle, brandIcon, autoConnect = true, streaming: _streaming = true, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height = '600px', showHeader = true, showNewChatButton = true, showClearButton = true, showModelSelector = true, showToolsMenu = true, showInput = true, disableInputPrompt = false, disabled, disableReason, overlay, launching = false, launchingMessage, showSkillsMenu = true, codemodeEnabled = false, onToggleCodemode, showTokenUsage = true, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount = true, suggestions, submitOnSuggestionClick = true, description, headerContent, headerActions, autoFocus = false, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation = true, chatViewMode, onChatViewModeChange, frontendTools, enableEphemeralNotebook, initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange, enableEphemeralDocument, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, onToolCallStart, onToolCallComplete, renderToolResult, hideMessagesAfterToolUI = false, contextSnapshot, mcpStatusData, codemodeStatusData, sandboxStatusData, kernel, kernelIndicatorPlacement, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, themeVariant, colorMode, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, disableInternalJupyterTheme = false, }) {
     const resolvedAgentId = typeof agentId === 'string' && agentId.trim().length > 0
         ? agentId.trim()
         : 'default';
@@ -168,10 +172,19 @@ export function Chat({ protocol: transport, extensions: _extensions, baseUrl = '
             return () => clearTimeout(timer);
         }
     }, [showDetails]);
+    /** The protocol's name, whichever form it was given in. */
+    const transportName = typeof transport === 'object' && transport !== null
+        ? transport.type
+        : transport;
     // Build protocol config based on transport.
     // Keep this pure: never call React state setters inside this memo.
     const protocolConfigResult = useMemo(() => {
         try {
+            // A config given outright is used as it stands: there is nothing here
+            // that could improve on an adapter's own description of itself.
+            if (typeof transport === 'object' && transport !== null) {
+                return { config: transport, error: null };
+            }
             let endpoint;
             let authToken = authTokenProp;
             let options;
@@ -327,7 +340,7 @@ export function Chat({ protocol: transport, extensions: _extensions, baseUrl = '
                         height,
                         p: 4,
                         bg: 'canvas.default',
-                    }, children: [_jsx(Spinner, { size: "large" }), _jsxs(Text, { sx: { mt: 3, color: 'fg.muted' }, children: ["Connecting to ", transport.toUpperCase().replace('-', ' '), " agent..."] })] }) }) }));
+                    }, children: [_jsx(Spinner, { size: "large" }), _jsxs(Text, { sx: { mt: 3, color: 'fg.muted' }, children: ["Connecting to ", transportName.toUpperCase().replace('-', ' '), ' ', "agent..."] })] }) }) }));
     }
     return (_jsx(ThemeProvider, { children: _jsx(QueryClientProvider, { client: queryClient, children: _jsxs(Box, { className: className, sx: {
                     position: 'relative',
@@ -339,7 +352,7 @@ export function Chat({ protocol: transport, extensions: _extensions, baseUrl = '
                             display: showDetails ? 'flex' : 'none',
                             flexDirection: 'column',
                             height: '100%',
-                        }, children: _jsx(AgentDetails, { name: title || 'AI Agent', icon: brandIcon, protocol: transport, url: protocolConfig?.endpoint || baseUrl, messageCount: messageCount, agentId: agentId, apiBase: baseUrl, identityProviders: identityProviders, onIdentityConnect: onIdentityConnect, onIdentityDisconnect: onIdentityDisconnect, onBack: handleBackFromDetails, mcpStatusData: mcpStatusData, codemodeStatusData: codemodeStatusData }) }), _jsxs(Box, { sx: {
+                        }, children: _jsx(AgentDetails, { name: title || 'AI Agent', icon: brandIcon, protocol: transportName, url: protocolConfig?.endpoint || baseUrl, messageCount: messageCount, agentId: agentId, apiBase: baseUrl, identityProviders: identityProviders, onIdentityConnect: onIdentityConnect, onIdentityDisconnect: onIdentityDisconnect, onBack: handleBackFromDetails, mcpStatusData: mcpStatusData, codemodeStatusData: codemodeStatusData }) }), _jsxs(Box, { sx: {
                             display: showDetails ? 'none' : 'flex',
                             flexDirection: 'column',
                             height: '100%',
@@ -364,6 +377,6 @@ export function Chat({ protocol: transport, extensions: _extensions, baseUrl = '
                                                 ? 'attention.fg'
                                                 : 'danger.fg',
                                             flex: 1,
-                                        }, children: errorBanner.message })] })), _jsx(ChatBase, { title: title, subtitle: subtitle, brandIcon: brandIcon, showHeader: showHeader, protocol: protocolConfig, placeholder: placeholder, description: description, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, autoFocus: autoFocus, runtimeId: runtimeId, historyEndpoint: historyEndpoint, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: handleInformationClick, headerContent: headerContent, headerActions: headerActions, showModelSelector: showModelSelector, showToolsMenu: showToolsMenu, showInput: showInput, disableInputPrompt: disableInputPrompt, overlay: overlay, launching: launching, launchingMessage: launchingMessage, autoConnect: autoConnect, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, codemodeEnabled: codemodeEnabled, onToggleCodemode: onToggleCodemode, initialModel: initialModel, availableModels: availableModels, mcpServers: mcpServers, initialSkills: initialSkills, connectedIdentities: identitiesForChat, onNewChat: handleNewChat, onMessagesChange: handleMessagesChange, headerButtons: headerButtons, avatarConfig: avatarConfig, backgroundColor: "canvas.default", focusTrigger: focusTrigger, chatViewMode: chatViewMode, onChatViewModeChange: onChatViewModeChange, frontendTools: frontendTools, enableEphemeralNotebook: enableEphemeralNotebook, initialEphemeralNotebookOpen: initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange: onEphemeralNotebookOpenChange, enableEphemeralDocument: enableEphemeralDocument, initialEphemeralSurfaceMode: initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange: onEphemeralSurfaceModeChange, collapsed: collapsed, onExpandFromCollapsed: onExpandFromCollapsed, ephemeralNotebookToolbar: ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems: ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems: ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider: ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId: ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration: ephemeralDocumentCollaboration, ephemeralRuntimeOverride: ephemeralRuntimeOverride, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, renderToolResult: renderToolResult, hideMessagesAfterToolUI: hideMessagesAfterToolUI, contextSnapshot: contextSnapshot, mcpStatusData: mcpStatusData, sandboxStatusData: sandboxStatusData, kernel: kernel, kernelIndicatorPlacement: kernelIndicatorPlacement, kernelEnvironmentName: kernelEnvironmentName, kernelCpu: kernelCpu, kernelMemory: kernelMemory, kernelGpu: kernelGpu, themeVariant: themeVariant, colorMode: colorMode, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, disableInternalJupyterTheme: disableInternalJupyterTheme })] })] }) }) }));
+                                        }, children: errorBanner.message })] })), _jsx(ChatBase, { title: title, subtitle: subtitle, brandIcon: brandIcon, showHeader: showHeader, protocol: protocolConfig, placeholder: placeholder, description: description, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, autoFocus: autoFocus, runtimeId: runtimeId, historyEndpoint: historyEndpoint, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: handleInformationClick, headerContent: headerContent, headerActions: headerActions, showModelSelector: showModelSelector, showToolsMenu: showToolsMenu, showInput: showInput, disableInputPrompt: disableInputPrompt, disabled: disabled, disableReason: disableReason, overlay: overlay, launching: launching, launchingMessage: launchingMessage, autoConnect: autoConnect, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, codemodeEnabled: codemodeEnabled, onToggleCodemode: onToggleCodemode, initialModel: initialModel, availableModels: availableModels, mcpServers: mcpServers, initialSkills: initialSkills, connectedIdentities: identitiesForChat, onNewChat: handleNewChat, onMessagesChange: handleMessagesChange, headerButtons: headerButtons, avatarConfig: avatarConfig, backgroundColor: "canvas.default", focusTrigger: focusTrigger, chatViewMode: chatViewMode, onChatViewModeChange: onChatViewModeChange, frontendTools: frontendTools, enableEphemeralNotebook: enableEphemeralNotebook, initialEphemeralNotebookOpen: initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange: onEphemeralNotebookOpenChange, enableEphemeralDocument: enableEphemeralDocument, initialEphemeralSurfaceMode: initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange: onEphemeralSurfaceModeChange, collapsed: collapsed, onExpandFromCollapsed: onExpandFromCollapsed, ephemeralNotebookToolbar: ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems: ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems: ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider: ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId: ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration: ephemeralDocumentCollaboration, ephemeralRuntimeOverride: ephemeralRuntimeOverride, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, renderToolResult: renderToolResult, hideMessagesAfterToolUI: hideMessagesAfterToolUI, contextSnapshot: contextSnapshot, mcpStatusData: mcpStatusData, sandboxStatusData: sandboxStatusData, kernel: kernel, kernelIndicatorPlacement: kernelIndicatorPlacement, kernelEnvironmentName: kernelEnvironmentName, kernelCpu: kernelCpu, kernelMemory: kernelMemory, kernelGpu: kernelGpu, themeVariant: themeVariant, colorMode: colorMode, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, disableInternalJupyterTheme: disableInternalJupyterTheme })] })] }) }) }));
 }
 export default Chat;

package/lib/chat/ChatFloating.d.ts

@@ -59,10 +59,11 @@ export interface ChatFloatingProps extends ChatCommonProps {
      * Default view mode.
      * - 'floating': Full-height floating panel (pinned to right edge with offset)
      * - 'floating-small': Standard floating popup
+     * - 'floating-draggable': The popup with a handle, movable about the viewport
      * - 'panel': Full-height side panel (right edge, no floating offset)
      * @default 'floating'
      */
-    defaultViewMode?: 'floating' | 'floating-small' | 'panel';
+    defaultViewMode?: 'floating' | 'floating-small' | 'floating-draggable' | 'panel';
     /**
      * Callback when the user switches view mode via the header toggle.
      * The parent component receives the new ChatViewMode value.
@@ -70,6 +71,16 @@ export interface ChatFloatingProps extends ChatCommonProps {
      * a ChatSidebar instead.
      */
     onViewModeChange?: (mode: ChatViewMode) => void;
+    /**
+     * Where "Sidebar panel" docks the chat: an element, or a selector for one.
+     *
+     * The proof there is a sidebar to dock into — without it, the option is
+     * shown greyed out in the header. A host that swaps to `<ChatSidebar>`
+     * itself on `onViewModeChange('sidebar')` passes the container it renders
+     * that sidebar in; a host with no such component passes the element, and
+     * the panel is rendered into it from here.
+     */
+    sidebarMountPoint?: HTMLElement | string | null;
     /**
      * Show backdrop overlay in panel mode.
      * When true, a semi-transparent overlay covers the page behind the panel.
@@ -81,5 +92,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, 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, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, }: ChatFloatingProps): import("react/jsx-runtime").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, 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;