@datalayer/agent-runtimes 1.0.10 → 1.0.17

package/lib/chat/notebook/EphemeralNotebook.js

@@ -0,0 +1,252 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * EphemeralNotebook — an in-memory Jupyter notebook rendered next to the chat.
+ *
+ * The notebook model lives purely in memory (the `nbformat` content below is
+ * never persisted to a file) and is backed by a sandbox kernel obtained via
+ * `useJupyter`. This mirrors the pattern used by the notebook editor and the
+ * `NotebookNbformat` example, so the agent can drive the notebook through the
+ * registered notebook frontend tools while nothing is written to disk.
+ *
+ * The container structure (relative wrapper + absolutely positioned inner box
+ * + `#dla-Jupyter-Notebook` overrides) is copied from the notebook editor
+ * (`NotebookEditorPanel`) so the cells get a resolved height and actually
+ * render — a plain `height: 100%` collapses to zero inside a flex parent.
+ *
+ * @module chat/notebook/EphemeralNotebook
+ */
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { ServerConnection, ServiceManager } from '@jupyterlab/services';
+import { Box, DatalayerThemeProvider, getThemeConfig, useSystemColorMode, useThemeStore, } from '@datalayer/primer-addons';
+import { Notebook, NotebookToolbar, CellSidebarExtension, CellSidebarButton, JupyterReactTheme, notebookStore, disposeServiceManager, } from '@datalayer/jupyter-react';
+import { useAgentsRuntimes } from '../../hooks/useAgentRuntimes';
+import { registerSandboxServiceManager } from '../../services/sandboxServiceManagers';
+import { useProgressTask } from '../../hooks/useProgressTask';
+/**
+ * Minimal in-memory notebook content. A single empty code cell is provided so
+ * the notebook renders immediately and the agent can insert/update cells.
+ */
+const EPHEMERAL_NOTEBOOK_CONTENT = {
+    cells: [
+        {
+            cell_type: 'code',
+            source: [''],
+            metadata: {},
+            outputs: [],
+            execution_count: null,
+        },
+    ],
+    metadata: {
+        kernelspec: {
+            display_name: 'Python 3',
+            language: 'python',
+            name: 'python3',
+        },
+        language_info: { name: 'python' },
+    },
+    nbformat: 4,
+    nbformat_minor: 5,
+};
+/**
+ * Renders an in-memory notebook backed by a sandbox kernel.
+ */
+export function EphemeralNotebook({ notebookId, runtimePodName, cellSidebarMargin = 120, nbformat, onNbformatChange, toolbarComponent, }) {
+    // The `nbformat` passed to the `Notebook` component MUST stay a stable
+    // reference for the lifetime of a given `notebookId`: the underlying
+    // `useNotebookModel` hook rebuilds the notebook model (and its context /
+    // adapter) every time the `nbformat` reference changes. Feeding the live
+    // model back into this prop would thrash the notebook and can persist
+    // transient/empty content. So we capture the initial/restore content ONCE
+    // per `notebookId` and never mutate it from the live model.
+    const initialNbformatRef = useRef(nbformat ?? EPHEMERAL_NOTEBOOK_CONTENT);
+    const initialNotebookIdRef = useRef(notebookId);
+    if (initialNotebookIdRef.current !== notebookId) {
+        // Notebook scope changed (e.g. switching agents) — reset the restore seed.
+        initialNotebookIdRef.current = notebookId;
+        initialNbformatRef.current = nbformat ?? EPHEMERAL_NOTEBOOK_CONTENT;
+    }
+    const initialNbformat = initialNbformatRef.current;
+    // Hash of the last content we persisted, so the poll only writes on change.
+    const lastSavedHashRef = useRef(JSON.stringify(initialNbformat));
+    // Resolve the runtime sandbox strictly by its assigned pod name. There is
+    // deliberately NO fallback to "first running" or `runtimes[0]`: the ephemeral
+    // notebook must bind to exactly the runtime assigned to this agent, or to
+    // none at all (straight path).
+    const { runtimes, refetchRuntimes } = useAgentsRuntimes();
+    const selectedRuntime = useMemo(() => {
+        const preferredPod = String(runtimePodName || '').trim();
+        if (!preferredPod) {
+            return undefined;
+        }
+        return runtimes.find(rt => String(rt?.pod_name || '') === preferredPod);
+    }, [runtimePodName, runtimes]);
+    // While the assigned pod has not yet appeared in the runtimes list, poll the
+    // list quickly instead of waiting for the default (10s) refresh interval.
+    // This is what makes the "Starting notebook…" state clear promptly once the
+    // agent runtime is ready, rather than lingering for several seconds.
+    const needsRuntimeLookup = Boolean(String(runtimePodName || '').trim() && !selectedRuntime);
+    useEffect(() => {
+        if (!needsRuntimeLookup) {
+            return;
+        }
+        void refetchRuntimes();
+        const intervalId = window.setInterval(() => {
+            void refetchRuntimes();
+        }, 1000);
+        return () => {
+            window.clearInterval(intervalId);
+        };
+    }, [needsRuntimeLookup, refetchRuntimes]);
+    const [runtimeServiceManager, setRuntimeServiceManager] = useState(null);
+    const [runtimeKernelId, setRuntimeKernelId] = useState(undefined);
+    const [runtimeStartDefaultKernel, setRuntimeStartDefaultKernel] = useState(false);
+    useEffect(() => {
+        let cancelled = false;
+        let manager = null;
+        let unregisterManager = null;
+        const connectRuntime = async () => {
+            const baseUrl = String(selectedRuntime?.url || '').trim();
+            if (!baseUrl) {
+                if (!cancelled) {
+                    setRuntimeServiceManager(null);
+                    setRuntimeKernelId(undefined);
+                    setRuntimeStartDefaultKernel(false);
+                }
+                return;
+            }
+            try {
+                const token = String(selectedRuntime?.token || '').trim();
+                const serverSettings = ServerConnection.makeSettings({
+                    baseUrl,
+                    wsUrl: baseUrl.replace(/^http/, 'ws'),
+                    token,
+                    appendToken: true,
+                });
+                manager = new ServiceManager({ serverSettings });
+                // Central sandbox registry: runtime terminate/pause disposes this
+                // manager immediately so its pollers cannot hit the dead pod ingress.
+                unregisterManager = registerSandboxServiceManager(String(selectedRuntime?.pod_name || ''), manager);
+                await manager.ready;
+                await manager.kernels.refreshRunning();
+                const runningKernel = [...manager.kernels.running()][0];
+                if (!cancelled) {
+                    setRuntimeServiceManager(manager);
+                    setRuntimeKernelId(runningKernel?.id);
+                    setRuntimeStartDefaultKernel(!runningKernel);
+                }
+            }
+            catch {
+                if (!cancelled) {
+                    setRuntimeServiceManager(null);
+                    setRuntimeKernelId(undefined);
+                    setRuntimeStartDefaultKernel(false);
+                }
+            }
+        };
+        connectRuntime();
+        return () => {
+            cancelled = true;
+            unregisterManager?.();
+            if (manager) {
+                disposeServiceManager(manager);
+            }
+        };
+    }, [selectedRuntime?.pod_name, selectedRuntime?.url, selectedRuntime?.token]);
+    // Bind strictly to the agent runtime sandbox; there is NO local fallback
+    // kernel. The notebook executes on the agent's runtime or shows a waiting
+    // state until the runtime is ready.
+    const activeServiceManager = runtimeServiceManager;
+    const activeKernelId = runtimeKernelId;
+    const activeStartDefaultKernel = runtimeStartDefaultKernel;
+    const ToolbarComponent = toolbarComponent || NotebookToolbar;
+    const isRuntimeStarting = Boolean(String(runtimePodName || '').trim() && !activeServiceManager);
+    useProgressTask(`ephemeral-notebook-start-${notebookId}`, isRuntimeStarting);
+    useEffect(() => {
+        // Read the CURRENT live notebook model straight from the notebook store.
+        // The `NotebookAdapter` exposes `notebook` (the widget, whose `.model` is
+        // the `INotebookModel`) and `panel` (`panel.content.model`). There is NO
+        // `notebookPanel` getter, so we read through those real accessors.
+        const readLiveModel = () => {
+            const notebook = notebookStore.getState().selectNotebook(notebookId);
+            const adapter = notebook?.adapter;
+            const model = adapter?.notebook?.model ?? adapter?.panel?.content?.model ?? null;
+            const modelJson = model?.toJSON?.();
+            return modelJson ?? null;
+        };
+        // Persist the current model to the store, but only when it actually
+        // changed. This never feeds back into the `nbformat` prop, so the live
+        // notebook is not rebuilt.
+        const persistLiveModel = () => {
+            const model = readLiveModel();
+            if (!model || !Array.isArray(model.cells)) {
+                return;
+            }
+            const nextHash = JSON.stringify(model);
+            if (nextHash === lastSavedHashRef.current) {
+                return;
+            }
+            lastSavedHashRef.current = nextHash;
+            onNbformatChange?.(model);
+        };
+        const intervalId = window.setInterval(persistLiveModel, 500);
+        return () => {
+            window.clearInterval(intervalId);
+            // Capture the final model on unmount (navigating away) so the very last
+            // edits are persisted before the notebook adapter is disposed.
+            persistLiveModel();
+        };
+    }, [activeServiceManager, notebookId, onNbformatChange]);
+    // Resolve the active theme/color-mode exactly like the notebook editor
+    // (NotebookEditorPanel) so the notebook honours dark / branded themes
+    // instead of always rendering light.
+    const { colorMode, theme: themeVariant } = useThemeStore();
+    const systemMode = useSystemColorMode();
+    const themeConfig = getThemeConfig(themeVariant);
+    const resolvedMode = colorMode === 'auto' ? systemMode : colorMode;
+    const modeStyles = resolvedMode === 'dark'
+        ? themeConfig.themeStyles.dark
+        : themeConfig.themeStyles.light;
+    const themeBackground = modeStyles.backgroundColor ?? '';
+    const extensions = useMemo(() => [new CellSidebarExtension({ factory: CellSidebarButton })], []);
+    return (_jsx(Box, { sx: {
+            flex: 1,
+            minHeight: 0,
+            height: '100%',
+            position: 'relative',
+            overflow: 'hidden',
+            bg: 'canvas.default',
+        }, children: activeServiceManager ? (_jsx(DatalayerThemeProvider, { colorMode: colorMode, theme: themeConfig.primerTheme, themeStyles: themeConfig.themeStyles, children: _jsx(JupyterReactTheme, { colormode: resolvedMode, backgroundColor: themeBackground, children: _jsx(Box, { sx: {
+                        position: 'absolute',
+                        inset: 0,
+                        display: 'flex',
+                        flexDirection: 'column',
+                        overflow: 'hidden',
+                        overscrollBehaviorY: 'contain',
+                        overflowAnchor: 'none',
+                        padding: 2,
+                        // Give the notebook a resolved height so cells render. The
+                        // Jupyter Notebook component renders its outer container with
+                        // id "dla-Jupyter-Notebook"; pin its toolbar and let the cell
+                        // area grow to fill the remaining space.
+                        '& #dla-Jupyter-Notebook': {
+                            display: 'flex',
+                            flexDirection: 'column',
+                        },
+                        '& #dla-Jupyter-Notebook > :first-of-type': {
+                            position: 'sticky',
+                            top: 0,
+                            zIndex: 2,
+                            flex: '0 0 auto',
+                            background: 'var(--jp-layout-color0, transparent)',
+                        },
+                        '& #dla-Jupyter-Notebook > .dla-Box-Notebook': {
+                            flex: '1 1 auto',
+                            minHeight: 0,
+                        },
+                    }, children: _jsx(Notebook, { nbformat: initialNbformat, id: notebookId, serviceManager: activeServiceManager, startDefaultKernel: activeStartDefaultKernel, kernelId: activeKernelId, height: "100%", cellSidebarMargin: cellSidebarMargin, extensions: extensions, Toolbar: ToolbarComponent }) }) }) })) : null }));
+}
+export default EphemeralNotebook;

