@datalayer/agent-runtimes 1.0.9 → 1.0.17

package/lib/jupyter/kernelsHandler.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+/**
+ * Call the jupyter_kernels extension
+ *
+ * @param endPoint API REST end point for the extension
+ * @param init Initial values for the request
+ * @returns The response body interpreted as JSON
+ */
+export async function requestJupyterKernelsExtension(endPoint = '', init = {}) {
+    // Make request to Jupyter API
+    const settings = ServerConnection.makeSettings();
+    const requestUrl = URLExt.join(settings.baseUrl, 'jupyter_kernels', // API Namespace
+    endPoint);
+    let response;
+    try {
+        response = await ServerConnection.makeRequest(requestUrl, init, settings);
+    }
+    catch (error) {
+        throw new ServerConnection.NetworkError(error);
+    }
+    let data = await response.text();
+    if (data.length > 0) {
+        try {
+            data = JSON.parse(data);
+        }
+        catch (error) {
+            console.log('Not a JSON response body.', response);
+        }
+    }
+    if (!response.ok) {
+        throw new ServerConnection.ResponseError(response, data.message || data);
+    }
+    return data;
+}

package/lib/mocks/models/CourseMock.d.ts

@@ -0,0 +1,6 @@
+import { ICourse } from '../../models/Course';
+export declare const newCourseMock: (name: string) => ICourse;
+export declare const COURSE_1_MOCK: ICourse;
+export declare const COURSE_2_MOCK: ICourse;
+export declare const COURSE_3_MOCK: ICourse;
+export declare const COURSES_MOCK: ICourse[];

package/lib/mocks/models/CourseMock.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { uniqueNamesGenerator, names } from 'unique-names-generator';
+import { newUlid } from '@datalayer/core/lib/utils';
+import { newSpaceMock } from './SpaceMock';
+import { newUserMock } from '@datalayer/core/lib/mocks/models/UserMock';
+export const newCourseMock = (name) => {
+    const course = {
+        id: newUlid(),
+        owner: newUserMock(uniqueNamesGenerator({ dictionaries: [names] }), uniqueNamesGenerator({ dictionaries: [names] })),
+        handle: newUlid(),
+        type: 'space',
+        variant: 'course',
+        name: name,
+        description: name + ' description.',
+        public: false,
+        creationDate: new Date(),
+        items: [],
+        itemIds: [],
+        seedSpace: newSpaceMock('space content'),
+    };
+    return course;
+};
+export const COURSE_1_MOCK = newCourseMock('Course 1');
+export const COURSE_2_MOCK = newCourseMock('Course 2');
+export const COURSE_3_MOCK = newCourseMock('Course 3');
+export const COURSES_MOCK = [COURSE_1_MOCK, COURSE_2_MOCK, COURSE_3_MOCK];

package/lib/mocks/models/SpaceMock.d.ts

@@ -0,0 +1,6 @@
+import { ISpace } from '../../models/Space';
+export declare const newSpaceMock: (name: string) => ISpace;
+export declare const SPACE_1_MOCK: ISpace;
+export declare const SPACE_2_MOCK: ISpace;
+export declare const SPACE_3: ISpace;
+export declare const SPACES_MOCK: ISpace[];

package/lib/mocks/models/SpaceMock.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { uniqueNamesGenerator, names } from 'unique-names-generator';
+import { newUlid } from '@datalayer/core/lib/utils';
+import { newUserMock } from '@datalayer/core/lib/mocks/models/UserMock';
+export const newSpaceMock = (name) => {
+    const space = {
+        id: newUlid(),
+        owner: newUserMock(uniqueNamesGenerator({ dictionaries: [names] }), uniqueNamesGenerator({ dictionaries: [names] })),
+        handle: newUlid(),
+        type: 'space',
+        variant: 'default',
+        name: name,
+        description: name + ' description.',
+        public: false,
+        creationDate: new Date(),
+    };
+    return space;
+};
+export const SPACE_1_MOCK = newSpaceMock('Space 1');
+export const SPACE_2_MOCK = newSpaceMock('Space 2');
+export const SPACE_3 = newSpaceMock('Space 3');
+export const SPACES_MOCK = [SPACE_1_MOCK, SPACE_2_MOCK, SPACE_3];

package/lib/models/Assignment.d.ts

@@ -0,0 +1,7 @@
+import { IBaseNotebook } from './Notebook';
+import { IStudentItem } from './StudentItem';
+export type IAssignment = IBaseNotebook & {
+    type: 'assignment';
+    studentItem?: IStudentItem;
+};
+export default IAssignment;

package/lib/models/Assignment.js

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

package/lib/models/Cell.d.ts

