@datalayer/agent-runtimes 1.0.10 → 1.0.17

package/lib/models/PageTag.js

@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { CopilotIcon, ZapIcon } from '@primer/octicons-react';
+export const PAGE_TAGE_NONE = {
+    id: '0',
+    text: undefined,
+    Icon: CopilotIcon,
+    color: 'pink',
+};
+const PAGE_TAGE_AGENT = {
+    id: '9',
+    text: 'agent',
+    Icon: CopilotIcon,
+    color: 'teal',
+};
+const PAGE_TAGE_AI = {
+    id: '1',
+    text: 'ai',
+    Icon: CopilotIcon,
+    color: 'pink',
+};
+const PAGE_TAGE_AI_AGENT = {
+    id: '10',
+    text: 'ai-agent',
+    Icon: CopilotIcon,
+    color: 'purple',
+};
+const PAGE_TAGE_DEEP_LEARNING = {
+    id: '2',
+    text: 'deep-learning',
+    Icon: ZapIcon,
+    color: 'blue',
+};
+const PAGE_TAGE_EXAMPLE = {
+    id: '3',
+    text: 'example',
+    Icon: CopilotIcon,
+    color: 'lime',
+};
+const PAGE_TAGE_LLM = {
+    id: '4',
+    text: 'llm',
+    Icon: CopilotIcon,
+    color: 'coral',
+};
+const PAGE_TAGE_NOTEBOOK = {
+    id: '11',
+    text: 'notebook',
+    Icon: CopilotIcon,
+    color: 'blue',
+};
+const PAGE_TAGE_PYTHON = {
+    id: '5',
+    text: 'python',
+    Icon: CopilotIcon,
+    color: 'gray',
+    metadata: { fillColor: 'var(--base-color-green-0)' },
+};
+const PAGE_TAGE_PYTORCH = {
+    id: '6',
+    text: 'pytorch',
+    Icon: CopilotIcon,
+    color: 'green',
+};
+const PAGE_TAGE_SPATIAL = {
+    id: '7',
+    text: 'spatial',
+    Icon: CopilotIcon,
+    color: 'lemon',
+};
+const PAGE_TAGE_TUTORIAL = {
+    id: '8',
+    text: 'tutorial',
+    Icon: CopilotIcon,
+    color: 'orange',
+    metadata: { fillColor: 'yellow' },
+};
+export const PAGE_TAGS = [
+    PAGE_TAGE_AGENT,
+    PAGE_TAGE_AI,
+    PAGE_TAGE_AI_AGENT,
+    PAGE_TAGE_DEEP_LEARNING,
+    PAGE_TAGE_EXAMPLE,
+    PAGE_TAGE_LLM,
+    PAGE_TAGE_NOTEBOOK,
+    PAGE_TAGE_PYTHON,
+    PAGE_TAGE_PYTORCH,
+    PAGE_TAGE_SPATIAL,
+    PAGE_TAGE_TUTORIAL,
+];
+export const PAGE_TAGS_BY_NAME_MAP = new Map(PAGE_TAGS.map(t => [t.text, t]));
+export const PAGE_TAGS_BY_COLOR_MAP = new Map(PAGE_TAGS.map(t => [t.color, t]));

