@datalayer/agent-runtimes 1.0.29 → 1.3.10

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

@@ -1,8 +1,4 @@
 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.
- */
 import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
 import { nullTranslator } from '@jupyterlab/translation';
 //import { kernelIcon } from '@jupyterlab/ui-components';
@@ -34,14 +30,30 @@ const RUNTIME_DISPLAY_NAME_MAX_LENGTH = 25;
  * "Assign a new Code Sandbox" and never among the ones already running.
  */
 function isRunningSandbox(desc) {
-    return !!desc.kernelId || !!desc.podName;
+    return !!desc.kernelId || !!desc.runtimeName;
 }
 /** How a sandbox is identified among the choices; see `dropdownDescs`. */
 function codeSandboxDescKey(desc) {
-    // The pod stands in for the kernel of a sandbox that has none — the ones
-    // of an external provider. Without it two Modal sandboxes of the same
-    // environment answer to one key and the list shows a single row.
-    return `${desc.location}:${desc.kernelId ?? desc.podName ?? desc.name}`;
+    // The runtime uid, then the pod, stands in for the kernel of a sandbox that
+    // does not have one yet. Without that identity all Daytona sandboxes of the
+    // same environment answer to one key.
+    return `${desc.location}:${desc.kernelId ?? desc.id ?? desc.runtimeName ?? desc.name}`;
+}
+/** The identifier shown beside a running sandbox. */
+function codeSandboxDisplayId(desc) {
+    return desc.kernelId ?? desc.id ?? desc.runtimeName;
+}
+/** Whether two descriptions refer to the same choice. */
+function isSameCodeSandbox(left, right) {
+    if (!right) {
+        return false;
+    }
+    if (left.runtimeName && right.runtimeName) {
+        return left.runtimeName === right.runtimeName;
+    }
+    const sameLocation = left.location === right.location ||
+        (isRuntimeRemote(left.location) && isRuntimeRemote(right.location));
+    return sameLocation && codeSandboxDescKey(left) === codeSandboxDescKey(right);
 }
 /**
  * The picker of a code sandbox: what runs already, and what could run.
@@ -108,10 +120,15 @@ export function CodeSandboxPicker(props) {
         descs.filter(isRunningSandbox),
     ])
         .filter(([, descs]) => descs.length > 0), [groupedRuntimeDescs]);
-    const environmentOnlyOptions = useMemo(() => dropdownOptions.filter(option => {
+    const environmentOnlyOptions = useMemo(() => dropdownOptions
+        .filter(option => {
         const desc = dropdownDescs.get(option.key);
         return !desc || !isRunningSandbox(desc);
-    }), [dropdownDescs, dropdownOptions]);
+    })
+        // The running sandboxes are the radio column beside this; the dropdown
+        // then lists only environments to start, so it needs no group heading
+        // of its own ("Assign a new Code Sandbox" already labels the control).
+        .map(option => ({ ...option, group: undefined })), [dropdownDescs, dropdownOptions]);
     const radioSections = (entries) => (_jsx(RadioGroup, { name: "kernel-options", "aria-labelledby": "kernel-options", children: entries.map(([group, runtimeDescs]) => (_jsxs(Box, { children: [_jsx(Box, { as: "h4", sx: {
                         /*
                          * The type of a form label, not of a heading.
@@ -132,22 +149,20 @@ export function CodeSandboxPicker(props) {
                         fontSize: 'var(--text-body-size-medium, 0.875rem)',
                         fontWeight: 'var(--base-text-weight-semibold, 600)',
                     }, children: group }), runtimeDescs.map(k => {
+                    const choiceKey = codeSandboxDescKey(k);
+                    const displayId = codeSandboxDisplayId(k);
                     return (
                     // A kernel identifies a runtime that already runs; an
                     // environment to start one in has none, and is named
                     // by where it runs and what it runs.
-                    _jsxs(Box, { title: k.name, children: [_jsxs(FormControl, { children: [_jsx(Radio, { value: k.kernelId, onChange: () => {
+                    _jsxs(Box, { title: k.name, children: [_jsxs(FormControl, { children: [_jsx(Radio, { value: choiceKey, onChange: () => {
                                             setRuntimeDesc(k);
-                                        }, checked: (k.location === runtimeDesc?.location ||
-                                            (isRuntimeRemote(k.location) &&
-                                                isRuntimeRemote(runtimeDesc?.location ?? 'local'))) &&
-                                            (k.kernelId ?? k.name) ===
-                                                (runtimeDesc?.kernelId ?? runtimeDesc?.name) }), _jsx(FormControl.Label, { children: _jsxs(Box, { display: "flex", sx: { alignItems: 'baseline' }, children: [_jsx(Box, { children: k.displayName }), k.kernelId && (_jsx(Text, { sx: {
+                                        }, checked: isSameCodeSandbox(k, runtimeDesc) }), _jsx(FormControl.Label, { children: _jsxs(Box, { display: "flex", sx: { alignItems: 'baseline' }, children: [_jsx(Box, { children: k.displayName }), displayId && (_jsx(Text, { sx: {
                                                         ml: 2,
                                                         fontSize: 0,
                                                         color: 'fg.muted',
-                                                        fontFamily: 'mono'
-                                                    }, title: k.kernelId, children: k.kernelId.slice(0, 8) })), k.kernelId && k.location === 'remote' && (_jsx(Box, { ml: 3, mt: 1, children: _jsx(CreditsIndicator, { kernelId: k.kernelId, serviceManager: multiServiceManager.remote }, "credits-indicator") }))] }) }), _jsx(FormControl.Caption, { children: _jsxs(LabelGroup, { sx: { marginTop: 1 }, children: [_jsx(Label, { variant: "secondary", children: k.name }), k.provider && (_jsx(Label, { variant: "accent", sx: { marginLeft: 1 }, children: codeSandboxVariantTitle(k.provider) })), _jsx(Label, { variant: "secondary", sx: { marginLeft: 1 }, children: k.location }), k.burningRate && (_jsxs(Label, { variant: "sponsors", sx: { marginLeft: 1 }, children: [k.burningRate, " credits/second"] })), k.gpu && (_jsx(Label, { variant: "success", sx: { marginLeft: 1 }, children: "GPU" }))] }) })] }), _jsx(ActionList.Divider, {})] }, `${k.location}:${k.kernelId ?? k.name}`));
+                                                        fontFamily: 'mono',
+                                                    }, title: displayId, children: displayId.slice(0, 8) })), k.kernelId && k.location === 'remote' && (_jsx(Box, { ml: 3, mt: 1, children: _jsx(CreditsIndicator, { kernelId: k.kernelId, serviceManager: multiServiceManager.remote }, "credits-indicator") }))] }) }), _jsx(FormControl.Caption, { children: _jsxs(LabelGroup, { sx: { marginTop: 1 }, children: [_jsx(Label, { variant: "secondary", children: k.name }), k.provider && (_jsx(Label, { variant: "accent", sx: { marginLeft: 1 }, children: codeSandboxVariantTitle(k.provider) })), _jsx(Label, { variant: "secondary", sx: { marginLeft: 1 }, children: k.location }), k.burningRate && (_jsxs(Label, { variant: "sponsors", sx: { marginLeft: 1 }, children: [k.burningRate, " credits/second"] })), k.gpu && (_jsx(Label, { variant: "success", sx: { marginLeft: 1 }, children: "GPU" }))] }) })] }), _jsx(ActionList.Divider, {})] }, choiceKey));
                 })] }, group))) }));
     const trans = useMemo(() => (translator ?? nullTranslator).load('jupyterlab'), [translator]);
     const [defaultSet, setDefaultSet] = useState(false);
@@ -220,17 +235,36 @@ export function CodeSandboxPicker(props) {
         }
         if (sessionContext && groupedRuntimeDescs) {
             const kernelId = sessionContext.session?.kernel?.id;
-            if (kernelId) {
+            /*
+             * An external sandbox is bound by its POD, not a kernel of this platform.
+             *
+             * Its descriptor carries the pod and — until a kernel of the platform is
+             * ever attached — an empty kernel id, and the session it binds stands on
+             * the pod as its `location`. Matching only on the kernel id therefore
+             * missed it: the picker fell back to the local kernel the notebook never
+             * ran on, opening on "Python 3" while the toolbar rightly showed the
+             * sandbox. So the current sandbox is matched on the pod as well, and the
+             * remote descriptors — which arrive late — are waited for before the
+             * choice is allowed to settle on anything else.
+             */
+            const location = sessionContext.location;
+            const remoteBound = !!location && isRuntimeRemote(location);
+            const matchesCurrent = (desc) => (!!kernelId && desc.kernelId === kernelId) ||
+                (!!desc.runtimeName && !!location && desc.runtimeName === location);
+            if (kernelId || remoteBound) {
+                if (remoteBound && !remoteModelsReady) {
+                    return;
+                }
                 let matched = false;
-                Object.entries(groupedRuntimeDescs).forEach(([group, runtimeDescs]) => {
+                Object.values(groupedRuntimeDescs).forEach(runtimeDescs => {
                     runtimeDescs.forEach(runtimeDesc => {
-                        if (runtimeDesc.kernelId === kernelId) {
+                        if (matchesCurrent(runtimeDesc)) {
                             matched = true;
                             setRuntimeDesc(runtimeDesc);
                         }
                     });
                 });
-                if (!matched) {
+                if (!matched && kernelId) {
                     if (!remoteModelsReady) {
                         return;
                     }
@@ -244,8 +278,8 @@ export function CodeSandboxPicker(props) {
                             kernelId,
                             language: spec.language,
                             displayName: sessionContext.kernelDisplayName,
-                            location: sessionContext.location ??
-                                'local',
+                            location: location ?? 'local',
+                            runtimeName: remoteBound ? location : undefined,
                         });
                     }
                 }
@@ -300,7 +334,7 @@ export function CodeSandboxPicker(props) {
      */
     const [givenName, setGivenName] = useState('');
     const givenNameFor = useRef(undefined);
-    const [userStorage, setUserStorage] = useState(false);
+    const [homeFolder, setHomeFolder] = useState(false);
     const asksForNewSandbox = withNewSandboxControls || !!onTransferChange;
     useEffect(() => {
         if (asksForNewSandbox) {
@@ -312,7 +346,12 @@ export function CodeSandboxPicker(props) {
             .get()
             .find(env => env.name === runtimeDesc?.name)?.burning_rate;
     const allowance = useNewCodeSandboxAllowance(resolvedBurningRate);
-    const isNewSandbox = !!runtimeDesc && !runtimeDesc.kernelId;
+    // New means an environment to start, not a sandbox already running. An
+    // external sandbox runs with a pod but no kernel of its own, so keying
+    // "new" on the kernel alone misread it as new — and a new remote sandbox
+    // the account cannot yet price is answered with nothing, which is why
+    // assigning an existing Daytona did nothing.
+    const isNewSandbox = !!runtimeDesc && !isRunningSandbox(runtimeDesc);
     // Offer a name for what was just picked, and leave it alone afterwards: the
     // key is the thing picked, so re-picking the same one keeps what was typed.
     const pickedKey = isNewSandbox
@@ -375,28 +414,40 @@ export function CodeSandboxPicker(props) {
                         ? `${runtimeDesc.location}-${runtimeDesc.name}`
                         : runtimeDesc.name,
                     id: runtimeDesc.kernelId,
+                    // The pod names a sandbox that has no kernel of its own — an
+                    // external one — so the session can bind it through the proxy.
+                    runtime_name: runtimeDesc.runtimeName,
                     // The name the sandbox is given, carried with the choice.
                     //
                     // Everything else about the pick travelled in this object and the
                     // name did not, so whoever created the sandbox had nothing to name
                     // it with and fell back to the kernelspec: the launcher honoured
                     // what was typed, the picker silently dropped it.
+                    //
+                    // Two readers, two fields: a sandbox of a server is named from
+                    // `displayName`, a runtime of the platform is started with
+                    // `givenName`. A new remote sandbox — a Daytona among them — read
+                    // the second, which nothing filled, and came up "Code Sandbox".
+                    // Both carry the name now: what the user typed, or the title of the
+                    // environment it runs.
                     displayName: runtimeDesc.displayName,
+                    givenName: givenName || runtimeDesc.displayName,
                     creditsLimit,
-                    capabilities: userStorage ? ['user_storage'] : undefined,
+                    capabilities: homeFolder ? ['home-folder'] : undefined,
                 }
                 : null,
             selectedVariables,
         });
     }, [
         allowance,
+        givenName,
         isNewSandbox,
         onTransferChange,
         resolvedBurningRate,
         runtimeDesc,
         selectedVariables,
         timeLimit,
-        userStorage,
+        homeFolder,
     ]);
     // For cell using submenu instead of group would be nice unfortunately the feature
     // is not yet implemented in the component there has been a not-great demo story.
@@ -410,8 +461,9 @@ export function CodeSandboxPicker(props) {
                             icon: () => (_jsx("span", { className: "dla-Cell-runtime-icon", children: _jsx(CpuIcon, {}) })), "aria-label": trans.__('Assign a Runtime to the Cell.'), title: trans.__('Assign a Runtime to the Cell.'), size: "small", variant: "invisible" }) })) : (_jsxs(ActionMenu.Button, { variant: "default", disabled: disabled || groupedRuntimeDescs === null, children: [_jsx(Text, { fontWeight: 'bold', children: trans.__('Runtime:') }), ' ' + (runtimeDesc?.displayName ?? trans.__('No Runtime'))] })), _jsx(ActionMenu.Overlay, { ...overlayProps, width: "medium", sx: { overflowY: 'auto' }, side: variant === 'cell' ? 'outside-left' : 'outside-right', children: _jsxs(ActionList, { selectionVariant: "single", children: [variant === 'cell' && (_jsxs(ActionList.Item, { selected: runtimeDesc === undefined, onSelect: () => {
                                         setRuntimeDesc(undefined);
                                     }, children: [preference?.location && (_jsx(ActionList.LeadingVisual, { children: preference.location === 'local' ? (_jsx(LaptopSimpleIcon, {})) : preference.location === 'browser' ? (_jsx(BrowserIcon, {})) : (_jsx(CloudUploadIcon, {})) })), trans.__('Assign the Notebook Runtime')] }, 'null')), !!preActions && preActions, Object.entries(groupedRuntimeDescs ?? {}).map(([group, runtimeDescs]) => (_jsxs(ActionList.Group, { children: [_jsx(ActionList.GroupHeading, { children: group }), runtimeDescs.map(candidateRuntimeDesc => {
-                                            const annotation = candidateRuntimeDesc.podName
-                                                ? ` - ${candidateRuntimeDesc.podName.split('-', 2).reverse()[0]}`
+                                            const choiceKey = codeSandboxDescKey(candidateRuntimeDesc);
+                                            const annotation = candidateRuntimeDesc.runtimeName
+                                                ? ` - ${candidateRuntimeDesc.runtimeName}`
                                                 : candidateRuntimeDesc.kernelId
                                                     ? ` - ${candidateRuntimeDesc.kernelId}`
                                                     : '';
@@ -420,16 +472,10 @@ export function CodeSandboxPicker(props) {
                                                 RUNTIME_DISPLAY_NAME_MAX_LENGTH
                                                 ? candidateRuntimeDesc.displayName.slice(0, RUNTIME_DISPLAY_NAME_MAX_LENGTH) + '…'
                                                 : (candidateRuntimeDesc.displayName ?? '');
-                                            return (_jsxs(ActionList.Item, { title: fullDisplayName, selected: (candidateRuntimeDesc.location ===
-                                                    runtimeDesc?.location ||
-                                                    (isRuntimeRemote(candidateRuntimeDesc.location) &&
-                                                        isRuntimeRemote(runtimeDesc?.location ?? 'local'))) &&
-                                                    (candidateRuntimeDesc.kernelId ??
-                                                        candidateRuntimeDesc.name) ===
-                                                        (runtimeDesc?.kernelId ?? runtimeDesc?.name), onSelect: () => {
+                                            return (_jsxs(ActionList.Item, { title: fullDisplayName, selected: isSameCodeSandbox(candidateRuntimeDesc, runtimeDesc), onSelect: () => {
                                                     setRuntimeDesc(candidateRuntimeDesc);
                                                 }, children: [_jsx(ActionList.LeadingVisual, { children: candidateRuntimeDesc.location === 'local' ? (_jsx(LaptopSimpleIcon, {})) : candidateRuntimeDesc.location === 'browser' ? (_jsx(BrowserIcon, {})) : (_jsx(CloudUploadIcon, {})) }), displayName + annotation.slice(0, 10), _jsxs(ActionList.TrailingVisual, { children: [candidateRuntimeDesc.name && (_jsx(Label, { size: "small", variant: "secondary", children: candidateRuntimeDesc.name })), ' ', candidateRuntimeDesc
-                                                                .provider && (_jsx(Label, { size: "small", variant: "accent", children: codeSandboxVariantTitle(candidateRuntimeDesc.provider) }))] })] }, candidateRuntimeDesc.name));
+                                                                .provider && (_jsx(Label, { size: "small", variant: "accent", children: codeSandboxVariantTitle(candidateRuntimeDesc.provider) }))] })] }, choiceKey));
                                         })] }, group))), !!postActions && (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), postActions] }))] }) })] })) : display === 'dropdown' ? (
             /*
              * Section for the dropdown display.
@@ -439,11 +485,12 @@ export function CodeSandboxPicker(props) {
              * nine rows of radio buttons before anything else on the dialog can
              * be read; closed, it is one line.
              */
-            _jsxs(_Fragment, { children: [defaultSet && sandboxLayout === 'separated' &&
+            _jsxs(_Fragment, { children: [defaultSet &&
+                        sandboxLayout === 'separated' &&
                         runningEntries.length > 0 &&
                         radioSections(runningEntries), defaultSet && (
                     // Room below: the controls of a new sandbox follow, and the
-                    // toggle of the user storage sat against the dropdown.
+                    // toggle of the home folder sat against the dropdown.
                     _jsxs(FormControl, { sx: { marginBottom: 4 }, children: [_jsx(FormControl.Label, { children: sandboxLayout === 'separated'
                                     ? 'Assign a new Code Sandbox'
                                     : 'Environment' }), _jsx(CodeSandboxEnvironmentSelect, { disabled: disabled, options: sandboxLayout === 'separated'
@@ -476,6 +523,6 @@ export function CodeSandboxPicker(props) {
                         // the name travels with it, rather than beside it.
                         setRuntimeDesc({ ...runtimeDesc, displayName: value });
                     }
-                }, userStorage: userStorage, onUserStorageToggle: () => setUserStorage(current => !current) })), variables.available && (_jsx(CodeSandboxVariables, { selectedVariables: variables.selected, setSelectVariable: variables.setSelected, transferVariables: variables.transfer, setTransferVariable: variables.setTransfer, kernelVariables: variables.variables, translator: translator }))] }));
+                }, homeFolder: homeFolder, onHomeFolderToggle: () => setHomeFolder(current => !current) })), variables.available && (_jsx(CodeSandboxVariables, { selectedVariables: variables.selected, setSelectVariable: variables.setSelected, transferVariables: variables.transfer, setTransferVariable: variables.setTransfer, kernelVariables: variables.variables, translator: translator }))] }));
 }
 export default CodeSandboxPicker;

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