@@ -0,0 +1,8 @@
+import { IItem } from './Item';
+export type ICell = IItem & {
+    type: 'cell';
+    source: string;
+    outputshotUrl?: string;
+    outputshotData?: string;
+};
+export default ICell;

package/lib/models/Cell.js

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

package/lib/models/CodeBlock.d.ts

@@ -0,0 +1,10 @@
+import { IUser } from '@datalayer/core/lib/models/User';
+export type CodeBlock = {
+    id: string;
+    type: 'codeblock';
+    code: string;
+    author: IUser;
+    ancestor: CodeBlock;
+    descendants: CodeBlock[];
+};
+export default CodeBlock;

package/lib/models/CodeBlock.js

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

package/lib/models/CodeSandboxSnapshot.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Code Sandbox snapshot from API.
+ */
+export interface IAPICodeSandboxSnapshot {
+    /**
+     * Snapshot UID
+     */
+    uid: string;
+    /**
+     * Snapshot name
+     */
+    name: string;
+    /**
+     * Snapshot description
+     */
+    description: string;
+    /**
+     * Snapshot environment
+     */
+    environment: string;
+    /**
+     * Snapshot metadata
+     */
+    metadata: Record<string, any>;
+    /**
+     * Snapshot size in bytes
+     */
+    size: number;
+    /**
+     * Latest update time of the snapshot
+     */
+    updated_at: string;
+    /**
+     * Snapshot format
+     */
+    format: string;
+    /**
+     * Snapshot format version
+     */
+    format_version: string;
+    /**
+     * Snapshot status
+     */
+    status: string;
+}
+/**
+ * Code Sandbox snapshot model.
+ */
+export interface ICodeSandboxSnapshot {
+    /**
+     * Snapshot UID
+     */
+    id: string;
+    /**
+     * Snapshot name
+     */
+    name: string;
+    /**
+     * Snapshot description
+     */
+    description: string;
+    /**
+     * Snapshot environment
+     */
+    environment: string;
+    /**
+     * Snapshot metadata
+     */
+    metadata: Record<string, any>;
+    /**
+     * Snapshot size in bytes
+     */
+    size: number;
+    /**
+     * Latest update time of the snapshot
+     */
+    updatedAt: Date;
+    /**
+     * Snapshot format
+     */
+    format: string;
+    /**
+     * Snapshot format version
+     */
+    formatVersion: string;
+    /**
+    
+     * Snapshot status
+     */
+    status: string;
+}
+export declare function asCodeSandboxSnapshot(s: IAPICodeSandboxSnapshot): ICodeSandboxSnapshot;

package/lib/models/CodeSandboxSnapshot.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export function asCodeSandboxSnapshot(s) {
+    const { uid, updated_at, format_version, ...others } = s;
+    return {
+        ...others,
+        id: uid,
+        updatedAt: new Date(updated_at),
+        formatVersion: format_version,
+    };
+}