package/lib/models/ProjectDTO.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Project domain model for the Datalayer Client.
+ *
+ * Projects are spaces with variant='project' that can have attached agents.
+ * This is a standalone model (no inheritance from SpaceDTO) to avoid
+ * circular dependency issues in the module graph.
+ *
+ * @module models/ProjectDTO
+ */
+import type { SpaceData } from './SpaceDTO';
+/**
+ * Stable public interface for Project data.
+ */
+export interface ProjectJSON {
+    uid: string;
+    id: string;
+    handle: string;
+    name: string;
+    description: string;
+    variant: string;
+    isPublic: boolean;
+    createdAt: string;
+    attachedAgentPodName: string | null;
+    attachedAgentSpecId: string | null;
+    attachedAgentGivenName: string | null;
+    hasAgent: boolean;
+}
+/**
+ * Default items (notebook UID and document UID) for a project.
+ */
+export interface ProjectDefaultItems {
+    defaultNotebookUid: string | null;
+    defaultDocumentUid: string | null;
+}
+/**
+ * Project domain model wrapping raw space data with project-specific accessors.
+ *
+ * @example
+ * ```typescript
+ * const projects = await client.getProjects();
+ * const project = projects[0];
+ * console.log(project.hasAgent); // false
+ * await client.assignAgent(project.uid, 'my-agent-pod');
+ * ```
+ */
+export declare class ProjectDTO {
+    private _data;
+    private _deleted;
+    private _createdAt;
+    constructor(data: SpaceData);
+    /** Unique identifier for the project. */
+    get uid(): string;
+    /** Internal numeric/string ID from the backend. Falls back to UID when not present. SDK client methods accept `uid` directly. */
+    get id(): string;
+    /** URL-friendly handle. */
+    get handle(): string;
+    /** Project name. */
+    get name(): string;
+    /** Project description. */
+    get description(): string;
+    /** Space variant (should be 'project'). */
+    get variant(): string;
+    /** Whether the project is public. */
+    get isPublic(): boolean;
+    /** Creation date (stable across calls). */
+    get createdAt(): Date;
+    /** Attached agent runtime pod name, if any. */
+    get attachedAgentPodName(): string | undefined;
+    /** Attached agentspec ID (e.g., 'data-acquisition'), if any. */
+    get attachedAgentSpecId(): string | undefined;
+    /** Human-readable name of the attached agent runtime, if any. */
+    get attachedAgentGivenName(): string | undefined;
+    /** Whether an agent is currently attached to this project. */
+    get hasAgent(): boolean;
+    /** Mark this project as deleted. */
+    markDeleted(): void;
+    /** Whether this project has been deleted. */
+    get isDeleted(): boolean;
+    /**
+     * Get project data in camelCase format.
+     * @returns Project data with camelCase properties
+     */
+    toJSON(): ProjectJSON;
+    /** Get raw space data as received from the API. */
+    rawData(): SpaceData;
+    /** String representation of the project. */
+    toString(): string;
+    private _checkDeleted;
+}

package/lib/models/ProjectDTO.js

@@ -0,0 +1,131 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Project domain model wrapping raw space data with project-specific accessors.
+ *
+ * @example
+ * ```typescript
+ * const projects = await client.getProjects();
+ * const project = projects[0];
+ * console.log(project.hasAgent); // false
+ * await client.assignAgent(project.uid, 'my-agent-pod');
+ * ```
+ */
+export class ProjectDTO {
+    _data;
+    _deleted = false;
+    _createdAt;
+    constructor(data) {
+        this._data = data;
+        // Cache creation date at construction to ensure stable value
+        this._createdAt = data.creation_ts_dt
+            ? new Date(data.creation_ts_dt)
+            : new Date();
+    }
+    /** Unique identifier for the project. */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /** Internal numeric/string ID from the backend. Falls back to UID when not present. SDK client methods accept `uid` directly. */
+    get id() {
+        this._checkDeleted();
+        return this._data.id ?? this._data.uid;
+    }
+    /** URL-friendly handle. */
+    get handle() {
+        this._checkDeleted();
+        return this._data.handle_s;
+    }
+    /** Project name. */
+    get name() {
+        this._checkDeleted();
+        return this._data.name_t;
+    }
+    /** Project description. */
+    get description() {
+        this._checkDeleted();
+        return this._data.description_t ?? '';
+    }
+    /** Space variant (should be 'project'). */
+    get variant() {
+        this._checkDeleted();
+        return this._data.variant_s;
+    }
+    /** Whether the project is public. */
+    get isPublic() {
+        this._checkDeleted();
+        return this._data.public_b ?? false;
+    }
+    /** Creation date (stable across calls). */
+    get createdAt() {
+        this._checkDeleted();
+        return this._createdAt;
+    }
+    /** Attached agent runtime pod name, if any. */
+    get attachedAgentPodName() {
+        this._checkDeleted();
+        return this._data.attached_agent_pod_name_s || undefined;
+    }
+    /** Attached agentspec ID (e.g., 'data-acquisition'), if any. */
+    get attachedAgentSpecId() {
+        this._checkDeleted();
+        return this._data.attached_agent_spec_id_s || undefined;
+    }
+    /** Human-readable name of the attached agent runtime, if any. */
+    get attachedAgentGivenName() {
+        this._checkDeleted();
+        return this._data.attached_agent_given_name_s || undefined;
+    }
+    /** Whether an agent is currently attached to this project. */
+    get hasAgent() {
+        this._checkDeleted();
+        return !!this._data.attached_agent_pod_name_s;
+    }
+    /** Mark this project as deleted. */
+    markDeleted() {
+        this._deleted = true;
+    }
+    /** Whether this project has been deleted. */
+    get isDeleted() {
+        return this._deleted;
+    }
+    /**
+     * Get project data in camelCase format.
+     * @returns Project data with camelCase properties
+     */
+    toJSON() {
+        this._checkDeleted();
+        return {
+            uid: this.uid,
+            id: this.id,
+            handle: this.handle,
+            name: this.name,
+            description: this.description,
+            variant: this.variant,
+            isPublic: this.isPublic,
+            createdAt: this.createdAt.toISOString(),
+            attachedAgentPodName: this.attachedAgentPodName ?? null,
+            attachedAgentSpecId: this.attachedAgentSpecId ?? null,
+            attachedAgentGivenName: this.attachedAgentGivenName ?? null,
+            hasAgent: this.hasAgent,
+        };
+    }
+    /** Get raw space data as received from the API. */
+    rawData() {
+        this._checkDeleted();
+        return this._data;
+    }
+    /** String representation of the project. */
+    toString() {
+        this._checkDeleted();
+        return `Project(${this._data.uid}, ${this._data.name_t})`;
+    }
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`Project ${this._data.uid} has been deleted and no longer exists`);
+        }
+    }
+}

