@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/components/code-sandboxes/NewCodeSandboxControls.d.ts

@@ -1,18 +1,24 @@
-/** What the account allows for a new sandbox of a given burning rate. */
-export interface INewCodeSandboxAllowance {
-    /** Minutes the available credits pay for; undefined without a rate. */
-    maxFromCredits?: number;
-    /** The ceiling offered by the reservation control. */
-    effectiveMaxMinutes: number;
-    /** Whether a paid start is impossible: no runs left and no credits. */
-    outOfCredits: boolean;
-    hasKnownCredits: boolean;
-    hasKnownRunAllowance: boolean;
-    hasRemainingRuns: boolean;
-}
+/**
+ * What launching a NEW code sandbox asks of the user, in one place.
+ *
+ * The launcher dialog and the picker both offer to start a sandbox, and both
+ * used to carry their own copy of the same questions — how long to reserve,
+ * whether to mount the home folder — and of the same arithmetic over the
+ * credits of the account. This module is the single copy: the hook computes
+ * what the account allows, the component renders the two controls, and the
+ * helper turns a time limit into the credits reservation.
+ *
+ * @module components/code-sandboxes/NewCodeSandboxControls
+ */
+import type { JSX } from 'react';
+import { type INewCodeSandboxAllowance } from './codeSandboxAllowance';
+export type { INewCodeSandboxAllowance };
 /**
  * The credits arithmetic both the launcher and the picker ask.
  *
+ * The arithmetic itself lives in `codeSandboxAllowance`, free of React and of
+ * this module's Primer imports, so it can be read and tested on its own.
+ *
  * @param burningRate Credits per second of the chosen environment
  */
 export declare function useNewCodeSandboxAllowance(burningRate: number | undefined): INewCodeSandboxAllowance;
@@ -31,8 +37,8 @@ export interface INewCodeSandboxControlsProps {
     error?: string;
     /** Offered next to the error when credits can be added from here. */
     addCredits?: () => void;
-    userStorage: boolean;
-    onUserStorageToggle: () => void;
+    homeFolder: boolean;
+    onHomeFolderToggle: () => void;
     storageDisabled?: boolean;
     /**
      * The name the sandbox is given, when the caller asks for that question.
@@ -50,7 +56,7 @@ export interface INewCodeSandboxControlsProps {
      * this machine: it reserves no time and mounts no storage of the platform,
      * so neither question applies to it.
      */
-    withUserStorage?: boolean;
+    withHomeFolder?: boolean;
 }
 /**
  * The two questions of a new sandbox: the time reservation, and the storage.

package/lib/components/code-sandboxes/NewCodeSandboxControls.js

@@ -1,60 +1,28 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-/*
- * Copyright (c) 2025-2026 Datalayer, Inc.
- * Distributed under the terms of the Modified BSD License.
- */
-/**
- * What launching a NEW code sandbox asks of the user, in one place.
- *
- * The launcher dialog and the picker both offer to start a sandbox, and both
- * used to carry their own copy of the same questions — how long to reserve,
- * whether to mount the user storage — and of the same arithmetic over the
- * credits of the account. This module is the single copy: the hook computes
- * what the account allows, the component renders the two controls, and the
- * helper turns a time limit into the credits reservation.
- *
- * @module components/code-sandboxes/NewCodeSandboxControls
- */
-import { FormControl, IconButton, TextInput, ToggleSwitch, Tooltip, } from '@primer/react';
-import { AlertIcon } from '@primer/octicons-react';
+import { FormControl, Link, TextInput, ToggleSwitch } from '@primer/react';
+import { InfoIcon } from '@primer/octicons-react';
 import { useCoreStore, useIAMStore } from '../../state/substates';
 import { CodeSandboxReservationControl, MAXIMAL_CODE_SANDBOX_TIME_RESERVATION_MINUTES, } from './CodeSandboxReservationControl';