package/lib/models/CodeSandboxSnapshotDTO.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Snapshot domain model for the Datalayer Client.
+ *
+ * @module models/CodeSandboxSnapshotDTO
+ */
+import type { AgentRuntimesClient as DatalayerClient } from '../client/AgentRuntimesClient';
+import { RuntimeDTO } from './RuntimeDTO';
+/**
+ * Represents a runthime snapshot of a runtime's state and files.
+ * @interface CodeSandboxSnapshotData
+ */
+export interface CodeSandboxSnapshotData {
+    /** Unique identifier for the snapshot */
+    uid: string;
+    /** Name of the snapshot */
+    name: string;
+    /** Optional description of the snapshot */
+    description?: string;
+    /** Name of the environment used by the runtime */
+    environment: string;
+    /** Metadata associated with the snapshot */
+    metadata?: {
+        version?: string;
+        language_info?: any;
+        [key: string]: any;
+    };
+    /** Size of the snapshot in bytes */
+    size?: number;
+    /** Format of the snapshot */
+    format?: string;
+    /** Format version of the snapshot */
+    format_version?: string;
+    /** Status of the snapshot */
+    status?: string;
+    /** ISO 8601 timestamp when the snapshot was last updated */
+    updated_at: string;
+    /** List of files included in the snapshot */
+    files?: any[];
+}
+/**
+ * Stable public interface for Snapshot data.
+ * This is the contract that Client consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface CodeSandboxSnapshotJSON {
+    /** Unique identifier for the snapshot */
+    uid: string;
+    /** Name of the snapshot */
+    name: string;
+    /** Optional description of the snapshot */
+    description?: string;
+    /** Name of the environment used by the runtime */
+    environment: string;
+    /** ISO 8601 timestamp when the snapshot was last updated */
+    updatedAt: string;
+}
+/**
+ * Request payload for creating a code sandbox snapshot
+ * @interface CreateCodeSandboxSnapshotRequest
+ */
+export interface CreateCodeSandboxSnapshotRequest {
+    /** Pod name of the runtime to snapshot */
+    pod_name: string;
+    /** Name for the snapshot */
+    name: string;
+    /** Description of the snapshot */
+    description: string;
+    /** Whether to stop the runtime after creating snapshot */
+    stop: boolean;
+}
+/**
+ * Response for getting a specific code snapshot snapshot
+ * @interface GetCodeSandboxSnapshotResponse
+ */
+export interface GetCodeSandboxSnapshotResponse {
+    /** Indicates if the request was successful */
+    success: boolean;
+    /** Response message */
+    message: string;
+    /** The snapshot details */
+    snapshot: CodeSandboxSnapshotData;
+}
+/**
+ * Response for creating a code sandbox snapshot
+ * @interface CreateCodeSandboxSnapshotResponse
+ */
+export interface CreateCodeSandboxSnapshotResponse {
+    /** Indicates if the request was successful */
+    success: boolean;
+    /** Response message */
+    message: string;
+    /** The created snapshot details */
+    snapshot: CodeSandboxSnapshotData;
+}
+/**
+ * Response from listing code sandbox snapshots
+ * @interface ListCodeSandboxSnapshotsResponse
+ */
+export interface ListCodeSandboxSnapshotsResponse {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Response message from the server */
+    message: string;
+    /** Array of code sandbox snapshots */
+    snapshots: CodeSandboxSnapshotData[];
+}
+/**
+ * Snapshot domain model that wraps API responses with convenient methods.
+ * Provides code sandbox snapshot management with data refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const snapshot = await runtime.createSnapshot('my-checkpoint');
+ * const runtime = await snapshot.restore();
+ * ```
+ */
+export declare class CodeSandboxSnapshotDTO {
+    protected _data: CodeSandboxSnapshotData;
+    private _client;
+    private _deleted;
+    /**
+     * Create a Code Sandbox Snapshot instance.
+     *
+     * @param data - Snapshot data from API
+     * @param client - Client instance
+     */
+    constructor(data: CodeSandboxSnapshotData, client: DatalayerClient);
+    /**
+     * Check if this snapshot has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    private _checkDeleted;
+    /** Unique identifier for the snapshot. */
+    get uid(): string;
+    /** Name of the snapshot. */
+    get name(): string;
+    /** Description of the snapshot. */
+    get description(): string;
+    /** Name of the environment used by the runtime. */
+    get environment(): string;
+    /** When the snapshot was last updated. */
+    get updatedAt(): Date;
+    /**
+     * Delete this snapshot permanently.
+     * After deletion, subsequent calls to dynamic methods will throw errors.
+     */
+    delete(): Promise<void>;
+    /**
+     * Create a code sandbox from this snapshot (restore functionality).
+     *
+     * @param minutesLimit - Time limit in minutes for the restored runtime
+     * @returns Created Runtime instance
+     */
+    restore(minutesLimit: number): Promise<RuntimeDTO>;
+    /**
+     * Get code snapshot snapshot data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     * Note: Returns current cached state - call getStatus() first if you need fresh data.
+     *
+     * @returns Core code snapshot snapshot data with camelCase properties
+     */
+    toJSON(): CodeSandboxSnapshotJSON;
+    /**
+     * Get the raw snapshot data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw snapshot data from API
+     */
+    rawData(): CodeSandboxSnapshotData;
+    /** String representation of the snapshot. */
+    toString(): string;
+}

package/lib/models/CodeSandboxSnapshotDTO.js

