@datalayer/agent-runtimes 1.0.9 → 1.0.17

package/lib/models/SpaceDTO.js

@@ -0,0 +1,244 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Space domain model for the Datalayer Client.
+ *
+ * @module models/SpaceDTO
+ */
+import * as users from '../api/spacer/users';
+import * as items from '../api/spacer/items';
+import * as notebooks from '../api/spacer/notebooks';
+import * as lexicals from '../api/spacer/lexicals';
+import { NotebookDTO } from './NotebookDTO';
+import { LexicalDTO } from './LexicalDTO';
+import { ItemTypes } from '@datalayer/core/lib/client/constants';
+import { convertSpaceItemsToModels } from '../client/utils/spacerUtils';
+import { validateJSON } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Space domain model that wraps API responses with convenient methods.
+ * Provides workspace management with data refresh and content creation operations.
+ *
+ * @example
+ * ```typescript
+ * const space = spaces[0];
+ * const items = await space.getItems();
+ * const notebook = await space.createNotebook({ name: 'Analysis' });
+ * ```
+ */
+export class SpaceDTO {
+    _data;
+    _client;
+    _items = null;
+    _deleted = false;
+    /**
+     * Create a Space instance.
+     *
+     * @param data - Space data from API
+     * @param client - Client instance
+     */
+    constructor(data, client) {
+        this._data = data;
+        this._client = client;
+    }
+    // ========================================================================
+    // Helper Methods
+    // ========================================================================
+    /**
+     * Check if this space has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`Space ${this._data.uid} has been deleted and no longer exists`);
+        }
+    }
+    /**
+     * Refresh space data from the API by fetching user's spaces.
+     */
+    async refresh() {
+        const token = this._client.getToken();
+        const spacerUrl = this._client.getSpacerUrl();
+        const response = await users.getMySpaces(token, spacerUrl);
+        const freshSpace = response.spaces.find(s => s.uid === this.uid);
+        if (freshSpace) {
+            this._data = freshSpace;
+        }
+    }
+    // ========================================================================
+    // Static Properties (set at creation, never change)
+    // ========================================================================
+    /** Unique identifier for the space. */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /** URL-friendly handle for the space. */
+    get handle() {
+        this._checkDeleted();
+        return this._data.handle_s;
+    }
+    /** Space variant type. */
+    get variant() {
+        this._checkDeleted();
+        return this._data.variant_s;
+    }
+    /**
+     * The name of the space.
+     */
+    get name() {
+        return this._data.name_t;
+    }
+    /**
+     * The description of the space.
+     */
+    get description() {
+        return this._data.description_t;
+    }
+    // ========================================================================
+    // Space-specific Methods
+    // ========================================================================
+    /**
+     * Helper method to create items in this space.
+     *
+     * @param itemType - Type of item to create
+     * @param data - Creation configuration
+     * @returns Created model instance
+     * @internal
+     */
+    async _createItem(data) {
+        this._checkDeleted();
+        // Get necessary configuration from Client
+        const token = this._client.getToken();
+        const spacerUrl = this._client.getSpacerUrl();
+        if (data.type === ItemTypes.NOTEBOOK) {
+            const requestData = {
+                spaceId: this.uid,
+                name: data.name,
+                description: data.description,
+                notebookType: data.type,
+                file: data.file,
+            };
+            const response = await notebooks.createNotebook(token, requestData, spacerUrl);
+            if (!response.notebook) {
+                throw new Error('Failed to create notebook: No notebook returned');
+            }
+            else {
+                return new NotebookDTO(response.notebook, this._client);
+            }
+        }
+        else if (data.type === ItemTypes.LEXICAL) {
+            const requestData = {
+                spaceId: this.uid,
+                name: data.name,
+                description: data.description,
+                documentType: data.type,
+                file: data.file,
+            };
+            const response = await lexicals.createLexical(token, requestData, spacerUrl);
+            if (!response.document) {
+                throw new Error('Failed to create lexical document: No document returned');
+            }
+            else {
+                return new LexicalDTO(response.document, this._client);
+            }
+        }
+        else {
+            throw new Error(`Unsupported item type: ${data.type}`);
+        }
+    }
+    /**
+     * Get all items in this space as model instances.
+     *
+     * @returns Array of Notebook and Lexical model instances
+     */
+    async getItems() {
+        this._checkDeleted();
+        const token = this._client.getToken();
+        const spacerUrl = this._client.getSpacerUrl();
+        const response = await items.getSpaceItems(token, this.uid, spacerUrl);
+        // Use shared utility function to convert items to model instances
+        this._items = convertSpaceItemsToModels(response.items || [], this._client);
+        return this._items;
+    }
+    /**
+     * Create a new notebook in this space.
+     *
+     * @param data - Notebook creation configuration
+     * @returns Created Notebook instance
+     */
+    async createNotebook(data) {
+        return this._createItem({
+            name: data.name,
+            type: ItemTypes.NOTEBOOK,
+            description: data.description,
+            file: data.file,
+        });
+    }
+    /**
+     * Create a new lexical document in this space.
+     *
+     * @param data - Lexical creation configuration
+     * @returns Created Lexical instance
+     */
+    async createLexical(data) {
+        return this._createItem({
+            name: data.name,
+            type: ItemTypes.LEXICAL,
+            description: data.description,
+            file: data.file,
+        });
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get raw space data object.
+     * Returns cached data without refreshing.
+     *
+     * @returns Raw space data object
+     */
+    /**
+     * Get space data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     *
+     * @returns Core space data with camelCase properties
+     */
+    toJSON() {
+        this._checkDeleted();
+        const ownerUserUids = Array.from(new Set([
+            ...(this._data.shared_owner_user_uids_ss || []),
+            ...(this._data.shared_ower_user_uids_ss || []),
+        ].filter(uid => typeof uid === 'string' && uid.length > 0)));
+        const obj = {
+            uid: this.uid,
+            name: this.name,
+            description: this.description,
+            variant: this.variant,
+            handle: this.handle,
+            ownerUserUids,
+            items: this._data.items
+                ? convertSpaceItemsToModels(this._data.items, this._client).map(item => item.toJSON())
+                : [],
+        };
+        validateJSON(obj, 'Space');
+        return obj;
+    }
+    /**
+     * Get the raw space data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     *
+     * @returns Raw space data from API
+     */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+    /** String representation of the space. */
+    toString() {
+        this._checkDeleted();
+        return `Space(${this.uid}, ${this.name})`;
+    }
+}

package/lib/models/SpaceItem.d.ts

@@ -0,0 +1,10 @@
+import { INotebook } from './Notebook';
+import { IDocument } from './Document';
+import { ICell } from './Cell';
+import { IDataset } from './Dataset';
+import { IEnvironment } from './Environment';
+import { ILesson } from './Lesson';
+import { IExercise } from './Exercise';
+import { IAssignment } from './Assignment';
+export type ISpaceItem = IDataset | INotebook | ICell | IEnvironment | ILesson | IExercise | IAssignment | IDocument;
+export default ISpaceItem;

package/lib/models/SpaceItem.js

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

package/lib/models/SpaceMember.d.ts

@@ -0,0 +1,6 @@
+import { Member } from '@datalayer/core/lib/models/Member';
+import { ISpace } from './Space';
+export type SpaceMember = Member & {
+    space?: ISpace;
+};
+export default SpaceMember;

package/lib/models/SpaceMember.js

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

package/lib/models/StudentItem.d.ts

@@ -0,0 +1,21 @@
+import { IItemType } from './ItemType';
+import { IStudent } from '@datalayer/core/lib/models/Student';
+import { ISpaceItem } from './SpaceItem';
+export type IStudentItem = {
+    id: string;
+    type: 'student_item';
+    student?: IStudent;
+    item?: ISpaceItem;
+    itemId: string;
+    itemType: IItemType;
+    score?: number;
+    nbgrades?: any;
+    nbgradesTotalPoints?: number;
+    nbgradesTotalScore?: number;
+    completed?: boolean;
+    codeStudent?: string;
+    pass?: boolean;
+    invalid?: boolean;
+    invalidReason?: string;
+};
+export default IStudentItem;

package/lib/models/StudentItem.js

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

package/lib/models/index.d.ts

@@ -0,0 +1,32 @@
+export * from './Assignment';
+export * from './Cell';
+export * from './CodeBlock';
+export * from './CodefeedBlocks';
+export * from './CodeSandboxSnapshot';
+export * from './CodeSandboxSnapshotDTO';
+export * from './Content';
+export * from './Course';
+export * from './Dataset';
+export * from './Document';
+export * from './Environment';
+export * from './EnvironmentDTO';
+export * from './Exercise';
+export * from './Item';
+export * from './ItemDTO';
+export * from './ItemType';
+export * from './Lesson';
+export * from './LexicalDTO';
+export * from './Library';
+export * from './Notebook';
+export * from './NotebookDTO';
+export * from './Page';
+export * from './PageTag';
+export * from './ProjectDTO';
+export * from './Runtime';
+export * from './RuntimeDTO';
+export * from './Space';
+export * from './SpaceDTO';
+export * from './SpaceItem';
+export * from './SpaceMember';
+export * from './StudentItem';
+export * from '@datalayer/core/lib/models';

package/lib/models/index.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+// Moved runtime + content + education models (owned by agent-runtimes).
+export * from './Assignment';
+export * from './Cell';
+export * from './CodeBlock';
+export * from './CodefeedBlocks';
+export * from './CodeSandboxSnapshot';
+export * from './CodeSandboxSnapshotDTO';
+export * from './Content';
+export * from './Course';
+export * from './Dataset';
+export * from './Document';
+export * from './Environment';
+export * from './EnvironmentDTO';
+export * from './Exercise';
+export * from './Item';
+export * from './ItemDTO';
+export * from './ItemType';
+export * from './Lesson';
+export * from './LexicalDTO';
+export * from './Library';
+export * from './Notebook';
+export * from './NotebookDTO';
+export * from './Page';
+export * from './PageTag';
+export * from './ProjectDTO';
+export * from './Runtime';
+export * from './RuntimeDTO';
+export * from './Space';
+export * from './SpaceDTO';
+export * from './SpaceItem';
+export * from './SpaceMember';
+export * from './StudentItem';
+// Re-export identity/plans/account model interfaces that stay in core so
+// agent-runtimes code can resolve every model from this single barrel.
+export * from '@datalayer/core/lib/models';

package/lib/protocols/AGUIAdapter.js

@@ -85,7 +85,7 @@ export class AGUIAdapter extends BaseProtocolAdapter {
     async terminateAgent(threadId) {
         try {
             // Derive the terminate endpoint from the base URL
-            // e.g., http://localhost:8765/api/v1/examples/agentic_chat -> http://localhost:8765/api/v1/ag-ui/terminate
+            // e.g., http://localhost:8765/api/v1/ag-ui/default -> http://localhost:8765/api/v1/ag-ui/terminate
             const baseUrl = new URL(this.aguiConfig.baseUrl);
             const terminateUrl = `${baseUrl.origin}/api/v1/ag-ui/terminate`;
             const response = await fetch(terminateUrl, {

package/lib/runtimes/actions.d.ts

@@ -0,0 +1,102 @@
+import type { IRuntimeOptions } from './apis';
+import type { ICodeSandboxSnapshot, IDatalayerEnvironment, IRuntimePod } from '../models';
+/**
+ * Get available Environments.
+ */
+export declare function getEnvironments(): Promise<IDatalayerEnvironment[]>;
+/**
+ * Create a Runtime.
+ */
+export declare function createRuntime(options: IRuntimeOptions): Promise<IRuntimePod>;
+/**
+ * Get the Runtimes.
+ */
+export declare function getRuntimes(): Promise<IRuntimePod[]>;
+/**
+ * Delete a Runtime
+ */
+export declare function deleteRuntime(options: {
+    /**
+     * Runtime ID
+     */
+    id: string;
+    /**
+     * Deletion reason
+     */
+    reason?: string;
+}): Promise<void>;
+/**
+ * Snapshot a Runtime.
+ */
+export declare function snapshotRuntime(options: {
+    /**
+     * Runtime ID.
+     */
+    id: string;
+    /**
+     * Snapshot name.
+     */
+    name?: string;
+    /**
+     * Snapshot description.
+     */
+    description?: string;
+    /**
+     * Whether to stop the runtime after the snapshot completion or not.
+     */
+    stop?: boolean;
+}): Promise<ICodeSandboxSnapshot | undefined>;
+/**
+ * Get Code Sandbox Snapshots.
+ */
+export declare function getSandboxSnapshots(): Promise<ICodeSandboxSnapshot[]>;
+/**
+ * Load a Code Sandbox Snapshot within a Runtime.
+ */
+export declare function loadSandboxSnapshot(options: {
+    /**
+     * Runtime ID
+     */
+    id: string;
+    /**
+     * Snapshot UID
+     */
+    from: string;
+}): Promise<void>;
+/**
+ * Returns the Code Sandbox Snapshot download URL.
+ *
+ * @param id Snapshot UID to download
+ * @returns The download URL
+ */
+export declare function createSandboxSnapshotDownloadURL(id: string): string;
+/**
+ * Export a Code Sandbox Snapshot.
+ *
+ * @param id Code Sandbox snapshot UID to download
+ */
+export declare function exportCodeSandboxSnapshot(id: string): void;
+/**
+ * Delete a Code Sandbox Snapshot.
+ */
+export declare function deleteCodeSandboxSnapshot(id: string): Promise<void>;
+/**
+ * Update Code Sandbox Snapshot metadata.
+ */
+export declare function updateCodeSandboxSnapshot(id: string, metadata: {
+    name?: string;
+    description?: string;
+}): Promise<void>;
+/**
+ * Upload a Code Sandbox Snapshot.
+ *
+ * Note: The promise will be rejected if the runtime state is empty.
+ */
+export declare function uploadCodeSandboxSnapshot(options: {
+    file: File | Blob;
+    metadata: {
+        filename: string;
+        [key: string]: string;
+    };
+    onProgress?: (bytesUploaded: number, bytesTotal: number) => void;
+}): Promise<void>;