+import { codeSandboxAllowance, } from './codeSandboxAllowance';
 /**
  * The credits arithmetic both the launcher and the picker ask.
  *
+ * The arithmetic itself lives in `codeSandboxAllowance`, free of React and of
+ * this module's Primer imports, so it can be read and tested on its own.
+ *
  * @param burningRate Credits per second of the chosen environment
  */
 export function useNewCodeSandboxAllowance(burningRate) {
     const { credits, user } = useIAMStore();
-    const includedRuns = user?.subscription?.usage?.included_runs ??
-        user?.subscription?.included_runs;
-    const currentRuns = user?.subscription?.usage?.current_runs ??
-        user?.subscription?.current_runs ??
-        user?.subscription?.used_runs;
-    const hasKnownRunAllowance = typeof includedRuns === 'number';
-    const hasRemainingRuns = hasKnownRunAllowance &&
-        typeof currentRuns === 'number' &&
-        includedRuns > 0 &&
-        currentRuns < includedRuns;
-    const hasKnownCredits = typeof credits?.available === 'number';
-    const maxFromCredits = burningRate
-        ? Math.floor((credits?.available ?? 0) / burningRate / 60.0)
-        : undefined;
-    const effectiveMaxMinutes = hasKnownCredits && hasKnownRunAllowance && !hasRemainingRuns
-        ? Math.max(1, maxFromCredits ?? 0)
-        : Math.max(10, maxFromCredits && maxFromCredits > 0 ? maxFromCredits : 0);
-    const outOfCredits = hasKnownCredits &&
-        hasKnownRunAllowance &&
-        !hasRemainingRuns &&
-        ((credits?.available ?? 0) <= 0 || (maxFromCredits ?? 0) < Number.EPSILON);
-    return {
-        maxFromCredits,
-        effectiveMaxMinutes,
-        outOfCredits,
-        hasKnownCredits,
-        hasKnownRunAllowance,
-        hasRemainingRuns,
-    };
+    return codeSandboxAllowance({
+        available: credits?.available,
+        includedRuns: user?.subscription?.usage?.included_runs ??
+            user?.subscription?.included_runs,
+        currentRuns: user?.subscription?.usage?.current_runs ??
+            user?.subscription?.current_runs ??
+            user?.subscription?.used_runs,
+        burningRate,
+    });
 }
 /** The credits a time reservation stands for. */
 export function creditsLimitFor(timeLimitMinutes, burningRate) {
@@ -67,10 +35,19 @@ export function creditsLimitFor(timeLimitMinutes, burningRate) {
  * The storage is withheld on white-label deployments, as it always was.
  */
 export function NewCodeSandboxControls(props) {
-    const { addCredits, burningRate, withReservation = true, disabled, error, givenName, max, onGivenNameChange, onTimeChange, onUserStorageToggle, storageDisabled, timeLimit, userStorage, withUserStorage = true, } = props;
+    const { addCredits, burningRate, withReservation = true, disabled, error, givenName, max, onGivenNameChange, onTimeChange, onHomeFolderToggle, storageDisabled, timeLimit, homeFolder, withHomeFolder = true, } = props;
     const { configuration } = useCoreStore();
-    return (_jsxs(_Fragment, { children: [onGivenNameChange && (_jsxs(FormControl, { disabled: disabled, children: [_jsx(FormControl.Label, { children: "Given Name" }), _jsx(TextInput, { block: true, name: "given-name", value: givenName ?? '', onChange: event => onGivenNameChange(event.target.value) }), _jsx(FormControl.Caption, { children: "What this sandbox is called, wherever it is listed." })] })), withReservation && (_jsx(CodeSandboxReservationControl, { addCredits: addCredits, disabled: disabled, label: 'Time reservation', max: max, time: timeLimit, burningRate: burningRate, onTimeChange: onTimeChange, error: error })), withUserStorage && !configuration.whiteLabel && (_jsxs(FormControl, { disabled: storageDisabled, layout: "horizontal", children: [_jsxs(FormControl.Label, { id: "new-sandbox-user-storage-label", children: ["User storage", _jsx(Tooltip, { text: "The runtime will be slower to start.", direction: "e", style: { marginLeft: 3 }, children: _jsx(IconButton, { icon: AlertIcon, "aria-label": "", variant: "invisible" }) })] }), _jsx(ToggleSwitch, { disabled: storageDisabled, checked: userStorage, size: "small", onClick: event => {
+    return (_jsxs(_Fragment, { children: [withReservation && (_jsx(CodeSandboxReservationControl, { addCredits: addCredits, disabled: disabled, label: 'Time reservation', max: max, time: timeLimit, burningRate: burningRate, onTimeChange: onTimeChange, error: error })), withHomeFolder && !configuration.whiteLabel && (_jsxs(FormControl, { disabled: storageDisabled, layout: "horizontal", children: [_jsxs(FormControl.Label, { id: "new-sandbox-home-folder-label", children: ["Mount Home Folder", _jsxs(Link, { href: "/docs/contents/home-folder", target: "_blank", rel: "noopener noreferrer", 
+                                // The label is a <label> for the toggle; a click on the link
+                                // must open the doc, not flip the switch.
+                                onClick: event => event.stopPropagation(), muted: true, sx: {
+                                    marginLeft: 2,
+                                    fontWeight: 'normal',
+                                    display: 'inline-flex',
+                                    alignItems: 'center',
+                                    gap: 1,
+                                }, children: [_jsx(InfoIcon, { size: 14 }), "Read more on Home Content"] })] }), _jsx(ToggleSwitch, { disabled: storageDisabled, checked: homeFolder, size: "small", onClick: event => {
                             event.preventDefault();
-                            onUserStorageToggle();
-                        }, "aria-labelledby": "new-sandbox-user-storage-label" })] }))] }));
+                            onHomeFolderToggle();
+                        }, "aria-labelledby": "new-sandbox-home-folder-label" })] })), onGivenNameChange && (_jsxs(FormControl, { disabled: disabled, children: [_jsx(FormControl.Label, { children: "Given Name" }), _jsx(TextInput, { block: true, name: "given-name", value: givenName ?? '', onChange: event => onGivenNameChange(event.target.value) }), _jsx(FormControl.Caption, { children: "What this sandbox is called, wherever it is listed." })] }))] }));
 }

package/lib/components/code-sandboxes/codeSandboxAllowance.d.ts

@@ -0,0 +1,33 @@
+/**
+ * How long a new Code Sandbox may be reserved for, and whether it may start.
+ *
+ * Separated from the control that renders it so it can be read and tested as
+ * what it is: arithmetic over a balance, a plan's run allowance and the
+ * burning rate of an environment. The launcher and the picker both ask it,
+ * and must get the same answer.
+ */
+/** What the account allows for a new sandbox of a given burning rate. */
+export interface INewCodeSandboxAllowance {
+    /** Minutes the available credits pay for; undefined without a usable rate. */
+    maxFromCredits?: number;
+    /** The ceiling offered by the reservation control. */
+    effectiveMaxMinutes: number;
+    /** Whether a paid start is impossible: no runs left and no credits. */
+    outOfCredits: boolean;
+    hasKnownCredits: boolean;
+    hasKnownRunAllowance: boolean;
+    hasRemainingRuns: boolean;
+}
+/** What a reservation is offered before any credits are known. */
+export declare const DEFAULT_MINUTES_FLOOR = 10;
+export interface ICodeSandboxAllowanceInput {
+    /** Credits the account can still commit. */
+    available?: number;
+    /** Runs the plan includes, when it counts runs. */
+    includedRuns?: number;
+    /** Runs already taken from that allowance. */
+    currentRuns?: number;
+    /** Credits per second of the chosen environment. */
+    burningRate?: number;
+}
+export declare function codeSandboxAllowance({ available, includedRuns, currentRuns, burningRate, }: ICodeSandboxAllowanceInput): INewCodeSandboxAllowance;

package/lib/components/code-sandboxes/codeSandboxAllowance.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** What a reservation is offered before any credits are known. */
+export const DEFAULT_MINUTES_FLOOR = 10;
+export function codeSandboxAllowance({ available, includedRuns, currentRuns, burningRate, }) {
+    const hasKnownRunAllowance = typeof includedRuns === 'number';
+    const hasRemainingRuns = hasKnownRunAllowance &&
+        typeof currentRuns === 'number' &&
+        includedRuns > 0 &&
+        currentRuns < includedRuns;
+    /*
+     * Finite, not merely a number: `NaN` is a `number`, and reading it as a
+     * known balance is how an account holding thousands of credits was offered
+     * the ten-minute floor. Unknown is unknown, and says so.
+     */
+    const hasKnownCredits = Number.isFinite(available);
+    const maxFromCredits = burningRate && burningRate > 0 && hasKnownCredits
+        ? Math.floor((available ?? 0) / burningRate / 60.0)
+        : undefined;
+    const effectiveMaxMinutes = hasKnownCredits && hasKnownRunAllowance && !hasRemainingRuns
+        ? Math.max(1, maxFromCredits ?? 0)
+        : Math.max(DEFAULT_MINUTES_FLOOR, maxFromCredits && maxFromCredits > 0 ? maxFromCredits : 0);
+    const outOfCredits = hasKnownCredits &&
+        hasKnownRunAllowance &&
+        !hasRemainingRuns &&
+        ((available ?? 0) <= 0 || (maxFromCredits ?? 0) < Number.EPSILON);
+    return {
+        maxFromCredits,
+        effectiveMaxMinutes,
+        outOfCredits,
+        hasKnownCredits,
+        hasKnownRunAllowance,
+        hasRemainingRuns,
+    };
+}

package/lib/components/code-sandboxes/codeSandboxEnvironments.d.ts

@@ -0,0 +1,86 @@
+/**
+ * What the environment dropdown says about an environment, as rules.
+ *
+ * The listing now holds two kinds of thing: the platform's environments, which
+ * have always been there, and the environments people build (PLAN_ENV.md,
+ * E1-01). They are told apart, grouped, priced and — where a variant was never
+ * built — refused here rather than in the components, so the launcher and the
+ * picker cannot come to different conclusions about the same entry, and so the
+ * rules can be read and tested without a DOM.
+ *
+ * Nothing in this module writes a rate: the burning rate of a user environment
+ * is the rate of the size class its promoted version names, and the listing
+ * carries it (D-4, E1-19).
+ *
+ * @module components/code-sandboxes/codeSandboxEnvironments
+ */
+import type { IDatalayerEnvironment } from '../../models';
+import type { ICodeSandboxEnvironmentOption } from './CodeSandboxEnvironmentSelect';
+/**
+ * The variant a sandbox of THIS platform starts on.
+ *
+ * A user environment may be built for Modal, Daytona or E2B as well; those
+ * sandboxes are launched at their provider, not from this dropdown, so what
+ * decides whether an entry can be launched here is the Datalayer artifact.
+ */
+export declare const DATALAYER_LAUNCH_VARIANT = "datalayer";
+/** Where an entry is listed. */
+export type CodeSandboxEnvironmentGroup = 'yours' | 'organizations' | 'library' | 'platform';
+/** The heading each group reads under. */
+export declare const CODE_SANDBOX_ENVIRONMENT_GROUP_TITLES: Record<CodeSandboxEnvironmentGroup, string>;
+/**
+ * The order the groups are offered in: what is yours first, then your
+ * organizations', then the environments you found in the Library, and the
+ * platform's own catalogue last, since it is the always-there fallback.
+ */
+export declare const CODE_SANDBOX_ENVIRONMENT_GROUP_ORDER: CodeSandboxEnvironmentGroup[];
+/** Who is looking: an account uid and a handle, as the IAM store holds them. */
+export type ICodeSandboxEnvironmentViewer = {
+    uid?: string;
+    handle?: string;
+};
+/**
+ * Which group an entry belongs to.
+ *
+ * An entry that reached the picker through the public Library is a *library*
+ * entry, whoever owns it: a published environment is offered where a reader who
+ * came from its public page looks for it (D-12, E2-16). Otherwise a platform
+ * entry says so with its `origin`. A user environment is the caller's own when
+ * the account that owns it is theirs — by uid, or by the handle its name is
+ * written with, `ada/geo`, since that is all an entry carries when the uid is
+ * not at hand. Everything else a caller can see is an environment of one of
+ * their organizations: the listing only ever offers them their own accounts'
+ * (D-19).
+ */
+export declare function codeSandboxEnvironmentGroupOf(environment: Pick<IDatalayerEnvironment, 'name' | 'origin' | 'owner' | 'fromLibrary'>, viewer?: ICodeSandboxEnvironmentViewer): CodeSandboxEnvironmentGroup;
+/** The version a launch of this entry runs, when it is a version anyone pinned. */
+export declare function codeSandboxEnvironmentVersion(environment: Pick<IDatalayerEnvironment, 'origin' | 'promotedVersion'>): number | undefined;
+/** The address of a version's page (E1-21), where its builds are. */
+export declare function environmentVersionHref(uid: string, version?: number): string;
+/**
+ * Whether a sandbox of this entry can be started from here.
+ *
+ * A platform entry always can. A user environment can once a version is
+ * promoted AND that version has a Datalayer artifact: without one the Operator
+ * refuses the launch with `DL_ENV_ARTIFACT_MISSING`, so offering it would be
+ * offering a failure. A listing that does not say which variants are built —
+ * an older Runtimes — is believed rather than doubted: the entry stays
+ * offered, and the refusal, if any, comes from the platform as it did before.
+ */
+export declare function isCodeSandboxEnvironmentLaunchable(environment: Pick<IDatalayerEnvironment, 'origin' | 'promotedVersion' | 'availableVariants' | 'burning_rate'>): boolean;
+/**
+ * Where "Build for this variant" leads: the version's own page, which is where
+ * a build of it is started. Only offered for an entry that has a version to
+ * build, and only when the entry cannot be launched as it stands.
+ */
+export declare function codeSandboxEnvironmentBuildHref(environment: Pick<IDatalayerEnvironment, 'uid' | 'origin' | 'promotedVersion' | 'availableVariants'>): string | undefined;
+/** One entry as the dropdown shows it: what it is, what it costs, and whether it can run. */
+export declare function codeSandboxEnvironmentOption(environment: IDatalayerEnvironment, viewer?: ICodeSandboxEnvironmentViewer, extra?: Partial<ICodeSandboxEnvironmentOption>): ICodeSandboxEnvironmentOption;
+/**
+ * The entries of the dropdown, in the order they read: what is yours, then
+ * your organizations', then the platform's, each in the order the listing gave
+ * them.
+ */
+export declare function codeSandboxEnvironmentOptions(environments: readonly IDatalayerEnvironment[], viewer?: ICodeSandboxEnvironmentViewer, decorate?: (environment: IDatalayerEnvironment) => Partial<ICodeSandboxEnvironmentOption>): ICodeSandboxEnvironmentOption[];
+/** The first entry a launcher may open on: never one that cannot be launched. */
+export declare function firstLaunchableCodeSandboxEnvironment(environments: readonly IDatalayerEnvironment[]): IDatalayerEnvironment | undefined;

package/lib/components/code-sandboxes/codeSandboxEnvironments.js

@@ -0,0 +1,147 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The variant a sandbox of THIS platform starts on.
+ *
+ * A user environment may be built for Modal, Daytona or E2B as well; those
+ * sandboxes are launched at their provider, not from this dropdown, so what
+ * decides whether an entry can be launched here is the Datalayer artifact.
+ */
+export const DATALAYER_LAUNCH_VARIANT = 'datalayer';
+/** The heading each group reads under. */
+export const CODE_SANDBOX_ENVIRONMENT_GROUP_TITLES = {
+    yours: 'Your environments',
+    organizations: "Your organizations' environments",
+    library: 'Library',
+    platform: 'Platform environments',
+};
+/**
+ * The order the groups are offered in: what is yours first, then your
+ * organizations', then the environments you found in the Library, and the
+ * platform's own catalogue last, since it is the always-there fallback.
+ */
+export const CODE_SANDBOX_ENVIRONMENT_GROUP_ORDER = ['yours', 'organizations', 'library', 'platform'];
+/**
+ * Which group an entry belongs to.
+ *
+ * An entry that reached the picker through the public Library is a *library*
+ * entry, whoever owns it: a published environment is offered where a reader who
+ * came from its public page looks for it (D-12, E2-16). Otherwise a platform
+ * entry says so with its `origin`. A user environment is the caller's own when
+ * the account that owns it is theirs — by uid, or by the handle its name is
+ * written with, `ada/geo`, since that is all an entry carries when the uid is
+ * not at hand. Everything else a caller can see is an environment of one of
+ * their organizations: the listing only ever offers them their own accounts'
+ * (D-19).
+ */
+export function codeSandboxEnvironmentGroupOf(environment, viewer) {
+    if (environment.fromLibrary) {
+        return 'library';
+    }
+    if (environment.origin !== 'user') {
+        return 'platform';
+    }
+    const handle = viewer?.handle;
+    const mine = (!!viewer?.uid && environment.owner === viewer.uid) ||
+        (!!handle && environment.name.startsWith(`${handle}/`));
+    return mine ? 'yours' : 'organizations';
+}
+/** The version a launch of this entry runs, when it is a version anyone pinned. */
+export function codeSandboxEnvironmentVersion(environment) {
+    if (environment.origin !== 'user') {
+        return undefined;
+    }
+    return environment.promotedVersion?.version;
+}
+/** The address of a version's page (E1-21), where its builds are. */
+export function environmentVersionHref(uid, version) {
+    return version === undefined
+        ? `/environments/${uid}/versions`
+        : `/environments/${uid}/versions/${version}`;
+}
+/**
+ * Whether a sandbox of this entry can be started from here.
+ *
+ * A platform entry always can. A user environment can once a version is
+ * promoted AND that version has a Datalayer artifact: without one the Operator
+ * refuses the launch with `DL_ENV_ARTIFACT_MISSING`, so offering it would be
+ * offering a failure. A listing that does not say which variants are built —
+ * an older Runtimes — is believed rather than doubted: the entry stays
+ * offered, and the refusal, if any, comes from the platform as it did before.
+ */
+export function isCodeSandboxEnvironmentLaunchable(environment) {
+    if (environment.origin !== 'user') {
+        return true;
+    }
+    if (!environment.promotedVersion) {
+        return false;
+    }
+    const available = environment.availableVariants;
+    if (available === undefined) {
+        return true;
+    }
+    if (!available.includes(DATALAYER_LAUNCH_VARIANT)) {
+        return false;
+    }
+    /*
+     * And it has to be priceable. A launch reserves credits before anything
+     * starts, so an entry whose size class carries no rate cannot be launched
+     * from here at all — offering it would reserve nothing and be refused by the
+     * platform, which reads to the user as the sandbox failing for no reason.
+     */
+    return !!environment.burning_rate;
+}
+/**
+ * Where "Build for this variant" leads: the version's own page, which is where
+ * a build of it is started. Only offered for an entry that has a version to
+ * build, and only when the entry cannot be launched as it stands.
+ */
+export function codeSandboxEnvironmentBuildHref(environment) {
+    if (environment.origin !== 'user' || !environment.uid) {
+        return undefined;
+    }
+    const available = environment.availableVariants;
+    /*
+     * Only where a BUILD is the thing that is missing. An entry that has its
+     * artifact and cannot be launched for another reason — an unpriced size
+     * class — is not made better by building it again, and an older Runtimes,
+     * which says nothing about artifacts, is not second-guessed.
+     */
+    if (available === undefined || available.includes(DATALAYER_LAUNCH_VARIANT)) {
+        return undefined;
+    }
+    return environmentVersionHref(environment.uid, codeSandboxEnvironmentVersion(environment));
+}
+/** One entry as the dropdown shows it: what it is, what it costs, and whether it can run. */
+export function codeSandboxEnvironmentOption(environment, viewer, extra = {}) {
+    const group = codeSandboxEnvironmentGroupOf(environment, viewer);
+    const version = codeSandboxEnvironmentVersion(environment);
+    return {
+        key: environment.name,
+        title: environment.title || environment.name,
+        name: environment.name,
+        group: CODE_SANDBOX_ENVIRONMENT_GROUP_TITLES[group],
+        version: version === undefined ? undefined : `v${version}`,
+        sizeClass: environment.sizeClass || undefined,
+        burningRate: environment.burning_rate,
+        gpu: environment.resources?.['nvidia.com/gpu'],
+        disabled: !isCodeSandboxEnvironmentLaunchable(environment),
+        buildHref: codeSandboxEnvironmentBuildHref(environment),
+        ...extra,
+    };
+}
+/**
+ * The entries of the dropdown, in the order they read: what is yours, then
+ * your organizations', then the platform's, each in the order the listing gave
+ * them.
+ */
+export function codeSandboxEnvironmentOptions(environments, viewer, decorate) {
+    const options = environments.map(environment => codeSandboxEnvironmentOption(environment, viewer, decorate?.(environment) ?? {}));
+    return CODE_SANDBOX_ENVIRONMENT_GROUP_ORDER.flatMap(group => options.filter(option => option.group === CODE_SANDBOX_ENVIRONMENT_GROUP_TITLES[group]));
+}
+/** The first entry a launcher may open on: never one that cannot be launched. */
+export function firstLaunchableCodeSandboxEnvironment(environments) {
+    return environments.find(isCodeSandboxEnvironmentLaunchable);
+}

package/lib/components/code-sandboxes/codeSandboxProviders.d.ts

@@ -0,0 +1,29 @@
+import type { IMultiServiceManager } from '../../api';
+import type { IRuntimeLocation } from '../../models';
+/** A place sandboxes run, as this page knows it. */
+export type ICodeSandboxProvider = {
+    /** Identifier of the provider, which is where its sandboxes run. */
+    name: IRuntimeLocation;
+    /** What it is called, for a person. */
+    title: string;
+    /** Whether this page can reach it at all. */
+    available: boolean;
+    /** Why not, when it cannot. */
+    unavailableReason?: string;
+};
+/**
+ * Every provider this page knows, and whether it can be used.
+ *
+ * @param multiServiceManager The services of the page, which say what is
+ *   reachable: the platform when the account has it, the Jupyter Server when
+ *   the page is one, the browser when kernels run in it
+ */
+export declare function codeSandboxProviders(multiServiceManager: IMultiServiceManager | undefined): ICodeSandboxProvider[];
+/**
+ * Whether one provider can be used from this page.
+ *
+ * @param location Where the sandboxes of that provider run
+ * @param multiServiceManager The services of the page
+ */
+export declare function isCodeSandboxProviderAvailable(location: IRuntimeLocation, multiServiceManager: IMultiServiceManager | undefined): boolean;
+export default codeSandboxProviders;

package/lib/components/code-sandboxes/codeSandboxProviders.js

@@ -0,0 +1,90 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The places a code sandbox can run, and which of them this page can use.
+ *
+ * A sandbox is not one kind of thing: it is a runtime of the platform, a
+ * kernel of a Jupyter Server, a kernel of the browser — and, on the Python
+ * side, a Kaggle session, a Modal or CoreWeave container, an E2B microVM, a
+ * Daytona sandbox or a Cloudflare edge container as well. Each of those is a
+ * PROVIDER, each ships the environments it offers (the platform ships
+ * `ai-agents-env`, Kaggle a CPU and a GPU session), and each is usable only
+ * where what it needs is at hand.
+ *
+ * That last rule was written three times over — in the picker, in the
+ * launcher, in the table of the sandboxes — and drifted every time it was
+ * touched: withholding the platform inside JupyterLab took `ai-agents-env`
+ * off the list and left no way to launch a remote sandbox there at all. It is
+ * stated once here, and the three read it.
+ *
+ * The same concept lives in `code_sandboxes.providers` on the Python side,
+ * where availability is decided by secrets rather than by services. Both
+ * answer the same question — which providers can be used from here — so the
+ * CLI, the web application and JupyterLab offer the same thing.
+ *
+ * The clouds of that registry — Kaggle, Modal, Cloudflare, CoreWeave,
+ * Daytona, E2B — are deliberately absent from the list below. Nothing on this
+ * page holds their credentials, and nothing here should: the operator holds
+ * them, decides which of them an account may use, and serves what they offer
+ * as environments of the platform, each tagged with its provider through
+ * `owner`. So they reach this page under `remote`, one provider as far as the
+ * services are concerned, and `CodeSandboxVariant` is what tells them apart.
+ *
+ * @module components/code-sandboxes/codeSandboxProviders
+ */
+import { loadJupyterConfig } from '@datalayer/jupyter-react';
+/**
+ * Every provider this page knows, and whether it can be used.
+ *
+ * @param multiServiceManager The services of the page, which say what is
+ *   reachable: the platform when the account has it, the Jupyter Server when
+ *   the page is one, the browser when kernels run in it
+ */
+export function codeSandboxProviders(multiServiceManager) {
+    /*
+     * The Jupyter Server is the provider bound to WHERE the page runs.
+     *
+     * Its kernels belong to the server the page is talking to. Outside
+     * JupyterLab there is no such server — what a manager reports as "local" is
+     * somebody else's — so offering them promises what cannot be reached.
+     */
+    const insideJupyterLab = loadJupyterConfig().insideJupyterLab;
+    return [
+        {
+            name: 'remote',
+            title: 'Datalayer',
+            available: Boolean(multiServiceManager?.remote),
+            unavailableReason: multiServiceManager?.remote
+                ? undefined
+                : 'Sign in to Datalayer to launch a sandbox on the platform.',
+        },
+        {
+            name: 'local',
+            title: 'Jupyter Server',
+            available: insideJupyterLab && Boolean(multiServiceManager?.local),
+            unavailableReason: insideJupyterLab
+                ? undefined
+                : 'The kernels of a Jupyter Server are offered inside JupyterLab.',
+        },
+        {
+            name: 'browser',
+            title: 'Browser',
+            available: Boolean(multiServiceManager?.browser),
+            unavailableReason: multiServiceManager?.browser
+                ? undefined
+                : 'No kernel runs in this browser.',
+        },
+    ];
+}
+/**
+ * Whether one provider can be used from this page.
+ *
+ * @param location Where the sandboxes of that provider run
+ * @param multiServiceManager The services of the page
+ */
+export function isCodeSandboxProviderAvailable(location, multiServiceManager) {
+    return Boolean(codeSandboxProviders(multiServiceManager).find(provider => provider.name === location)?.available);
+}
+export default codeSandboxProviders;

package/lib/components/code-sandboxes/index.d.ts

@@ -11,12 +11,15 @@
  */
 export * from './CodeSandboxCellVariables';
 export * from './CodeSandboxCellVariablesDialog';
+export * from './codeSandboxEnvironments';
+export * from './CodeSandboxEnvironmentSelect';
 export * from './CodeSandboxLauncher';
 export * from './CodeSandboxPicker';
 export * from './CodeSandboxPickerCell';
 export * from './CodeSandboxReservationControl';
 export * from './CodeSandboxTransfer';
 export * from './CodeSandboxNames';
+export * from './codeSandboxProviders';
 export * from './CodeSandboxUtils';
 export * from './CodeSandboxVariables';
 export * from './NewCodeSandboxControls';

package/lib/components/code-sandboxes/index.js

@@ -15,12 +15,15 @@
  */
 export * from './CodeSandboxCellVariables';
 export * from './CodeSandboxCellVariablesDialog';
+export * from './codeSandboxEnvironments';
+export * from './CodeSandboxEnvironmentSelect';
 export * from './CodeSandboxLauncher';
 export * from './CodeSandboxPicker';
 export * from './CodeSandboxPickerCell';
 export * from './CodeSandboxReservationControl';
 export * from './CodeSandboxTransfer';
 export * from './CodeSandboxNames';
+export * from './codeSandboxProviders';
 export * from './CodeSandboxUtils';
 export * from './CodeSandboxVariables';
 export * from './NewCodeSandboxControls';

package/lib/components/context/SpaceSelect.d.ts

@@ -1,2 +1,2 @@
-export declare const SpaceSelect: () => import("react/jsx-runtime").JSX.Element;
+export declare const SpaceSelect: () => import("react").JSX.Element;
 export default SpaceSelect;

package/lib/components/flashes/FlashDisclaimer.d.ts

@@ -1,2 +1,2 @@
-export declare const FlashDisclaimer: () => import("react/jsx-runtime").JSX.Element;
+export declare const FlashDisclaimer: () => import("react").JSX.Element;
 export default FlashDisclaimer;

package/lib/components/icons/ArtifactIcon.d.ts

@@ -1,3 +1,4 @@
+import type { JSX } from 'react';
 import { Icon } from '@primer/octicons-react';
 import { IAnyItem, IItemType } from '../../models';
 type IArtifactIconClassProp = {

package/lib/components/nbgrader/NbGradesDetails.d.ts

@@ -1,5 +1,5 @@
 import { IStudentItem } from '../../models';
 export declare const NbGradesDetails: (props: {
     studentItem?: IStudentItem;
-}) => import("react/jsx-runtime").JSX.Element;
+}) => import("react").JSX.Element;
 export default NbGradesDetails;

package/lib/components/progress/CreditsIndicator.d.ts

@@ -1,3 +1,4 @@
+import type { JSX } from 'react';
 import type { IRemoteServicesManager } from '../../runtimes';
 type ICreditsIndicatorProps = {
     /**