@@ -1,3 +1,4 @@
+import type { JSX } from 'react';
 import { ISessionContext } from '@jupyterlab/apputils';
 import { CodeCellModel } from '@jupyterlab/cells';
 import type { IMarkdownParser, IRenderMime } from '@jupyterlab/rendermime';

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

@@ -1,8 +1,4 @@
 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.
- */
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { nullTranslator } from '@jupyterlab/translation';
 import { ActionList } from '@primer/react';

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

@@ -1,3 +1,4 @@
+import type { JSX } from 'react';
 /**
  * Maximal time reservable for a runtime in minutes.
  *

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

@@ -1,11 +1,7 @@
-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.
- */
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { FormControl, IconButton, Text, TextInput } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
-import { PlusIcon } from '@primer/octicons-react';
+import { CreditCardIcon } from '@primer/octicons-react';
 import { Slider } from '@datalayer/primer-addons';
 /**
  * Maximal time reservable for a runtime in minutes.
@@ -45,5 +41,7 @@ export function CodeSandboxReservationControl(props) {
                     gridTemplateColumns: 'max-content 1fr max-content max-content',
                     gridGap: 'var(--stack-gap-condensed)',
                     width: '100%',
-                }, children: [_jsx(Slider, { step: 1, min: 1, max: max, value: displayedTime, onChange: handleTimeChange, disabled: disabled, label: "", displayValue: false }), _jsx(TextInput, { type: "number", step: "1", min: "1", max: max, disabled: disabled, value: displayedTime.toFixed(2), onChange: handleTimeChange }), (max === 0 || max > Number.EPSILON) && (_jsxs(_Fragment, { children: [_jsxs(Text, { children: ["out of ", maxProps, " available minutes"] }), addCredits && (_jsx(IconButton, { icon: PlusIcon, "aria-label": "Add credits", onClick: () => addCredits() }))] }))] }), _jsxs(FormControl.Caption, { children: ["Maximum execution time that can be consumed by the runtime. It must be less than ", (MAXIMAL_CODE_SANDBOX_TIME_RESERVATION_MINUTES / 60).toFixed(0), ' ', "hours.", burningRate && (_jsxs(_Fragment, { children: [_jsx("br", {}), `With the current value, the runtime execution will consume at most ${(time * burningRate * 60).toFixed(2)} credits.`] }))] }), error && (_jsx(FormControl.Validation, { variant: "error", children: error }))] })) : (_jsx(_Fragment, {}));
+                }, children: [_jsx(Slider, { step: 1, min: 1, max: max, value: displayedTime, onChange: handleTimeChange, disabled: disabled, label: "", displayValue: false }), _jsx(TextInput, { type: "number", step: "1", min: "1", max: max, disabled: disabled, value: displayedTime.toFixed(2), onChange: handleTimeChange }), (max === 0 || max > Number.EPSILON) && (_jsxs(_Fragment, { children: [_jsx(Text, { children: max < requestedMax
+                                    ? `out of ${max} minutes`
+                                    : `out of ${max} available minutes` }), addCredits && (_jsx(IconButton, { icon: CreditCardIcon, "aria-label": "Check your Plan", variant: "invisible", onClick: () => addCredits() }))] }))] }), _jsxs(FormControl.Caption, { children: ["Maximum execution time that can be consumed by the runtime. It must be less than", ' ', (MAXIMAL_CODE_SANDBOX_TIME_RESERVATION_MINUTES / 60).toFixed(0), " hours.", burningRate && (_jsxs(_Fragment, { children: [_jsx("br", {}), `With the current value, the runtime execution will consume at most ${(time * burningRate * 60).toFixed(2)} credits.`] }))] }), error && (_jsx(FormControl.Validation, { variant: "error", children: error }))] })) : (_jsx(_Fragment, {}));
 }

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

@@ -11,6 +11,11 @@ export interface CodeSandboxTransfer {
     runtime: Partial<Omit<IRuntimeOptions, 'kernelType'> & {
         id: string;
         displayName: string;
+        /**
+         * The pod of an external sandbox (Daytona, E2B), which has no kernel of
+         * its own — the session binds it through the runtimes proxy by this.
+         */
+        runtime_name: string;
     }> | null;
     /**
      * List of selected variables

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

@@ -1,12 +1,24 @@
 import { SessionContext } from '@jupyterlab/apputils';
 import { ITranslator } from '@jupyterlab/translation';
 import { IMultiServiceManager } from '../../runtimes';
-import { IRuntimeDesc } from '../../models';
+import { IRuntimeDesc, type IDatalayerEnvironment } from '../../models';
 import { CodeSandboxVariant } from '../../models/CodeSandboxVariant';
 export type IDatalayerCodeSandboxDesc = IRuntimeDesc & {
     gpu?: string;
     /** The provider the environment belongs to — see `CodeSandboxVariant`. */
     provider?: CodeSandboxVariant;