package/lib/chat/prompt/InputFooter.js

@@ -27,7 +27,7 @@ export function InputToolbar({ input, setInput, isLoading, kernelStatus, connect
     const hasSelectorsContent = hasConfigData || hasSkillsData;
     // Show token usage when we have valid context data
     const hasContext = Boolean(agentUsage && !agentUsage.error && agentUsage.totalTokens > 0);
-    return (_jsxs(Box, { children: [_jsx(InputPrompt, { placeholder: placeholder || 'Type a message...', isLoading: isLoading, isKernelBusy: isKernelBusy, disabled: disableInputPrompt, readOnly: !connectionConfirmed, onSend: onSend, onStop: onStop, autoFocus: autoFocus, focusTrigger: focusTrigger, padding: padding, value: input, onChange: setInput, footerRightContent: _jsxs(_Fragment, { children: [_jsx(McpStatusIndicator, { apiBase: apiBase, authToken: authToken, data: mcpStatusData }), _jsx(SkillsStatusIndicator, { skillsCount: skills.length, enabledCount: enabledSkills.size, loading: skillsLoading })] }) }), showTokenUsage && (_jsx(Box, { sx: { minHeight: hasContext && agentUsage ? 28 : 8 }, children: hasContext && agentUsage ? (_jsx(TokenUsageBar, { agentUsage: agentUsage, padding: padding })) : null })), showSelectorsBar && (_jsx(Box, { sx: {
+    return (_jsxs(Box, { children: [_jsx(InputPrompt, { placeholder: placeholder || 'Type a message...', isLoading: isLoading, isKernelBusy: isKernelBusy, disabled: disableInputPrompt, readOnly: !connectionConfirmed, onSend: onSend, onStop: onStop, autoFocus: autoFocus, focusTrigger: focusTrigger, padding: padding, value: input, onChange: setInput, footerRightContent: _jsxs(_Fragment, { children: [_jsx(McpStatusIndicator, { apiBase: apiBase, authToken: authToken, data: mcpStatusData }), _jsx(SkillsStatusIndicator, { skillsCount: skills.length, enabledCount: enabledSkills.size, loading: skillsLoading })] }) }), showTokenUsage && (_jsx(Box, { sx: { minHeight: hasContext && agentUsage ? 28 : 8 }, children: hasContext && agentUsage ? (_jsx(TokenUsageBar, { agentUsage: agentUsage, padding: padding })) : null })), showSelectorsBar && (_jsx(Box, { "aria-disabled": disableInputPrompt || undefined, sx: {
                     display: 'flex',
                     gap: 2,
                     px: padding,
@@ -37,6 +37,9 @@ export function InputToolbar({ input, setInput, isLoading, kernelStatus, connect
                     borderColor: 'border.default',
                     alignItems: 'center',
                     bg: 'canvas.subtle',
+                    ...(disableInputPrompt
+                        ? { opacity: 0.5, pointerEvents: 'none', filter: 'grayscale(1)' }
+                        : null),
                 }, children: hasSelectorsContent ? (_jsxs(_Fragment, { children: [showToolsMenu && (_jsx(ToolsMenu, { codemodeEnabled: codemodeEnabled, onToggleCodemode: onToggleCodemode, mcpServers: mcpServers, enabledMcpTools: enabledMcpTools, enabledMcpToolCount: enabledMcpToolCount, onToggleMcpTool: onToggleMcpTool, onToggleAllMcpServerTools: onToggleAllMcpServerTools, approvedMcpTools: approvedMcpTools, onToggleMcpToolApproval: onToggleMcpToolApproval, availableTools: availableTools })), showSkillsMenu && (_jsx(SkillsMenu, { skills: skills, skillsLoading: skillsLoading, enabledSkills: enabledSkills, onToggleSkill: onToggleSkill, onToggleAllSkills: onToggleAllSkills, approvedSkills: approvedSkills, onToggleSkillApproval: onToggleSkillApproval })), showModelSelector && models.length > 0 && selectedModel && (_jsx(ModelSelector, { models: models, selectedModel: selectedModel, onModelSelect: onModelSelect, isA2AProtocol: isA2AProtocol }))] })) : (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Loading controls..." })) }))] }));
 }
 // ---------------------------------------------------------------------------

package/lib/client/AgentRuntimesClient.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Agent Runtimes client: extends the core Datalayer client (IAM / plans) with
+ * runtime and workspace/content (Spacer) capabilities.
+ *
+ * @module client/AgentRuntimesClient
+ */
+import { DatalayerCoreClient, type DatalayerClientConfig } from '@datalayer/core/lib/client';
+import type { HealthCheck } from '@datalayer/core/lib/models/HealthCheck';
+import type { RuntimeDTO } from '../models/RuntimeDTO';
+import type { EnvironmentDTO } from '../models/EnvironmentDTO';
+import type { CodeSandboxSnapshotDTO } from '../models/CodeSandboxSnapshotDTO';
+import type { SpaceDTO, UpdateSpaceRequest } from '../models/SpaceDTO';
+import type { NotebookDTO } from '../models/NotebookDTO';
+import type { LexicalDTO } from '../models/LexicalDTO';
+import type { ProjectDTO, ProjectDefaultItems } from '../models/ProjectDTO';
+declare const AgentRuntimesClientWithMixins: {
+    new (...args: any[]): {
+        getMySpaces(): Promise<SpaceDTO[]>;
+        createSpace(name: string, description: string, variant: string, spaceHandle: string, organizationId: string, seedSpaceId: string, isPublic: boolean): Promise<SpaceDTO>;
+        createNotebook(spaceId: string, name: string, description: string, file?: File | Blob): Promise<NotebookDTO>;
+        getNotebook(id: string): Promise<NotebookDTO>;
+        updateNotebook(id: string, name?: string, description?: string): Promise<NotebookDTO>;
+        createLexical(spaceId: string, name: string, description: string, file?: File | Blob): Promise<LexicalDTO>;
+        getLexical(id: string): Promise<LexicalDTO>;
+        updateLexical(id: string, name?: string, description?: string): Promise<LexicalDTO>;
+        getSpaceItems(spaceId: string): Promise<(NotebookDTO | LexicalDTO)[]>;
+        getSpaceItem(itemId: string): Promise<NotebookDTO | LexicalDTO>;
+        deleteSpaceItem(itemId: string): Promise<void>;
+        getContent(itemId: string): Promise<any>;
+        checkSpacerHealth(): Promise<HealthCheck>;
+        getCollaborationSessionId(documentId: string): Promise<string>;
+        getSpace(uid: string): Promise<SpaceDTO>;
+        updateSpace(uid: string, data: UpdateSpaceRequest): Promise<SpaceDTO>;
+        updateUserSpace(uid: string, userId: string, data: UpdateSpaceRequest): Promise<SpaceDTO>;
+        deleteSpace(uid: string): Promise<void>;
+        makeSpacePublic(uid: string): Promise<SpaceDTO>;
+        makeSpacePrivate(uid: string): Promise<SpaceDTO>;
+        exportSpace(uid: string): Promise<any>;
+        cloneNotebook(id: string): Promise<NotebookDTO>;
+        cloneLexical(id: string): Promise<LexicalDTO>;
+        getProjects(): Promise<ProjectDTO[]>;
+        getProject(uid: string): Promise<ProjectDTO>;
+        createProject(name: string, description?: string): Promise<ProjectDTO>;
+        updateProject(uid: string, data: UpdateSpaceRequest): Promise<ProjectDTO>;
+        renameProject(uid: string, newName: string, description?: string): Promise<ProjectDTO>;
+        getProjectDefaultItems(uid: string): Promise<ProjectDefaultItems>;
+    };
+} & {
+    new (...args: any[]): {
+        _extractRuntimePodName(runtimePodNameOrInstance: string | RuntimeDTO): string;
+        _extractSnapshotId(snapshotIdOrInstance: string | CodeSandboxSnapshotDTO): string;
+        listEnvironments(): Promise<EnvironmentDTO[]>;
+        createRuntime(environmentName: string, type: "notebook" | "terminal" | "job", givenName: string, minutesLimit: number, fromSnapshotId?: string): Promise<RuntimeDTO>;
+        listRuntimes(): Promise<RuntimeDTO[]>;
+        getRuntime(podName: string): Promise<RuntimeDTO>;
+        deleteRuntime(podName: string): Promise<void>;
+        terminateAllRuntimes(): Promise<PromiseSettledResult<void>[]>;
+        createSnapshot(podName: string, name: string, description: string, stop?: boolean): Promise<CodeSandboxSnapshotDTO>;
+        listSnapshots(): Promise<CodeSandboxSnapshotDTO[]>;
+        getSnapshot(id: string): Promise<CodeSandboxSnapshotDTO>;
+        deleteSnapshot(id: string): Promise<void>;
+        checkRuntimesHealth(): Promise<HealthCheck>;
+    };
+} & typeof DatalayerCoreClient;
+/**
+ * Full Datalayer client for agent runtimes: identity/plans (from core) plus
+ * runtime and workspace/content operations.
+ *
+ * @example
+ * ```typescript
+ * const client = new AgentRuntimesClient({ token: 'your-token' });
+ * const user = await client.whoami();
+ * const runtime = await client.createRuntime('env', 'notebook', 'name', 10);
+ * ```
+ */
+export declare class AgentRuntimesClient extends AgentRuntimesClientWithMixins {
+    /**
+     * Create an AgentRuntimesClient instance.
+     *
+     * @param config - Client configuration options.
+     */
+    constructor(config: DatalayerClientConfig);
+}
+export interface AgentRuntimesClient extends DatalayerCoreClient {
+    listEnvironments(): Promise<EnvironmentDTO[]>;
+    ensureRuntime(environmentName?: string, creditsLimit?: number, waitForReady?: boolean, maxWaitTime?: number, reuseExisting?: boolean, snapshotId?: string): Promise<RuntimeDTO>;
+    createRuntime(environmentName: string, type: 'notebook' | 'terminal' | 'job', givenName: string, minutesLimit: number, fromSnapshotId?: string): Promise<RuntimeDTO>;
+    listRuntimes(): Promise<RuntimeDTO[]>;
+    getRuntime(podName: string): Promise<RuntimeDTO>;
+    deleteRuntime(podName: string): Promise<void>;
+    terminateAllRuntimes(): Promise<PromiseSettledResult<void>[]>;
+    createSnapshot(podName: string, name: string, description: string, stop?: boolean): Promise<CodeSandboxSnapshotDTO>;
+    listSnapshots(): Promise<CodeSandboxSnapshotDTO[]>;
+    getSnapshot(id: string): Promise<CodeSandboxSnapshotDTO>;
+    deleteSnapshot(id: string): Promise<void>;
+    checkRuntimesHealth(): Promise<HealthCheck>;
+    getMySpaces(): Promise<SpaceDTO[]>;
+    createSpace(name: string, description: string, variant: string, spaceHandle: string, organizationId: string, seedSpaceId: string, isPublic: boolean): Promise<SpaceDTO>;
+    createNotebook(spaceId: string, name: string, description: string, file?: File | Blob): Promise<NotebookDTO>;
+    getNotebook(id: string): Promise<NotebookDTO>;
+    updateNotebook(id: string, name?: string, description?: string): Promise<NotebookDTO>;
+    createLexical(spaceId: string, name: string, description: string, file?: File | Blob): Promise<LexicalDTO>;
+    getLexical(id: string): Promise<LexicalDTO>;
+    updateLexical(id: string, name?: string, description?: string): Promise<LexicalDTO>;
+    getSpaceItems(spaceId: string): Promise<(NotebookDTO | LexicalDTO)[]>;
+    getSpaceItem(itemId: string): Promise<NotebookDTO | LexicalDTO>;
+    deleteSpaceItem(itemId: string): Promise<void>;
+    getCollaborationSessionId(documentId: string): Promise<string>;
+    getContent(itemId: string): Promise<any>;
+    checkSpacerHealth(): Promise<HealthCheck>;
+    getSpace(uid: string): Promise<SpaceDTO>;
+    updateSpace(uid: string, data: UpdateSpaceRequest): Promise<SpaceDTO>;
+    updateUserSpace(uid: string, userId: string, data: UpdateSpaceRequest): Promise<SpaceDTO>;
+    deleteSpace(uid: string): Promise<void>;
+    makeSpacePublic(uid: string): Promise<SpaceDTO>;
+    makeSpacePrivate(uid: string): Promise<SpaceDTO>;
+    exportSpace(uid: string): Promise<any>;
+    cloneNotebook(id: string): Promise<NotebookDTO>;
+    cloneLexical(id: string): Promise<LexicalDTO>;
+    getProjects(): Promise<ProjectDTO[]>;
+    getProject(uid: string): Promise<ProjectDTO>;
+    createProject(name: string, description?: string): Promise<ProjectDTO>;
+    updateProject(uid: string, data: UpdateSpaceRequest): Promise<ProjectDTO>;
+    renameProject(uid: string, newName: string, description?: string): Promise<ProjectDTO>;
+    getProjectDefaultItems(uid: string): Promise<ProjectDefaultItems>;
+}
+export {};

package/lib/client/AgentRuntimesClient.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Agent Runtimes client: extends the core Datalayer client (IAM / plans) with
+ * runtime and workspace/content (Spacer) capabilities.
+ *
+ * @module client/AgentRuntimesClient
+ */
+import { DatalayerCoreClient, } from '@datalayer/core/lib/client';
+import { RuntimesMixin } from './mixins/RuntimesMixin';
+import { SpacerMixin } from './mixins/SpacerMixin';
+// Apply the runtime + content mixins on top of the core client.
+const AgentRuntimesClientWithMixins = SpacerMixin(RuntimesMixin(DatalayerCoreClient));
+/**
+ * Full Datalayer client for agent runtimes: identity/plans (from core) plus
+ * runtime and workspace/content operations.
+ *
+ * @example
+ * ```typescript
+ * const client = new AgentRuntimesClient({ token: 'your-token' });
+ * const user = await client.whoami();
+ * const runtime = await client.createRuntime('env', 'notebook', 'name', 10);
+ * ```
+ */
+export class AgentRuntimesClient extends AgentRuntimesClientWithMixins {
+    /**
+     * Create an AgentRuntimesClient instance.
+     *
+     * @param config - Client configuration options.
+     */
+    constructor(config) {
+        super(config);
+    }
+}

package/lib/client/AgentsMixin.js

@@ -22,7 +22,7 @@ export function AgentsMixin(Base) {
          */
         async getRunningAgents() {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return agents.getRunningAgents(token, baseUrl);
         }
         /**
@@ -33,7 +33,7 @@ export function AgentsMixin(Base) {
          */
         async getAgentStatus(podName, agentId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return agents.getAgentStatus(token, podName, agentId, baseUrl);
         }
         /**
@@ -42,7 +42,7 @@ export function AgentsMixin(Base) {
          */
         async pauseAgent(podName) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return agents.pauseAgent(token, podName, baseUrl);
         }
         /**
@@ -51,7 +51,7 @@ export function AgentsMixin(Base) {
          */
         async resumeAgent(podName) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return agents.resumeAgent(token, podName, baseUrl);
         }
         /**
@@ -62,7 +62,7 @@ export function AgentsMixin(Base) {
          */
         async getAgentCheckpoints(podName, agentId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return agents.getAgentCheckpoints(token, podName, agentId, baseUrl);
         }
         /**
@@ -73,7 +73,7 @@ export function AgentsMixin(Base) {
          */
         async getAgentUsage(podName, agentId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return agents.getAgentUsage(token, podName, agentId, baseUrl);
         }
         // ========================================================================
@@ -95,7 +95,7 @@ export function AgentsMixin(Base) {
          */
         async getNotifications(filters) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return notifications.getNotifications(token, filters, baseUrl);
         }
         /**
@@ -104,7 +104,7 @@ export function AgentsMixin(Base) {
          */
         async markNotificationRead(notificationId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return notifications.markNotificationRead(token, notificationId, baseUrl);
         }
         /**
@@ -112,7 +112,7 @@ export function AgentsMixin(Base) {
          */
         async markAllNotificationsRead() {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return notifications.markAllRead(token, undefined, baseUrl);
         }
         // ========================================================================
@@ -125,7 +125,7 @@ export function AgentsMixin(Base) {
          */
         async createEvent(data) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return events.createEvent(token, data, baseUrl);
         }
         /**
@@ -135,7 +135,7 @@ export function AgentsMixin(Base) {
          */
         async listEvents(agentId, params = {}) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return events.listEvents(token, agentId, params, baseUrl);
         }
         /**
@@ -145,7 +145,7 @@ export function AgentsMixin(Base) {
          */
         async getEvent(agentId, eventId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return events.getEvent(token, agentId, eventId, baseUrl);
         }
         /**
@@ -156,7 +156,7 @@ export function AgentsMixin(Base) {
          */
         async updateEvent(agentId, eventId, data) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return events.updateEvent(token, agentId, eventId, data, baseUrl);
         }
         // ========================================================================
@@ -169,7 +169,7 @@ export function AgentsMixin(Base) {
          */
         async getAgentOutputs(agentId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return output.getAgentOutputs(token, agentId, baseUrl);
         }
         /**
@@ -180,7 +180,7 @@ export function AgentsMixin(Base) {
          */
         async getAgentOutput(agentId, outputId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return output.getAgentOutput(token, agentId, outputId, baseUrl);
         }
         /**
@@ -192,7 +192,7 @@ export function AgentsMixin(Base) {
          */
         async generateAgentOutput(agentId, format, options) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return output.generateAgentOutput(token, agentId, format, options, baseUrl);
         }
         // ========================================================================
@@ -206,7 +206,7 @@ export function AgentsMixin(Base) {
          */
         async runEvals(agentId, request) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return evals.runEvals(token, agentId, request, baseUrl);
         }
         /**
@@ -216,7 +216,7 @@ export function AgentsMixin(Base) {
          */
         async listEvals(agentId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return evals.listEvals(token, agentId, baseUrl);
         }
         /**
@@ -227,7 +227,7 @@ export function AgentsMixin(Base) {
          */
         async getEval(agentId, evalId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return evals.getEval(token, agentId, evalId, baseUrl);
         }
         // ========================================================================
@@ -240,7 +240,7 @@ export function AgentsMixin(Base) {
          */
         async getContextUsage(agentId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return context.getContextUsage(token, agentId, baseUrl);
         }
         /**
@@ -250,7 +250,7 @@ export function AgentsMixin(Base) {
          */
         async getCostUsage(agentId) {
             const token = this.getToken();
-            const baseUrl = this.getIamRunUrl();
+            const baseUrl = this.getIamUrl();
             return context.getCostUsage(token, agentId, baseUrl);
         }
         // ========================================================================
@@ -328,14 +328,14 @@ export function AgentsMixin(Base) {
          */
         async createAgentRuntime(data) {
             const token = this.getToken();
-            const runtimesRunUrl = this.getRuntimesRunUrl();
+            const runtimesUrl = this.getRuntimesUrl();
             const normalizedVolumeUids = Array.isArray(data.volumeUids)
                 ? data.volumeUids.map(uid => String(uid || '').trim()).filter(Boolean)
                 : data.volumeUid
                     ? [String(data.volumeUid).trim()]
                     : [];
             return requestDatalayerAPI({
-                url: `${runtimesRunUrl}/api/runtimes/v1/runtimes`,
+                url: `${runtimesUrl}/api/runtimes/v1/runtimes`,
                 method: 'POST',
                 token,
                 body: {
@@ -348,11 +348,11 @@ export function AgentsMixin(Base) {
                     agent_spec_id: data.agentSpecId || undefined,
                     agent_spec: data.agentSpec || undefined,
                     user_account_handle: data.userAccountHandle || undefined,
-                    billable_account_uid: data.billableAccountUid || undefined,
-                    billable_account_type: data.billableAccountType || undefined,
-                    billable_account_handle: data.billableAccountHandle || undefined,
-                    billable_source_organization_uid: data.billableSourceOrganizationUid || undefined,
-                    billable_source_organization_handle: data.billableSourceOrganizationHandle || undefined,
+                    billing_entity_uid: data.billingEntityUid || undefined,
+                    billing_entity_type: data.billingEntityType || undefined,
+                    billing_entity_handle: data.billingEntityHandle || undefined,
+                    billing_source_organization_uid: data.billingSourceOrganizationUid || undefined,
+                    billing_source_organization_handle: data.billingSourceOrganizationHandle || undefined,
                     mount_home_folder: data.mountHomeFolder ?? false,
                     volume_uids: normalizedVolumeUids.length > 0 ? normalizedVolumeUids : undefined,
                     volume_uid: normalizedVolumeUids[0] || data.volumeUid || undefined,

package/lib/client/SdkAgentRuntimesClient.d.ts

@@ -79,7 +79,7 @@ export interface AgentsSdkLike {
  * import { AgentsMixin, SdkAgentRuntimesClient } from '@datalayer/agent-runtimes';
  *
  * const ClientWithAgents = AgentsMixin(DatalayerClient);
- * const sdk = new ClientWithAgents({ iamRunUrl, runtimesRunUrl, spacerRunUrl });
+ * const sdk = new ClientWithAgents({ iamUrl, runtimesUrl, spacerUrl });
  * const client = new SdkAgentRuntimesClient(sdk);
  * ```
  */