@@ -0,0 +1,139 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { snapshots } from '../api/runtimes';
+import { validateJSON } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Snapshot domain model that wraps API responses with convenient methods.
+ * Provides code sandbox snapshot management with data refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const snapshot = await runtime.createSnapshot('my-checkpoint');
+ * const runtime = await snapshot.restore();
+ * ```
+ */
+export class CodeSandboxSnapshotDTO {
+    _data;
+    _client;
+    _deleted = false;
+    /**
+     * Create a Code Sandbox Snapshot instance.
+     *
+     * @param data - Snapshot data from API
+     * @param client - Client instance
+     */
+    constructor(data, client) {
+        this._data = data;
+        this._client = client;
+    }
+    // ========================================================================
+    // Helper Methods
+    // ========================================================================
+    /**
+     * Check if this snapshot has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`Snapshot ${this._data.uid} has been deleted and no longer exists`);
+        }
+    }
+    // ========================================================================
+    // Static Properties (set at creation, never change)
+    // ========================================================================
+    /** Unique identifier for the snapshot. */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /** Name of the snapshot. */
+    get name() {
+        this._checkDeleted();
+        return this._data.name;
+    }
+    /** Description of the snapshot. */
+    get description() {
+        this._checkDeleted();
+        return this._data.description || '';
+    }
+    /** Name of the environment used by the runtime. */
+    get environment() {
+        this._checkDeleted();
+        return this._data.environment;
+    }
+    /** When the snapshot was last updated. */
+    get updatedAt() {
+        this._checkDeleted();
+        return new Date(this._data.updated_at);
+    }
+    // ========================================================================
+    // Action Methods
+    // ========================================================================
+    /**
+     * Delete this snapshot permanently.
+     * After deletion, subsequent calls to dynamic methods will throw errors.
+     */
+    async delete() {
+        this._checkDeleted();
+        const token = this._client.getToken();
+        const runtimesUrl = this._client.getRuntimesUrl();
+        await snapshots.deleteSnapshot(token, this.uid, runtimesUrl);
+        this._deleted = true;
+    }
+    /**
+     * Create a code sandbox from this snapshot (restore functionality).
+     *
+     * @param minutesLimit - Time limit in minutes for the restored runtime
+     * @returns Created Runtime instance
+     */
+    async restore(minutesLimit) {
+        this._checkDeleted();
+        return await this._client.createRuntime({
+            environmentName: this.environment,
+            type: 'notebook',
+            givenName: `Restored from ${this.name}`,
+            minutesLimit: minutesLimit,
+            fromSnapshotId: this.uid,
+        });
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get code snapshot snapshot data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     * Note: Returns current cached state - call getStatus() first if you need fresh data.
+     *
+     * @returns Core code snapshot snapshot data with camelCase properties
+     */
+    toJSON() {
+        this._checkDeleted();
+        const obj = {
+            uid: this.uid,
+            name: this.name,
+            description: this.description,
+            environment: this.environment,
+            updatedAt: this.updatedAt.toISOString(),
+        };
+        validateJSON(obj, 'Snapshot');
+        return obj;
+    }
+    /**
+     * Get the raw snapshot data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw snapshot data from API
+     */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+    /** String representation of the snapshot. */
+    toString() {
+        this._checkDeleted();
+        return `Snapshot(${this.uid}, ${this.name})`;
+    }
+}

package/lib/models/CodefeedBlocks.d.ts

@@ -0,0 +1,7 @@
+import { CodeBlock } from './CodeBlock';
+export type ICodefeedBlocks = {
+    id: string;
+    type: 'codefeed';
+    blocks: CodeBlock[];
+};
+export default ICodefeedBlocks;

package/lib/models/CodefeedBlocks.js

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

package/lib/models/Content.d.ts

@@ -0,0 +1,5 @@
+export interface IContent {
+    name: string;
+    mount: string;
+}
+export default IContent;

package/lib/models/Content.js

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

package/lib/models/Course.d.ts

@@ -0,0 +1,17 @@
+import { IBaseSpace } from './Space';
+import { Instructor } from '@datalayer/core/lib/models/Instructor';
+import { IStudent } from '@datalayer/core/lib/models/Student';
+import { ISchool } from '@datalayer/core/lib/models/School';
+import { ISpace } from './Space';
+import { ISpaceItem } from './SpaceItem';
+export type ICourse = IBaseSpace & {
+    type: 'space';
+    variant: 'course';
+    seedSpace?: ISpace;
+    school?: ISchool;
+    instructor?: Instructor;
+    students?: Map<string, IStudent>;
+    items: Array<ISpaceItem>;
+    itemIds: Array<string>;
+};
+export default ICourse;

package/lib/models/Course.js

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

package/lib/models/Dataset.d.ts

@@ -0,0 +1,16 @@
+import { IItem } from './Item';
+export type IDataset = IItem & {
+    type: 'dataset';
+    fileName: string;
+    datasetExtension: string;
+    contentLength: number;
+    contentType: string;
+    mimeType: string;
+    mimeTypeParams?: object;
+    bucketName?: string;
+    path?: string;
+    creationDate: Date;
+    lastPublicationDate?: Date;
+    cdnUrl: string;
+};
+export default IDataset;

package/lib/models/Dataset.js

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

package/lib/models/Document.d.ts

@@ -0,0 +1,8 @@
+import { IItem } from './Item';
+export type IBaseDocument = IItem & {
+    model?: any;
+};
+export type IDocument = IBaseDocument & {
+    type: 'document';
+};
+export default IDocument;

package/lib/models/Document.js

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