@datalayer/agent-runtimes 1.0.9 → 1.0.17

package/lib/client/AgentsMixin.js

@@ -8,7 +8,7 @@ import * as events from '../api/events';
 import * as output from '../api/output';
 import * as evals from '../api/evals';
 import * as context from '../api/context';
-import * as agentSpecs from '../specs/agents';
+import * as agentspecs from '../specs/agents';
 import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
 /** Agents mixin providing durable agent management. */
 export function AgentsMixin(Base) {
@@ -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);
         }
         // ========================================================================
@@ -261,24 +261,24 @@ export function AgentsMixin(Base) {
          * @param agentSpecId - Agent spec identifier.
          * @returns The agent spec, or undefined if not found.
          */
-        getAgentSpec(agentSpecId) {
-            return agentSpecs.getAgentSpecs(agentSpecId);
+        getAgentspec(agentSpecId) {
+            return agentspecs.getAgentspecs(agentSpecId);
         }
         /**
          * List all available agent specifications.
          * @param prefix - If provided, only return specs whose ID starts with this prefix.
          * @returns Array of agent specifications.
          */
-        listAgentSpecs(prefix) {
-            return agentSpecs.listAgentSpecs(prefix);
+        listAgentspecs(prefix) {
+            return agentspecs.listAgentspecs(prefix);
         }
         /**
          * Get required environment variables for an agent spec.
          * @param spec - The agent specification.
          * @returns Deduplicated array of required environment variable names.
          */
-        getAgentSpecRequiredEnvVars(spec) {
-            return agentSpecs.getAgentSpecRequiredEnvVars(spec);
+        getAgentspecRequiredEnvVars(spec) {
+            return agentspecs.getAgentspecRequiredEnvVars(spec);
         }
         // ========================================================================
         // Project Agent Assignment
@@ -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);
  * ```
  */

package/lib/client/SdkAgentRuntimesClient.js

@@ -13,7 +13,7 @@
  * 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);
  * ```
  */

package/lib/client/mixins/RuntimesMixin.d.ts

@@ -0,0 +1,93 @@
+import type { Constructor } from '@datalayer/core/lib/client/utils/mixins';
+import { EnvironmentDTO } from '../../models/EnvironmentDTO';
+import { RuntimeDTO } from '../../models/RuntimeDTO';
+import { CodeSandboxSnapshotDTO } from '../../models/CodeSandboxSnapshotDTO';
+import { HealthCheck } from '@datalayer/core/lib/models/HealthCheck';
+/** Options for ensuring a runtime is available. */
+export interface EnsureRuntimeOptions {
+    /** Name of the environment to use */
+    environmentName?: string;
+    /** Maximum credits to allocate */
+    creditsLimit?: number;
+    /** Whether to wait for runtime to be ready */
+    waitForReady?: boolean;
+    /** Maximum time to wait for ready state (ms) */
+    maxWaitTime?: number;
+    /** Whether to reuse existing suitable runtime */
+    reuseExisting?: boolean;
+    /** Snapshot ID to create runtime from */
+    snapshotId?: string;
+}
+/** Runtimes mixin providing computational environment and runtime management. */
+export declare function RuntimesMixin<TBase extends Constructor>(Base: TBase): {
+    new (...args: any[]): {
+        _extractRuntimePodName(runtimePodNameOrInstance: string | RuntimeDTO): string;
+        _extractSnapshotId(snapshotIdOrInstance: string | CodeSandboxSnapshotDTO): string;
+        /**
+         * List all available computational environments.
+         * @returns Array of Environment model instances
+         */
+        listEnvironments(): Promise<EnvironmentDTO[]>;
+        /**
+         * Create a new computational runtime.
+         * @param environmentName - Name of the environment to use
+         * @param type - Type of runtime
+         * @param givenName - User-friendly name for the runtime
+         * @param creditsLimit - Credits limit
+         * @returns Created runtime
+         */
+        createRuntime(environmentName: string, type: "notebook" | "terminal" | "job", givenName: string, minutesLimit: number, fromSnapshotId?: string): Promise<RuntimeDTO>;
+        /**
+         * List all runtimes.
+         * @returns Array of runtimes
+         */
+        listRuntimes(): Promise<RuntimeDTO[]>;
+        /**
+         * Get details for a specific runtime by pod name.
+         * @param podName - Runtime pod name
+         * @returns Runtime details
+         */
+        getRuntime(podName: string): Promise<RuntimeDTO>;
+        /**
+         * Delete a runtime permanently.
+         * @param podName - Runtime pod name
+         */
+        deleteRuntime(podName: string): Promise<void>;
+        /**
+         * Terminate all runtimes.
+         * Lists all runtimes and deletes them in parallel.
+         * @returns Array of results for each deletion (fulfilled or rejected)
+         */
+        terminateAllRuntimes(): Promise<PromiseSettledResult<void>[]>;
+        /**
+         * Create a snapshot of a runtime.
+         * @param podName - Pod name of the runtime to snapshot
+         * @param name - Name for the snapshot
+         * @param description - Description of the snapshot
+         * @param stop - Whether to stop the runtime after creating snapshot (defaults to false)
+         * @returns Created snapshot
+         */
+        createSnapshot(podName: string, name: string, description: string, stop?: boolean): Promise<CodeSandboxSnapshotDTO>;
+        /**
+         * List all code sandbox snapshots.
+         * @returns Array of snapshots
+         */
+        listSnapshots(): Promise<CodeSandboxSnapshotDTO[]>;
+        /**
+         * Get details for a specific snapshot by ID.
+         * @param id - Snapshot ID
+         * @returns Snapshot details
+         */
+        getSnapshot(id: string): Promise<CodeSandboxSnapshotDTO>;
+        /**
+         * Delete a snapshot permanently.
+         * @param id - Snapshot ID
+         */
+        deleteSnapshot(id: string): Promise<void>;
+        /**
+         * Check the health status of the Runtimes service.
+         * @returns Health check result with status and response time
+         */
+        checkRuntimesHealth(): Promise<HealthCheck>;
+    };
+} & TBase;

package/lib/client/mixins/RuntimesMixin.js

@@ -0,0 +1,229 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Runtimes mixin for managing computational environments and runtime instances.
+ * @module client/mixins/RuntimesMixin
+ */
+import * as environments from '../../api/runtimes/environments';
+import * as runtimes from '../../api/runtimes/runtimes';
+import * as snapshots from '../../api/runtimes/snapshots';
+import { EnvironmentDTO } from '../../models/EnvironmentDTO';
+import { RuntimeDTO } from '../../models/RuntimeDTO';
+import { CodeSandboxSnapshotDTO } from '../../models/CodeSandboxSnapshotDTO';
+import { HealthCheck } from '@datalayer/core/lib/models/HealthCheck';
+/** Runtimes mixin providing computational environment and runtime management. */
+export function RuntimesMixin(Base) {
+    return class extends Base {
+        // ========================================================================
+        // Helper Functions
+        // ========================================================================
+        _extractRuntimePodName(runtimePodNameOrInstance) {
+            return typeof runtimePodNameOrInstance === 'string'
+                ? runtimePodNameOrInstance
+                : runtimePodNameOrInstance.podName;
+        }
+        _extractSnapshotId(snapshotIdOrInstance) {
+            return typeof snapshotIdOrInstance === 'string'
+                ? snapshotIdOrInstance
+                : snapshotIdOrInstance.uid;
+        }
+        // ========================================================================
+        // Environments
+        // ========================================================================
+        /**
+         * List all available computational environments.
+         * @returns Array of Environment model instances
+         */
+        async listEnvironments() {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const response = await environments.listEnvironments(token, runtimesUrl);
+            // Save for later use after first call
+            this.environments = response.environments.map(env => new EnvironmentDTO(env, this));
+            return this.environments;
+        }
+        // ========================================================================
+        // Runtimes
+        // ========================================================================
+        /**
+         * Create a new computational runtime.
+         * @param environmentName - Name of the environment to use
+         * @param type - Type of runtime
+         * @param givenName - User-friendly name for the runtime
+         * @param creditsLimit - Credits limit
+         * @returns Created runtime
+         */
+        async createRuntime(environmentName, type, givenName, minutesLimit, fromSnapshotId) {
+            if (!this.environments) {
+                await this.listEnvironments();
+            }
+            if (this.environments) {
+                const env = this.environments.find((e) => e.name === environmentName);
+                if (!env) {
+                    throw new Error(`Environment "${environmentName}" not found. Available environments: ${this.environments.map((e) => e.name).join(', ')}`);
+                }
+                else {
+                    const token = this.getToken();
+                    const runtimesUrl = this.getRuntimesUrl();
+                    const creditsLimit = this.calculateCreditsFromMinutes(minutesLimit, env.burningRate);
+                    const data = {
+                        environment_name: environmentName,
+                        type,
+                        given_name: givenName,
+                        credits_limit: creditsLimit,
+                        from: fromSnapshotId,
+                    };
+                    const response = await runtimes.createRuntime(token, data, runtimesUrl);
+                    return new RuntimeDTO(response.runtime, this);
+                }
+            }
+            else {
+                throw new Error('Environments not loaded');
+            }
+        }
+        /**
+         * List all runtimes.
+         * @returns Array of runtimes
+         */
+        async listRuntimes() {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const response = await runtimes.listRuntimes(token, runtimesUrl);
+            return response.runtimes.map(r => new RuntimeDTO(r, this));
+        }
+        /**
+         * Get details for a specific runtime by pod name.
+         * @param podName - Runtime pod name
+         * @returns Runtime details
+         */
+        async getRuntime(podName) {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const runtimeData = await runtimes.getRuntime(token, podName, runtimesUrl);
+            return new RuntimeDTO(runtimeData, this);
+        }
+        /**
+         * Delete a runtime permanently.
+         * @param podName - Runtime pod name
+         */
+        async deleteRuntime(podName) {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            await runtimes.deleteRuntime(token, podName, runtimesUrl);
+        }
+        /**
+         * Terminate all runtimes.
+         * Lists all runtimes and deletes them in parallel.
+         * @returns Array of results for each deletion (fulfilled or rejected)
+         */
+        async terminateAllRuntimes() {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            // List all runtimes
+            const response = await runtimes.listRuntimes(token, runtimesUrl);
+            // Delete all runtimes in parallel
+            const deletePromises = response.runtimes.map(runtime => runtimes.deleteRuntime(token, runtime.pod_name, runtimesUrl));
+            return Promise.allSettled(deletePromises);
+        }
+        // ========================================================================
+        // Snapshots
+        // ========================================================================
+        /**
+         * Create a snapshot of a runtime.
+         * @param podName - Pod name of the runtime to snapshot
+         * @param name - Name for the snapshot
+         * @param description - Description of the snapshot
+         * @param stop - Whether to stop the runtime after creating snapshot (defaults to false)
+         * @returns Created snapshot
+         */
+        async createSnapshot(podName, name, description, stop = false) {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const data = {
+                pod_name: podName,
+                name,
+                description,
+                stop,
+            };
+            const response = await snapshots.createSnapshot(token, data, runtimesUrl);
+            return new CodeSandboxSnapshotDTO(response.snapshot, this);
+        }
+        /**
+         * List all code sandbox snapshots.
+         * @returns Array of snapshots
+         */
+        async listSnapshots() {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const response = await snapshots.listSnapshots(token, runtimesUrl);
+            return response.snapshots.map(s => new CodeSandboxSnapshotDTO(s, this));
+        }
+        /**
+         * Get details for a specific snapshot by ID.
+         * @param id - Snapshot ID
+         * @returns Snapshot details
+         */
+        async getSnapshot(id) {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            const response = await snapshots.getSnapshot(token, id, runtimesUrl);
+            return new CodeSandboxSnapshotDTO(response.snapshot, this);
+        }
+        /**
+         * Delete a snapshot permanently.
+         * @param id - Snapshot ID
+         */
+        async deleteSnapshot(id) {
+            const token = this.getToken();
+            const runtimesUrl = this.getRuntimesUrl();
+            await snapshots.deleteSnapshot(token, id, runtimesUrl);
+        }
+        // ========================================================================
+        // Service Health Checks
+        // ========================================================================
+        /**
+         * Check the health status of the Runtimes service.
+         * @returns Health check result with status and response time
+         */
+        async checkRuntimesHealth() {
+            const startTime = Date.now();
+            const errors = [];
+            let status = 'unknown';
+            let healthy = false;
+            try {
+                // Test basic connectivity by listing environments (lightweight operation)
+                const environments = await this.listEnvironments();
+                const responseTime = Date.now() - startTime;
+                if (Array.isArray(environments)) {
+                    healthy = true;
+                    status = 'operational';
+                }
+                else {
+                    status = 'degraded';
+                    errors.push('Unexpected response format from environments endpoint');
+                }
+                return new HealthCheck({
+                    healthy,
+                    status,
+                    responseTime,
+                    errors,
+                    timestamp: new Date(),
+                }, this);
+            }
+            catch (error) {
+                const responseTime = Date.now() - startTime;
+                status = 'down';
+                errors.push(`Service unreachable: ${error}`);
+                return new HealthCheck({
+                    healthy: false,
+                    status,
+                    responseTime,
+                    errors,
+                    timestamp: new Date(),
+                }, this);
+            }
+        }
+    };
+}