+    /**
+     * The listing entry a NEW sandbox would be started from, carried whole.
+     *
+     * What the picker has to say about an environment — whose it is, which
+     * version it launches, the class that prices it, whether anything was built
+     * for this variant — is decided by the rules in `codeSandboxEnvironments`,
+     * and they read the entry. Copying a field at a time here is how the
+     * launcher and the picker came to disagree about the same environment
+     * (PLAN_ENV.md, E1-19). Absent on a sandbox that already runs and on a
+     * kernelspec of a server or of the browser.
+     */
+    environment?: IDatalayerEnvironment;
 };
 /**
  * Create the grouped runtime descriptions.

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

@@ -90,18 +90,23 @@ export function getGroupedCodeSandboxDescs(multiServiceManager, kernelId, transl
          * picker, which is the one place a notebook can be pointed at them.
          * What they always have is the pod that stands for them.
          */
-        .filter(k => (k.id || k.pod_name) && !listedAsSession.includes(k.id))
+        .filter(k => (k.id || k.runtime_name) && !listedAsSession.includes(k.id))
         .map(runtime => {
         const environment = multiServiceManager
             .remote.environments.get()
             .find(env => env.name === runtime.environment.name);
         return {
+            // Keep the control-plane identity as well as the Jupyter kernel
+            // identity. External sandboxes may not have a kernel until they
+            // are attached, but their runtime uid is already unique.
+            id: runtime.uid,
             // Empty for an external sandbox: it has none, and saying so is
             // what keeps the picker from trying to connect to one.
             kernelId: runtime.id || undefined,
             name: environment.name,
             language: environment.language,
-            provider: codeSandboxVariantOf(environment?.owner ?? runtime.environment?.owner),
+            provider: codeSandboxVariantOf(environment?.owner ??
+                runtime.environment?.owner),
             displayName: 
             // The name it was GIVEN first: the title of the environment is
             // what it runs, and every sandbox of that environment answers
@@ -109,7 +114,7 @@ export function getGroupedCodeSandboxDescs(multiServiceManager, kernelId, transl
             // can be told apart here.
             runtime.given_name || environment.title || environment.name,
             location: 'remote',
-            podName: runtime.pod_name,
+            runtimeName: runtime.runtime_name,
             gpu: environment.resources?.['nvidia.com/gpu'],
         };
     }))
@@ -133,7 +138,7 @@ export function getGroupedCodeSandboxDescs(multiServiceManager, kernelId, transl
     const distinctRunning = runningSessions.filter(desc => {
         // A kernel-less sandbox is named by its pod; without it every external
         // sandbox of one environment collapsed into a single entry.
-        const key = `${desc.location}:${desc.kernelId ?? desc.podName ?? desc.name}`;
+        const key = `${desc.location}:${desc.kernelId ?? desc.runtimeName ?? desc.name}`;
         if (seen.has(key)) {
             return false;
         }
@@ -187,6 +192,7 @@ export function getGroupedCodeSandboxDescs(multiServiceManager, kernelId, transl
         gpu: spec.resources?.['nvidia.com/gpu'],
         burningRate: spec.burning_rate,
         provider: codeSandboxVariantOf(spec?.owner),
+        environment: spec,
     }))
         .filter(filterKernels));
     environments.push(...Object.values(multiServiceManager.browser?.kernelspecs.specs?.kernelspecs ?? {})

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: [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" })] })), 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." })] }))] }));
+                            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;