package/lib/models/Runtime.d.ts

@@ -0,0 +1,160 @@
+import { Kernel } from '@jupyterlab/services';
+export declare const BACKWARDS_COMPATIBLE_KERNEL_TYPES_MAP: {
+    default: IRuntimeType;
+    snippet: IRuntimeType;
+    notebook: IRuntimeType;
+    cell: IRuntimeType;
+};
+/**
+ * Error thrown when a runtime has been created
+ * but it can ont be reached.
+ */
+export declare class RuntimeUnreachable extends Error {
+    name: string;
+}
+/**
+ * Runtime location.
+ */
+export type IRuntimeLocation = 'browser' | 'local' | string;
+/**
+ * A live runtime.
+ *
+ * Composition of the control-plane runtime pod ({@link IRuntimePod}) and the
+ * JupyterLab kernel model ({@link Kernel.IModel}, e.g. `id`, `name`,
+ * `execution_state`). This is the canonical shape used across the app once a
+ * pod has an attached kernel: `IRuntimePod` supplies the pod/control-plane
+ * fields (snake_case) and `Kernel.IModel` supplies the live kernel fields.
+ *
+ * Note on identity: `Kernel.IModel.id` is the *kernel* id (only present once a
+ * kernel is attached), while {@link IRuntimePod.uid} is the stable *pod* id.
+ * Prefer `uid` for pod identity and `id` for kernel identity.
+ */
+export interface IRuntimeModel extends IRuntimePod, Kernel.IModel {
+}
+/**
+ * A runtime pod as returned by the Datalayer control-plane.
+ *
+ * This is the canonical snake_case transport shape for a runtime pod. The
+ * Datalayer Client's `RuntimeData` (see `RuntimeDTO.ts`) is a type alias of
+ * this interface, so there is a single source of truth for the pod payload.
+ * It is the source of the pod-level fields composed into {@link IRuntimeModel}.
+ *
+ * It is distinct from {@link IRuntimeDesc}, which is the camelCase,
+ * location-agnostic UI descriptor used by pickers/launchers - do not merge the
+ * two (see `IRuntimeDesc`).
+ */
+export interface IRuntimePod {
+    /**
+     * Stable runtime pod identifier (ULID) assigned by the control-plane.
+     *
+     * Distinct from the kernel `id` carried by {@link Kernel.IModel}: a pod may
+     * exist before a kernel is attached, so prefer `uid` for pod identity.
+     */
+    uid: string;
+    /**
+     * Environment display name
+     */
+    environment_title: string;
+    /**
+     * Environment name
+     */
+    environment_name: string;
+    /**
+     * Runtime name
+     */
+    pod_name: string;
+    /**
+     * Runtime ingress URL
+     */
+    ingress: string;
+    /**
+     * Runtime user given name
+     */
+    given_name: string;
+    /**
+     * Runtime type
+     */
+    type: IRuntimeType;
+    /**
+     * Server authentication token
+     */
+    token: string;
+    /**
+     * Credits burning rate per second
+     */
+    burning_rate: number;
+    /**
+     * Kernel reservation ID
+     */
+    reservation_id?: string;
+    /**
+     * Runtime usage starting timestamp
+     */
+    started_at: string;
+    /**
+     * Runtime credits reservation expiration timestamp
+     */
+    expired_at?: string;
+}
+/**
+ * Runtime description (UI layer).
+ *
+ * A lightweight, camelCase, location-agnostic descriptor used by the runtime
+ * pickers/launchers to describe a *desired or selected* runtime across all
+ * locations (browser / local / remote). It is intentionally kept separate from
+ * {@link IRuntimePod}:
+ *  - naming: camelCase (UI) vs snake_case (backend transport);
+ *  - scope: spans all {@link IRuntimeLocation}s vs remote pod only;
+ *  - lifecycle: a selection/description (may not exist yet) vs a concrete
+ *    running pod.
+ * Map between the two at the boundary (e.g. `podName` <-> `pod_name`,
+ * `burningRate` <-> `burning_rate`) rather than merging them.
+ */
+export interface IRuntimeDesc {
+    /**
+     * Runtime ID.
+     */
+    id?: string;
+    /**
+     * Runtime Kernel ID.
+     */
+    kernelId?: string;
+    /**
+     * Runtime name.
+     */
+    name: string;
+    /**
+     * Runtime language.
+     */
+    language: string;
+    /**
+     * Runtime location.
+     */
+    location: IRuntimeLocation;
+    /**
+     * Runtime display name.
+     */
+    displayName?: string;
+    /**
+     * Runtime parameters.
+     */
+    params?: Record<string, any>;
+    /**
+     * Runtime credits burning rate.
+     */
+    burningRate?: number;
+    /**
+     * Runtime Pod name (if applicable).
+     */
+    podName?: string;
+}
+/**
+ * Runtime type.
+ *
+ * TODO refactor with type `IRuntimeLocation`
+ */
+export type IRuntimeType = 'notebook' | 'cell';
+/**
+ * Runtime optional capabilities.
+ */
+export type IRuntimeCapabilities = 'user_storage';

