@datalayer/agent-runtimes 1.0.10 → 1.0.17

package/lib/runtimes/actions.js

@@ -0,0 +1,249 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Runtimes APIs.
+ */
+import { URLExt } from '@jupyterlab/coreutils';
+import { PromiseDelegate } from '@lumino/coreutils';
+import { Upload } from 'tus-js-client';
+import { requestDatalayerAPI } from '@datalayer/core/lib/api';
+import { asCodeSandboxSnapshot } from '../models';
+import { iamStore, runtimesStore } from '../state/substates';
+/**
+ * Get available Environments.
+ */
+export async function getEnvironments() {
+    const data = await requestDatalayerAPI({
+        url: URLExt.join(runtimesStore.getState().runtimesUrl, 'api/runtimes/v1/environments'),
+        token: iamStore.getState().token,
+    });
+    if (!data.success) {
+        console.error('Failed to fetch available environments.', data);
+        return [];
+    }
+    return data.environments ?? [];
+}
+/**
+ * Create a Runtime.
+ */
+export async function createRuntime(options) {
+    const { externalToken, token } = iamStore.getState();
+    if (typeof options.creditsLimit !== 'number' ||
+        !Number.isFinite(options.creditsLimit) ||
+        options.creditsLimit <= 0) {
+        throw new Error(`Invalid runtime creditsLimit for environment ${options.environmentName}. ` +
+            'A positive number is required.');
+    }
+    const body = {
+        environment_name: options.environmentName,
+        type: options.type ?? 'notebook',
+        given_name: options.givenName,
+        credits_limit: options.creditsLimit,
+    };
+    if (options.capabilities) {
+        body['capabilities'] = options.capabilities;
+    }
+    if (options.snapshot) {
+        body['from'] = options.snapshot;
+    }
+    const data = await requestDatalayerAPI({
+        url: URLExt.join(runtimesStore.getState().runtimesUrl, `api/runtimes/v1/runtimes`),
+        method: 'POST',
+        body,
+        token: token,
+        // externalToken may be needed for addons (like credits...).
+        headers: externalToken
+            ? {
+                'X-External-Token': externalToken,
+            }
+            : undefined,
+    });
+    if (!data.success || !data.runtime) {
+        const msg = `Failed to create a kernel for the environment ${options.environmentName}.`;
+        console.error(msg, data);
+        throw new Error(msg);
+    }
+    return data.runtime;
+}
+/**
+ * Get the Runtimes.
+ */
+export async function getRuntimes() {
+    const data = await requestDatalayerAPI({
+        url: URLExt.join(runtimesStore.getState().runtimesUrl, 'api/runtimes/v1/runtimes'),
+        token: iamStore.getState().token,
+    });
+    if (!data.success) {
+        const msg = 'Failed to list the running kernels.';
+        console.error(msg, data);
+        throw new Error(msg);
+    }
+    return data.runtimes ?? [];
+}
+/**
+ * Delete a Runtime
+ */
+export async function deleteRuntime(options) {
+    const externalToken = iamStore.getState().externalToken;
+    await requestDatalayerAPI({
+        url: URLExt.join(runtimesStore.getState().runtimesUrl, `api/runtimes/v1/runtimes/${options.id}`) +
+            URLExt.objectToQueryString(options.reason ? { reason: options.reason } : {}),
+        method: 'DELETE',
+        token: iamStore.getState().token,
+        // externalToken may be needed for addons (like credits...).
+        headers: externalToken
+            ? {
+                'X-External-Token': externalToken,
+            }
+            : undefined,
+    });
+}
+/**
+ * Snapshot a Runtime.
+ */
+export async function snapshotRuntime(options) {
+    const data = await requestDatalayerAPI({
+        url: URLExt.join(runtimesStore.getState().runtimesUrl, 'api/runtimes/v1/sandbox-snapshots'),
+        method: 'POST',
+        body: {
+            pod_name: options.id,
+            name: options.name,
+            description: options.description,
+            stop: options.stop,
+        },
+        token: iamStore.getState().token,
+    });
+    if (!data.success) {
+        throw new Error(`Failed to take the code sandbox snapshot ${options.id} - ${data}`);
+    }
+    // Runtimes service can return 202 Accepted without inline snapshot payload
+    // while the snapshot lifecycle completes asynchronously via pub-sub events.
+    if (!data.snapshot) {
+        return undefined;
+    }
+    return asCodeSandboxSnapshot(data.snapshot);
+}
+/**
+ * Get Code Sandbox Snapshots.
+ */
+export async function getSandboxSnapshots() {
+    const data = await requestDatalayerAPI({
+        url: URLExt.join(runtimesStore.getState().runtimesUrl, 'api/runtimes/v1/sandbox-snapshots'),
+        token: iamStore.getState().token,
+    });
+    if (!data.success) {
+        console.error('Failed to fetch code sandbox snapshots.', data);
+        return [];
+    }
+    return (data.snapshots ?? []).map(asCodeSandboxSnapshot);
+}
+/**
+ * Load a Code Sandbox Snapshot within a Runtime.
+ */
+export async function loadSandboxSnapshot(options) {
+    const data = await requestDatalayerAPI({
+        url: URLExt.join(runtimesStore.getState().runtimesUrl, 'api/runtimes/v1/runtimes', options.id),
+        method: 'PUT',
+        body: {
+            from: options.from,
+        },
+        token: iamStore.getState().token,
+    });
+    if (!data.success) {
+        throw new Error(`Failed to load the code sandbox snapshot; ${data.message}`);
+    }
+}
+/**
+ * Returns the Code Sandbox Snapshot download URL.
+ *
+ * @param id Snapshot UID to download
+ * @returns The download URL
+ */
+export function createSandboxSnapshotDownloadURL(id) {
+    return (URLExt.join(runtimesStore.getState().runtimesUrl, `api/runtimes/v1/sandbox-snapshots/${id}`) +
+        URLExt.objectToQueryString({
+            download: '1',
+            token: iamStore.getState().token ?? '',
+        }));
+}
+/**
+ * Export a Code Sandbox Snapshot.
+ *
+ * @param id Code Sandbox snapshot UID to download
+ */
+export function exportCodeSandboxSnapshot(id) {
+    const url = createSandboxSnapshotDownloadURL(id);
+    const element = document.createElement('a');
+    element.href = url;
+    element.download = '';
+    document.body.appendChild(element);
+    element.click();
+    document.body.removeChild(element);
+}
+/**
+ * Delete a Code Sandbox Snapshot.
+ */
+export async function deleteCodeSandboxSnapshot(id) {
+    await requestDatalayerAPI({
+        url: URLExt.join(runtimesStore.getState().runtimesUrl, `api/runtimes/v1/sandbox-snapshots/${id}`),
+        method: 'DELETE',
+        token: iamStore.getState().token,
+    });
+}
+/**
+ * Update Code Sandbox Snapshot metadata.
+ */
+export async function updateCodeSandboxSnapshot(id, metadata) {
+    if (metadata.name || metadata.description) {
+        await requestDatalayerAPI({
+            url: URLExt.join(runtimesStore.getState().runtimesUrl, `api/runtimes/v1/sandbox-snapshots/${id}`),
+            method: 'PATCH',
+            body: { ...metadata },
+            token: iamStore.getState().token,
+        });
+    }
+}
+/**
+ * Upload a Code Sandbox Snapshot.
+ *
+ * Note: The promise will be rejected if the runtime state is empty.
+ */
+export async function uploadCodeSandboxSnapshot(options) {
+    if (options.file.size === 0) {
+        return Promise.reject('Empty Code Sandbox Snapshot.');
+    }
+    const tracker = new PromiseDelegate();
+    // Create a new tus upload.
+    const upload = new Upload(options.file, {
+        // Endpoint is the upload creation URL from your tus server.
+        endpoint: `${runtimesStore.getState().runtimesUrl}/api/runtimes/v1/sandbox-snapshots/upload`,
+        headers: { Authorization: `Bearer ${iamStore.getState().token}` },
+        // Retry delays will enable tus-js-client to automatically retry on errors.
+        // retryDelays: [0, 3000, 5000, 10000, 20000],
+        retryDelays: null,
+        // Attach additional meta data about the file for the server.
+        metadata: options.metadata,
+        // Callback for errors which cannot be fixed using retries.
+        onError: error => {
+            console.error(`Failed to upload ${options.metadata.filename}.`, error);
+            tracker.reject(error);
+        },
+        // Callback for reporting upload progress.
+        onProgress: options.onProgress,
+        // Callback for once the upload is completed.
+        onSuccess: () => {
+            tracker.resolve();
+        },
+    });
+    // Check if there are any previous uploads to continue then start the upload.
+    const previousUploads = await upload.findPreviousUploads();
+    // Found previous uploads so we select the first one.
+    if (previousUploads.length) {
+        upload.resumeFromPreviousUpload(previousUploads[0]);
+    }
+    // Start the upload.
+    upload.start();
+    return tracker.promise;
+}