package/lib/models/Runtime.js

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export const BACKWARDS_COMPATIBLE_KERNEL_TYPES_MAP = {
+    // Backwards compatible mapping.
+    default: 'notebook',
+    snippet: 'cell',
+    notebook: 'notebook',
+    cell: 'cell',
+};
+/**
+ * Error thrown when a runtime has been created
+ * but it can ont be reached.
+ */
+export class RuntimeUnreachable extends Error {
+    name = 'RuntimeUnreachable';
+}

package/lib/models/RuntimeDTO.d.ts

@@ -0,0 +1,172 @@
+import type { AgentRuntimesClient as DatalayerClient } from '../client/AgentRuntimesClient';
+import { CodeSandboxSnapshotDTO } from './CodeSandboxSnapshotDTO';
+import type { IRuntimePod } from './Runtime';
+/**
+ * Represents a running instance of a computing environment.
+ *
+ * Alias of the canonical {@link IRuntimePod} (see `Runtime.ts`) so the raw
+ * snake_case pod payload is defined in a single place. Kept as a named export
+ * for the Datalayer Client's public API surface.
+ */
+export type RuntimeData = IRuntimePod;
+/**
+ * Stable public interface for Runtime data.
+ * This is the contract that Client consumers can rely on.
+ * The raw API may change, but this interface remains stable.
+ */
+export interface RuntimeJSON {
+    /** ulid for the runtime */
+    uid: string;
+    /** Kubernetes pod name for the runtime instance */
+    podName: string;
+    /** User-friendly name for the runtime */
+    givenName: string;
+    /** Name of the environment this runtime is based on */
+    environmentName: string;
+    /** Title of the environment for display */
+    environmentTitle: string;
+    /** Type of runtime - notebook, terminal, or job */
+    type: string;
+    /** Credits consumed per second */
+    burningRate: number;
+    /** Credits allocated/available to this runtime */
+    ingress: string;
+    /** Authentication token for accessing the runtime */
+    token: string;
+    /** When the runtime was started */
+    startedAt: string;
+    /** When the runtime will expire */
+    expiredAt: string;
+}
+/**
+ * Request payload for creating a new runtime
+ * @interface CreateRuntimeRequest
+ */
+export interface CreateRuntimeRequest {
+    /** Name of the environment to use */
+    environment_name: string;
+    /** Type of runtime (e.g., 'notebook', 'terminal', 'job') */
+    type?: 'notebook' | 'terminal' | 'job';
+    /** Optional given name for the runtime */
+    given_name?: string;
+    /** Maximum credits this runtime can consume */
+    credits_limit?: number;
+    /** Optional capabilities for the runtime */
+    capabilities?: string[];
+    /** Optional source to create runtime from (e.g., snapshot ID) */
+    from?: string;
+}
+/**
+ * Response from creating a new runtime
+ * @interface CreateRuntimeResponse
+ */
+export interface CreateRuntimeResponse {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Response message from the server */
+    message: string;
+    /** The created runtime instance */
+    runtime: RuntimeData;
+}
+/**
+ * Response from listing runtimes
+ * @interface ListRuntimesResponse
+ */
+export interface ListRuntimesResponse {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Response message from the server */
+    message: string;
+    /** Array of runtime instances */
+    runtimes: RuntimeData[];
+}
+/**
+ * Runtime domain model that wraps API responses with convenient methods.
+ * Provides state management and lifecycle operations for computational runtimes.
+ *
+ * @example
+ * ```typescript
+ * const runtime = await client.createRuntime({ environment_name: 'python-cpu' });
+ * await runtime.waitUntilReady();
+ * ```
+ */
+export declare class RuntimeDTO {
+    /** @internal */
+    _data: RuntimeData;
+    private _client;
+    private _deleted;
+    /**
+     * Create a Runtime instance.
+     *
+     * @param data - Runtime data from API
+     * @param client - Client instance
+     */
+    constructor(data: RuntimeData, client: DatalayerClient);
+    /**
+     * Check if this runtime has been deleted and throw error if so.
+     * @throws Error if deleted
+     */
+    private _checkDeleted;
+    /** Kubernetes pod name for the runtime instance. */
+    get podName(): string;
+    /** Unique identifier for the runtime. */
+    get uid(): string;
+    /** Name of the environment this runtime is based on. */
+    get environmentName(): string;
+    /** Ingress URL for accessing the runtime. */
+    get ingress(): string;
+    /** Authentication token for accessing the runtime. */
+    get token(): string;
+    /** Credits consumed per second. */
+    get burningRate(): number;
+    /** User-friendly name for the runtime. */
+    get givenName(): string;
+    /** Type of runtime (notebook, terminal, or job). */
+    get type(): string;
+    /** When the runtime started. */
+    get startedAt(): Date;
+    /** When the runtime will expire. */
+    get expiredAt(): Date;
+    /** Environment title for display. */
+    get environmentTitle(): string;
+    /**
+     * Delete this runtime permanently.
+     * After deletion, subsequent calls to dynamic methods will throw errors.
+     */
+    delete(): Promise<void>;
+    /**
+     * Update runtime from a snapshot.
+     *
+     * @param from - Snapshot identifier to restore from
+     * @returns Updated Runtime instance
+     */
+    update(from: string): Promise<RuntimeDTO>;
+    /**
+     * Create a snapshot of this runtime.
+     *
+     * @param name - Name for the snapshot
+     * @param description - Optional description
+     * @param stop - Whether to stop runtime after snapshotting
+     * @returns Created Snapshot instance
+     */
+    createSnapshot(name: string, description?: string, stop?: boolean): Promise<CodeSandboxSnapshotDTO>;
+    /**
+     * Get runtime data in camelCase format.
+     * Returns only the core fields that consumers need.
+     * This provides a stable interface regardless of API changes.
+     * Returns the current cached state - call getState() first if you need fresh data.
+     *
+     * @returns Core runtime data with camelCase properties
+     */
+    toJSON(): RuntimeJSON;
+    /**
+     * Get the raw runtime data exactly as received from the API.
+     * This preserves the original snake_case naming from the API response.
+     * Returns the current cached state - call getState() first if you need fresh data.
+     *
+     * @returns Raw runtime data from API
+     */
+    rawData(): RuntimeData;
+    /** String representation of the runtime. */
+    toString(): string;
+}