package/lib/runtimes/apis.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Runtimes APIs.
+ */
+import { ISessionContext } from '@jupyterlab/apputils';
+import { ServiceManager, Kernel, ServerConnection } from '@jupyterlab/services';
+import { IDisposable } from '@lumino/disposable';
+import { ISignal } from '@lumino/signaling';
+import type { ICodeSandboxSnapshot, IRuntimeCapabilities, IRuntimeModel, IDatalayerEnvironment, IRuntimeType, IRuntimeLocation } from '../models';
+/**
+ * Abstract interface for the Datalayer session context.
+ * It extends the JupyterLab session context
+ * to include the runtime location.
+ */
+export interface IDatalayerSessionContext extends ISessionContext {
+    get location(): IRuntimeLocation;
+}
+/**
+ * Runtime creation options
+ */
+export interface IRuntimeOptions {
+    /**
+     * Environment name
+     */
+    environmentName: string;
+    /**
+     * Credits limit to be consumed by the kernel
+     */
+    creditsLimit: number;
+    /**
+     * Runtime type
+     */
+    type?: IRuntimeType;
+    /**
+     * Runtime given name
+     */
+    givenName?: string;
+    /**
+     * Kernel capabilities
+     */
+    capabilities?: IRuntimeCapabilities[];
+    /**
+     * Kernel snapshot to restore
+     */
+    snapshot?: string;
+}
+/**
+ * Interface for the Environments Manager
+ */
+export interface IEnvironmentsManager extends IDisposable {
+    /**
+     * Signal emitted when the environments changes.
+     */
+    readonly changed: ISignal<IEnvironmentsManager, readonly IDatalayerEnvironment[]>;
+    /**
+     * A signal emitted when there is a connection failure.
+     */
+    readonly connectionFailure: ISignal<IEnvironmentsManager, Error>;
+    /**
+     * Test whether the manager is ready.
+     */
+    readonly isReady: boolean;
+    /**
+     * A promise that fulfills when the manager is ready.
+     */
+    readonly ready: Promise<void>;
+    /**
+     * Get the list of environments.
+     */
+    get(): readonly IDatalayerEnvironment[];
+    /**
+     * Refresh the environment list.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Refresh the environments.
+     */
+    refreshEnvironments(): Promise<void>;
+}
+/**
+ * Interface for the Remote Runtimes Manager
+ */
+export interface IRemoteRuntimesManager extends IDisposable {
+    /**
+     * A signal emitted when there is a connection failure.
+     */
+    readonly connectionFailure: ISignal<IRemoteRuntimesManager, Error>;
+    /**
+     * Test whether the manager is ready.
+     */
+    readonly isReady: boolean;
+    /**
+     * A promise that fulfills when the manager is ready.
+     */
+    readonly ready: Promise<void>;
+    /**
+     * Remote kernels changed
+     */
+    readonly changed: ISignal<IRemoteRuntimesManager, readonly IRuntimeModel[]>;
+    /**
+     * The server settings.
+     */
+    readonly serverSettings: ServerConnection.ISettings;
+    /**
+     * Get the list of remote kernels.
+     */
+    get(): readonly IRuntimeModel[];
+    /**
+     * Get the service manager for a remote server
+     *
+     * @param serverName Remote kernel server name
+     * @returns Service manager for the remote server
+     */
+    getServices(serverName: string): any | undefined;
+    /**
+     * Refresh the environment list
+     */
+    refresh(): Promise<void>;
+    /**
+     * Launch a Kernel.
+     *
+     * @param createOptions - The kernel creation options
+     *
+     * @param connectOptions - The kernel connection options
+     *
+     * @returns A promise that resolves with the kernel connection.
+     */
+    startNew(createOptions: IRuntimeOptions, connectOptions?: Omit<Kernel.IKernelConnection.IOptions, 'model' | 'serverSettings'>): Promise<Kernel.IKernelConnection>;
+    /**
+     * Find a kernel by id.
+     *
+     * @param id - The id of the target kernel.
+     *
+     * @returns A promise that resolves with the kernel's model, or undefined if not found.
+     */
+    findById(id: string): Promise<IRuntimeModel | undefined>;
+    /**
+     * Connect to an existing kernel.
+     *
+     * @param options - The connection options.
+     *
+     * @returns A promise that resolves with the new kernel instance.
+     */
+    connectTo(options: Kernel.IKernelConnection.IOptions): Kernel.IKernelConnection;
+    /**
+     * Shut down a kernel by id.
+     *
+     * @param id - The id of the target kernel.
+     *
+     * @returns A promise that resolves when the operation is complete.
+     */
+    shutdown(id: string): Promise<void>;
+    /**
+     * Shut down all kernels.
+     *
+     * @returns A promise that resolves when all of the kernels are shut down.
+     */
+    shutdownAll(): Promise<void>;
+    /**
+     * @deprecated Use {@link refresh} instead.
+     */
+    refreshKernels(): Promise<void>;
+    /**
+     * Snapshot a runtime
+     *
+     * The runtime may be given by its `id` or `podName`.
+     * A custom description for the snapshot can be provided.
+     *
+     * @returns The snapshot description
+     */
+    snapshotRuntime(options: {
+        /**
+         * The runtime id to snapshot
+         */
+        id?: string;
+        /**
+         * The kernel pod name to snapshot
+         */
+        podName?: string;
+        /**
+         * The snapshot name
+         */
+        name?: string;
+        /**
+         * The snapshot description
+         */
+        description?: string;
+        /**
+         * Whether to stop the kernel after the snapshot completion or not.
+         */
+        stop?: boolean;
+    }): Promise<ICodeSandboxSnapshot | undefined>;
+    /**
+     * Load a snapshot within a runtim
+     *
+     * The runtime may be given by its `id` or `podName`.
+     */
+    loadSandboxSnapshot(options: {
+        /**
+         * The kernel id
+         */
+        id?: string;
+        /**
+         * The kernel pod name
+         */
+        podName?: string;
+        /**
+         * The snapshot UID
+         */
+        snapshot: string;
+    }): Promise<void>;
+}
+/**
+ * Interface for the Remote Services Manager
+ */
+export interface IRemoteServicesManager extends IDisposable {
+    /**
+     * The environments manager.
+     */
+    readonly environments: IEnvironmentsManager;
+    /**
+     * The remote runtimes manager.
+     */
+    readonly runtimesManager: IRemoteRuntimesManager;
+    /**
+     * The server settings.
+     */
+    readonly serverSettings: ServerConnection.ISettings;
+    /**
+     * A signal emitted when there is a connection failure with the kernel.
+     */
+    readonly connectionFailure: ISignal<IRemoteServicesManager, Error>;
+    /**
+     * Test whether the service manager is disposed.
+     */
+    readonly isDisposed: boolean;
+    /**
+     * Whether the remote manager is ready or not.
+     */
+    readonly isReady: boolean;
+    /**
+     * Wait for the remote manager to be ready.
+     */
+    readonly ready: Promise<void>;
+}
+/**
+ * Interface for the Service Manager that manages multiple Jupyter service managers.
+ */
+export interface IMultiServiceManager extends ServiceManager.IManager {
+    /**
+     * Service manager for browser kernels.
+     *
+     * The kernels managed by this service manager
+     * are fully executed in a service worker with
+     * browser.
+     */
+    browser: ServiceManager.IManager | undefined;
+    /**
+     * Signal emitted when the browser services changes.
+     */
+    readonly browserChanged: ISignal<ServiceManager.IManager, ServiceManager.IManager | undefined>;
+    /**
+     * Classical Service manager on the Local Jupyter server.
+     */
+    readonly local: ServiceManager.IManager;
+    /**
+     * Service manager on a Remote Jupyter server.
+     */
+    remote: IRemoteServicesManager | undefined;
+    /**
+     * Signal emitted when the remote services changes.
+     */
+    readonly remoteChanged: ISignal<ServiceManager.IManager, IRemoteServicesManager | undefined>;
+}

package/lib/runtimes/apis.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/runtimes/index.d.ts

@@ -0,0 +1,5 @@
+export * from './actions';
+export * from './apis';
+export * from './settings';
+export * from './snapshots';
+export * from './utils';

package/lib/runtimes/index.js

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export * from './actions';
+export * from './apis';
+export * from './settings';
+export * from './snapshots';
+export * from './utils';

package/lib/runtimes/settings.d.ts

@@ -0,0 +1,15 @@
+import { ServerConnection } from '@jupyterlab/services';
+/**
+ * Create a settings object given a subset of options.
+ *
+ * TODO This is already present somewhere else?
+ *
+ * @param options - An optional partial set of options.
+ *
+ * @returns The full settings object.
+ */
+export declare function makeDatalayerSettings(baseUrl: string, token: string, wsUrl?: string): ServerConnection.ISettings;
+declare const _default: {
+    makeDatalayerSettings: typeof makeDatalayerSettings;
+};
+export default _default;

package/lib/runtimes/settings.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { ServerConnection } from '@jupyterlab/services';
+/**
+ * Create a settings object given a subset of options.
+ *
+ * TODO This is already present somewhere else?
+ *
+ * @param options - An optional partial set of options.
+ *
+ * @returns The full settings object.
+ */
+export function makeDatalayerSettings(baseUrl, token, wsUrl) {
+    const serverSettings = ServerConnection.makeSettings({
+        baseUrl,
+        wsUrl: wsUrl || baseUrl.replace(/^http/, 'ws'),
+        token,
+        appendToken: true,
+        init: {
+            mode: 'cors',
+            credentials: 'include',
+            cache: 'no-store',
+        },
+    });
+    return serverSettings;
+}
+export default {
+    makeDatalayerSettings,
+};

package/lib/runtimes/snapshots.d.ts

@@ -0,0 +1,25 @@
+import { Kernel } from '@jupyterlab/services';
+type Props = {
+    connection: Kernel.IKernelConnection;
+    metadata: {
+        filename: string;
+        [key: string]: string;
+    };
+    onUploadProgress?: (bytesUploaded: number, bytesTotal: number) => void;
+};
+/**
+ * Snapshot a runtime through the frontend and upload it to the cloud.
+ *
+ * Note: You should use this only for browser runtimes.
+ */
+export declare function createSandboxSnapshot(props: Props): Promise<void>;
+/**
+ * Load a snapshot within a browser kernel.
+ *
+ * Note: You should use this only for browser kernels.
+ */
+export declare function loadBrowserSandboxSnapshot({ connection, id, }: {
+    connection: Kernel.IKernelConnection;
+    id: string;
+}): Promise<void>;
+export {};