@datalayer/agent-runtimes 1.0.25 → 1.0.28

package/lib/components/agents/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * What an agent shows of itself.
+ *
+ * @module components/agents
+ */
+export * from './AgentSummary';

package/lib/components/{students → agents}/index.js

@@ -2,4 +2,9 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-export * from './StudentItemStatus';
+/**
+ * What an agent shows of itself.
+ *
+ * @module components/agents
+ */
+export * from './AgentSummary';

package/lib/components/{NotificationEventCard.js → cards/NotificationEventCard.js}

@@ -9,7 +9,7 @@ import { Box } from '@datalayer/primer-addons';
 import { ChevronDownIcon, DownloadIcon, EyeClosedIcon, EyeIcon, TrashIcon, } from '@primer/octicons-react';
 import { createMarkdownDownloadPayload, downloadTextPayload, formatDurationMs, formatRelativeTime, } from '@datalayer/core/lib/utils';
 import { Streamdown } from 'streamdown';
-import { streamdownMarkdownStyles } from '../chat/styles/streamdownStyles';
+import { streamdownMarkdownStyles } from '../../chat/styles/streamdownStyles';
 const EVENT_KIND_VARIANT = {
     'agent-start-requested': 'attention',
     'agent-assigned': 'accent',

package/lib/components/{OutputCard.js → cards/OutputCard.js}

@@ -9,7 +9,7 @@ import { Box } from '@datalayer/primer-addons';
 import { ChevronDownIcon, DownloadIcon, EyeClosedIcon, EyeIcon, TrashIcon, } from '@primer/octicons-react';
 import { createMarkdownDownloadPayload, downloadTextPayload, formatDurationMs, formatRelativeTime, } from '@datalayer/core/lib/utils';
 import { Streamdown } from 'streamdown';
-import { streamdownMarkdownStyles } from '../chat/styles/streamdownStyles';
+import { streamdownMarkdownStyles } from '../../chat/styles/streamdownStyles';
 export function OutputCard({ event, onToggleRead, onDelete, onOpenAgent, }) {
     const [isOutputExpanded, setIsOutputExpanded] = useState(false);
     const outputText = event.kind === 'agent-output' && event.payload?.outputs

package/lib/components/cards/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The cards an agent run is read through: the notifications it emitted, the
+ * outputs it produced, and the tool calls waiting for an approval.
+ *
+ * @module components/cards
+ */
+export * from './NotificationEventCard';
+export * from './OutputCard';
+export * from './ToolApprovalCard';

package/lib/components/cards/index.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The cards an agent run is read through: the notifications it emitted, the
+ * outputs it produced, and the tool calls waiting for an approval.
+ *
+ * @module components/cards
+ */
+export * from './NotificationEventCard';
+export * from './OutputCard';
+export * from './ToolApprovalCard';

package/lib/components/{runtimes/RuntimeCellVariables.d.ts → code-sandboxes/CodeSandboxCellVariables.d.ts}

@@ -1,6 +1,6 @@
 import { ITranslator } from '@jupyterlab/translation';
 /**
- * {@link RuntimeCellVariables} properties
+ * {@link CodeSandboxCellVariables} properties
  */
 interface IRuntimeCellVariablesProps {
     /**
@@ -35,5 +35,5 @@ interface IRuntimeCellVariablesProps {
 /**
  * Runtime Cell Variables Picker.
  */
-export declare function RuntimeCellVariables(props: IRuntimeCellVariablesProps): JSX.Element;
-export default RuntimeCellVariables;
+export declare function CodeSandboxCellVariables(props: IRuntimeCellVariablesProps): JSX.Element;
+export default CodeSandboxCellVariables;

package/lib/components/{runtimes/RuntimeCellVariables.js → code-sandboxes/CodeSandboxCellVariables.js}

@@ -11,7 +11,7 @@ import { Box } from '@datalayer/primer-addons';
 /**
  * Runtime Cell Variables Picker.
  */
-export function RuntimeCellVariables(props) {
+export function CodeSandboxCellVariables(props) {
     const { getInputOptions, getOutputOptions, inputs, output, setInputs, setOutput, translator, } = props;
     const trans = useMemo(() => (translator ?? nullTranslator).load('jupyterlab'), [translator]);
     const inputForOutputRef = useRef(null);
@@ -169,4 +169,4 @@ export function RuntimeCellVariables(props) {
                                         .filter(item => item.selected)
                                         .map(item => item.id), onSelectedChange: onSelectedInputsChange, "aria-labelledby": "cell-input-variables", selectionVariant: "multiple", emptyStateText: trans.__('No available variables.'), loading: inputLoading }) })] })] }), _jsxs(FormControl, { children: [_jsx(FormControl.Label, { id: "cell-output-variables", children: trans.__('Output') }), _jsxs(Autocomplete, { children: [_jsx(Autocomplete.Input, { ref: inputForOutputRef, value: output, onChange: onOutputChange }), _jsx(Autocomplete.Overlay, { children: _jsx(Autocomplete.Menu, { items: outputsState ?? [], selectedItemIds: output ? [output] : [], "aria-labelledby": "cell-output-variables", loading: getOutputOptions && !outputsState, emptyStateText: trans.__('Not among the available variables.'), onOpenChange: handleOutputMenuOpenChange }) })] })] })] }));
 }
-export default RuntimeCellVariables;
+export default CodeSandboxCellVariables;

package/lib/components/{runtimes/RuntimeCellVariablesDialog.d.ts → code-sandboxes/CodeSandboxCellVariablesDialog.d.ts}

@@ -2,9 +2,9 @@ import { ISessionContext } from '@jupyterlab/apputils';
 import { CodeCellModel } from '@jupyterlab/cells';
 import { ITranslator } from '@jupyterlab/translation';
 /**
- * {@link RuntimeCellVariablesDialog} properties
+ * {@link CodeSandboxCellVariablesDialog} properties
  */
-export interface IRuntimeCellVariablesDialogProps {
+export interface ICodeSandboxCellVariablesDialogProps {
     /**
      * Code cell model
      */
@@ -33,5 +33,5 @@ export interface IRuntimeCellVariablesDialogProps {
 /**
  * Dialog to define the runtime cell variables to transfer
  */
-export declare function RuntimeCellVariablesDialog(props: IRuntimeCellVariablesDialogProps): JSX.Element;
-export default RuntimeCellVariablesDialog;
+export declare function CodeSandboxCellVariablesDialog(props: ICodeSandboxCellVariablesDialogProps): JSX.Element;
+export default CodeSandboxCellVariablesDialog;

package/lib/components/{runtimes/RuntimeCellVariablesDialog.js → code-sandboxes/CodeSandboxCellVariablesDialog.js}

@@ -9,11 +9,11 @@ import { nullTranslator } from '@jupyterlab/translation';
 import { JSONExt } from '@lumino/coreutils';
 import { KernelExecutor } from '@datalayer/jupyter-react';
 import { RuntimeSnippetsFacade } from '../../jupyter';
-import { RuntimeCellVariables } from './RuntimeCellVariables';
+import { CodeSandboxCellVariables } from './CodeSandboxCellVariables';
 /**
  * Dialog to define the runtime cell variables to transfer
  */
-export function RuntimeCellVariablesDialog(props) {
+export function CodeSandboxCellVariablesDialog(props) {
     const { onClose, model, preference, sessionContext, translator } = props;
     const [inputs, setInputs] = useState([]);
     const [output, setOutput] = useState();
@@ -96,6 +96,6 @@ export function RuntimeCellVariablesDialog(props) {
                 onClick: setVariables,
                 autoFocus: true,
             },
-        ], children: _jsx(RuntimeCellVariables, { inputs: inputs, getInputOptions: sessionContext ? getInputCandidates : undefined, setInputs: setInputs, output: output ?? undefined, getOutputOptions: getOutputCandidates, setOutput: setOutput, translator: translator }) }));
+        ], children: _jsx(CodeSandboxCellVariables, { inputs: inputs, getInputOptions: sessionContext ? getInputCandidates : undefined, setInputs: setInputs, output: output ?? undefined, getOutputOptions: getOutputCandidates, setOutput: setOutput, translator: translator }) }));
 }
-export default RuntimeCellVariablesDialog;
+export default CodeSandboxCellVariablesDialog;

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

@@ -55,5 +55,3 @@ export interface ICodeSandboxLauncherProps {
  * The launcher of a new code sandbox.
  */
 export declare function CodeSandboxLauncher(props: ICodeSandboxLauncherProps): JSX.Element;
-export declare const RuntimeLauncherDialog: typeof CodeSandboxLauncher;
-export type IRuntimeLauncherDialogProps = ICodeSandboxLauncherProps;

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

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /*
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
@@ -12,7 +12,8 @@ import { useJupyterReactStore } from '@datalayer/jupyter-react';
 import { USAGE_ROUTE } from '@datalayer/core/lib/routes';
 import { useNavigate } from '@datalayer/core/lib/hooks';
 import { NO_RUNTIME_AVAILABLE_LABEL } from '@datalayer/core/lib/i18n';
-import { iamStore, useCoreStore, useIAMStore } from '../../state/substates';
+import { getCodeSandboxGivenName, listCodeSandboxGivenNames, nextCodeSandboxGivenName, setCodeSandboxGivenName, } from './CodeSandboxNames';
+import { iamStore, runtimesStore, useCoreStore, useIAMStore, } from '../../state/substates';
 import { createNotebook, sleep } from '@datalayer/core/lib/utils';
 import { Markdown } from '@datalayer/core/lib/components/display';
 import { Timer } from '@datalayer/core/lib/components/progress';
@@ -46,6 +47,30 @@ export function CodeSandboxLauncher(props) {
     const shouldStartRuntime = startRuntime !== 'defer';
     const user = iamStore.getState().user;
     const environments = manager.environments.get();
+    /*
+     * The sandboxes of this Jupyter Server, offered beside those of the platform.
+     *
+     * Inside JupyterLab a sandbox can be a kernel of the server, and the picker
+     * has always offered both — the launcher offered only the environments of
+     * the platform, so "Launch a Code Sandbox" could not launch the very kind
+     * that costs nothing and starts at once. The value of a local choice is
+     * prefixed, since a kernelspec and an environment are free to share a name.
+     */
+    const localSpecs = useMemo(() => {
+        const specs = runtimesStore.getState().multiServiceManager?.local?.kernelspecs.specs
+            ?.kernelspecs ?? {};
+        return Object.values(specs)
+            .filter(Boolean)
+            .map(spec => ({
+            name: spec.name,
+            title: spec.display_name,
+            language: spec.language,
+        }));
+    }, []);
+    const LOCAL_PREFIX = 'local:';
+    const localSpecOf = (value) => value.startsWith(LOCAL_PREFIX)
+        ? localSpecs.find(spec => spec.name === value.slice(LOCAL_PREFIX.length))
+        : undefined;
     const { configuration } = useCoreStore();
     const { refreshCredits } = useIAMStore();
     let navigate;
@@ -61,7 +86,24 @@ export function CodeSandboxLauncher(props) {
     const jupyterLabAdapter = jupyterReactStore.jupyterLabAdapter;
     const [selection, setSelection] = useState((kernelSnapshot?.environment || environments[0]?.name) ?? '');
     const [timeLimit, setTimeLimit] = useState(10);
-    const [runtimeName, setRuntimeName] = useState(environments[0]?.runtime?.givenNameTemplate || environments[0]?.title || '');
+    /*
+     * The name the sandbox is given, and what is offered for it.
+     *
+     * The environment says what to call one of its sandboxes; the sandboxes that
+     * already run say which of those names are taken — a second sandbox of an
+     * environment is offered that name numbered, exactly as an unnamed one is
+     * given one. Both go through `nextCodeSandboxGivenName`, so what is proposed
+     * here and what is assigned elsewhere never drift apart.
+     */
+    const takenGivenNames = useCallback(() => [
+        ...manager.runtimesManager
+            .get()
+            .map(runtime => runtime.given_name)
+            .filter(Boolean),
+        ...listCodeSandboxGivenNames(),
+    ], [manager]);
+    const givenNameFor = useCallback((spec) => nextCodeSandboxGivenName(spec?.runtime?.givenNameTemplate || spec?.title || '', takenGivenNames()), [takenGivenNames]);
+    const [runtimeName, setRuntimeName] = useState(() => givenNameFor(environments[0]));
     // Whether the runtim name has been changed by the user or not
     const [hasCustomRuntimeName, setHasCustomRuntimeName] = useState(false);
     const [userStorage, setUserStorage] = useState(false);
@@ -75,6 +117,7 @@ export function CodeSandboxLauncher(props) {
             refreshCredits();
         }
     }, [shouldStartRuntime]);
+    const isLocalSelection = selection.startsWith(LOCAL_PREFIX);
     const spec = useMemo(() => environments.find(spec => spec.name === selection), [environments, selection]);
     const description = spec?.description ?? '';
     const burningRate = spec?.burning_rate ?? 1;
@@ -86,11 +129,49 @@ export function CodeSandboxLauncher(props) {
         const selection = e.target.value;
         setSelection(selection);
         if (!hasCustomRuntimeName) {
-            const spec = environments.find(env => env.name === selection);
-            setRuntimeName(spec?.runtime?.givenNameTemplate || spec?.title || '');
+            const local = localSpecOf(selection);
+            setRuntimeName(givenNameFor(local ?? environments.find(env => env.name === selection)));
         }
-    }, [setSelection, hasCustomRuntimeName]);
+    }, [environments, givenNameFor, setSelection, hasCustomRuntimeName]);
     const handleSubmitRuntime = useCallback(async () => {
+        const localSpec = localSpecOf(selection);
+        if (localSpec) {
+            /*
+             * A sandbox of this Jupyter Server: started here, named here.
+             *
+             * Nothing to reserve, no credits to weigh, no pod to wait for — the
+             * kernel is started and the choice is handed back as any other, with
+             * the name the user gave it, which is the local answer to `given_name`.
+             */
+            setError(undefined);
+            const kernels = runtimesStore.getState().multiServiceManager?.local?.kernels;
+            if (!kernels) {
+                setError(_jsx(_Fragment, { children: "The Jupyter Server of this page is not reachable." }));
+                return;
+            }
+            setWaitingForRuntime(true);
+            try {
+                const connection = await kernels.startNew({ name: localSpec.name });
+                setCodeSandboxGivenName(connection.id, runtimeName);
+                onSubmit({
+                    kernelId: connection.id,
+                    name: localSpec.name,
+                    language: localSpec.language ?? '',
+                    location: 'local',
+                    displayName: getCodeSandboxGivenName(connection.id) ?? localSpec.title,
+                });
+            }
+            catch (reason) {
+                console.warn('Failed to start a code sandbox of this server.', reason);
+                setError(_jsx(_Fragment, { children: "The code sandbox could not be started." }));
+            }
+            finally {
+                if (isMounted()) {
+                    setWaitingForRuntime(false);
+                }
+            }
+            return;
+        }
         if (selection) {
             setError(undefined);
             setWaitingForRuntime(shouldStartRuntime);
@@ -195,6 +276,8 @@ export function CodeSandboxLauncher(props) {
                 onSubmit(desc);
             }
         }
+        // `localSpecOf` closes over `localSpecs`, which is built once.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [
         manager,
         selection,
@@ -251,7 +334,7 @@ export function CodeSandboxLauncher(props) {
                     event.preventDefault();
                     handleSubmitRuntime();
                 }
-            }, children: [_jsxs(FormControl, { disabled: !!kernelSnapshot?.environment || environments.length === 0, children: [_jsx(FormControl.Label, { children: "Environment" }), _jsx(Select, { name: "environment", disabled: !!kernelSnapshot?.environment || environments.length === 0, value: selection, onChange: handleSelectionChange, block: true, children: environments.map(spec => (_jsxs(Select.Option, { value: spec.name, children: [spec.name, spec.title && (_jsxs(_Fragment, { children: [' - ', spec.title] }))] }, spec.name))) }), _jsx(FormControl.Caption, { children: _jsx(_Fragment, { children: markdownParser ? (_jsx(Box, { sx: { img: { maxWidth: '100%' } }, children: _jsx(Markdown, { text: description, markdownParser: markdownParser, sanitizer: sanitizer }) })) : sanitizer ? (
+            }, children: [_jsxs(FormControl, { disabled: !!kernelSnapshot?.environment || environments.length === 0, children: [_jsx(FormControl.Label, { children: "Environment" }), _jsxs(Select, { name: "environment", disabled: !!kernelSnapshot?.environment || environments.length === 0, value: selection, onChange: handleSelectionChange, block: true, children: [environments.map(spec => (_jsxs(Select.Option, { value: spec.name, children: [spec.name, spec.title && (_jsxs(_Fragment, { children: [' - ', spec.title] }))] }, spec.name))), localSpecs.map(spec => (_jsxs(Select.Option, { value: `${LOCAL_PREFIX}${spec.name}`, children: [spec.name, spec.title && _jsx(_Fragment, { children: ` - ${spec.title}` }), ' - Jupyter Server'] }, `${LOCAL_PREFIX}${spec.name}`)))] }), _jsx(FormControl.Caption, { children: _jsx(_Fragment, { children: markdownParser ? (_jsx(Box, { sx: { img: { maxWidth: '100%' } }, children: _jsx(Markdown, { text: description, markdownParser: markdownParser, sanitizer: sanitizer }) })) : sanitizer ? (
                                 // The description of an environment carries markup. With no
                                 // parser to render it, the sanitizer of the application is
                                 // enough to show it as what it is rather than as its tags.
@@ -260,13 +343,17 @@ export function CodeSandboxLauncher(props) {
                                     } })) : (
                                 // Neither a parser nor a sanitizer: the text of the markup,
                                 // which is still better than the markup itself.
-                                asPlainText(description)) }) })] }), _jsx(NewCodeSandboxControls, { withReservation: !!startRuntime, burningRate: burningRate, timeLimit: timeLimit, onTimeChange: setTimeLimit, max: effectiveMaxMinutes, disabled: outOfCredits, error: outOfCredits ? 'You must add credits to your account.' : undefined, addCredits: navigate
+                                asPlainText(description)) }) })] }), _jsx(NewCodeSandboxControls
+                // A sandbox of this server costs nothing and starts at once: it has
+                // no time to reserve and no storage of the platform to mount.
+                , { 
+                    // A sandbox of this server costs nothing and starts at once: it has
+                    // no time to reserve and no storage of the platform to mount.
+                    withReservation: !!startRuntime && !isLocalSelection, withUserStorage: !isLocalSelection, burningRate: burningRate, timeLimit: timeLimit, onTimeChange: setTimeLimit, max: effectiveMaxMinutes, disabled: outOfCredits, error: outOfCredits ? 'You must add credits to your account.' : undefined, addCredits: navigate
                         ? () => {
                             navigate(USAGE_ROUTE);
                         }
-                        : undefined, userStorage: userStorage, onUserStorageToggle: () => setUserStorage(current => !current) }), _jsxs(FormControl, { sx: { paddingTop: '10px' }, children: [_jsx(FormControl.Label, { children: "Runtime name" }), _jsx(TextInput, { name: "name", value: runtimeName, onChange: handleKernelNameChange, block: true })] }), hasExample &&
+                        : undefined, userStorage: userStorage, onUserStorageToggle: () => setUserStorage(current => !current) }), _jsxs(FormControl, { sx: { paddingTop: '10px' }, children: [_jsx(FormControl.Label, { children: "Given Name" }), _jsx(TextInput, { name: "name", value: runtimeName, onChange: handleKernelNameChange, block: true })] }), hasExample &&
                     jupyterLabAdapter?.jupyterLab &&
                     !configuration.whiteLabel && (_jsxs(FormControl, { sx: { paddingTop: '10px' }, children: [_jsx(FormControl.Label, { id: "open-example-label", children: "Open example notebook" }), _jsx(ToggleSwitch, { disabled: !environments.find(spec => spec.name === selection)?.example, checked: openExample, size: "small", onClick: handleSwitchClick, "aria-labelledby": "open-example-label" })] })), error && (_jsx(FlashClosable, { variant: flashLevel, actions: navigate && upgradeSubscription && flashLevel === 'warning' ? (_jsx(Button, { onClick: handleUpgrade, title: 'Upgrade your subscription.', children: "Upgrade" })) : undefined, children: error }))] }) }));
 }
-// Backward-compatible aliases (deprecated: use CodeSandboxLauncher).
-export const RuntimeLauncherDialog = CodeSandboxLauncher;

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

@@ -0,0 +1,47 @@
+/**
+ * The given name of a sandbox, when it has one.
+ *
+ * @param kernelId Kernel of the sandbox
+ */
+export declare function getCodeSandboxGivenName(kernelId?: string): string | undefined;
+/**
+ * Name a sandbox, or rename it.
+ *
+ * @param kernelId Kernel of the sandbox
+ * @param givenName What to call it; empty forgets the name
+ */
+export declare function setCodeSandboxGivenName(kernelId: string, givenName: string): void;
+/**
+ * Drop the names of the sandboxes that are no longer running.
+ *
+ * @param runningKernelIds The kernels that are still there
+ */
+export declare function pruneCodeSandboxGivenNames(runningKernelIds: Iterable<string>): void;
+/**
+ * Every given name in use by a sandbox of a server or of the browser.
+ */
+export declare function listCodeSandboxGivenNames(): string[];
+/**
+ * The next free name built on a base, numbered when the base is taken.
+ *
+ * "Python 3 (ipykernel)", then "Python 3 (ipykernel) 2", then 3 — one rule for
+ * the name a sandbox is given on first sight and for the name the launcher
+ * offers, so what the launcher proposes is what an unnamed one would get.
+ *
+ * @param base What to call it, before any numbering
+ * @param taken The names already in use
+ */
+export declare function nextCodeSandboxGivenName(base: string, taken: Iterable<string>): string;
+/**
+ * The given name of a sandbox, giving it one when it has none.
+ *
+ * The name of what it runs, and a number when a sandbox of that kind is
+ * already named — the way two runtimes of one environment are told apart.
+ * Assigned once and kept: a name that changed with what else is running would
+ * be no name at all.
+ *
+ * @param kernelId Kernel of the sandbox
+ * @param specDisplayName What the kernelspec of the sandbox is called
+ */
+export declare function ensureCodeSandboxGivenName(kernelId: string, specDisplayName: string): string;
+export default ensureCodeSandboxGivenName;

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

@@ -0,0 +1,166 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The given name of a code sandbox of a Jupyter Server or of the browser.
+ *
+ * A sandbox of the platform is named when it is launched — `given_name`, the
+ * field the launcher fills from the template of its environment — and it
+ * carries that name everywhere it is listed. A kernel of a Jupyter Server has
+ * no such field: the API gives its identifier and its kernelspec, and nothing
+ * that is the name of THIS sandbox. `python3` is what it runs, and reads the
+ * same on every one of them.
+ *
+ * The name was taken from the session instead, and that was the wrong place:
+ * a session is a standard Jupyter session, it ties a kernel to a document, it
+ * comes and goes as documents open and close, and several can name one kernel.
+ * A sandbox then wore the name of a document, changed name when another
+ * document took it, and kept the name of a document that had been closed.
+ *
+ * The given name is held here, by kernel, and given on first sight — from the
+ * kernelspec, which is what the launcher does for a runtime of the platform.
+ * It is kept in the browser: the kernels of a server outlive the page that
+ * lists them, so the name has to outlive it too, and the server has nowhere to
+ * put it.
+ *
+ * @module components/code-sandboxes/CodeSandboxNames
+ */
+/** Where the names are kept, and under which key. */
+const STORAGE_KEY = 'datalayer:code-sandbox-names';
+/** The names, by kernel identifier, as they were last written. */
+let names;
+function load() {
+    if (names) {
+        return names;
+    }
+    try {
+        const raw = globalThis.localStorage?.getItem(STORAGE_KEY);
+        names = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        // A browser that refuses its storage keeps the names for this page only.
+        names = {};
+    }
+    return names;
+}
+function save() {
+    try {
+        globalThis.localStorage?.setItem(STORAGE_KEY, JSON.stringify(load()));
+    }
+    catch {
+        /* the names stay in memory */
+    }
+}
+/**
+ * The given name of a sandbox, when it has one.
+ *
+ * @param kernelId Kernel of the sandbox
+ */
+export function getCodeSandboxGivenName(kernelId) {
+    return kernelId ? load()[kernelId] : undefined;
+}
+/**
+ * Name a sandbox, or rename it.
+ *
+ * @param kernelId Kernel of the sandbox
+ * @param givenName What to call it; empty forgets the name
+ */
+export function setCodeSandboxGivenName(kernelId, givenName) {
+    const stored = load();
+    if (givenName) {
+        stored[kernelId] = asGivenName(givenName);
+    }
+    else {
+        delete stored[kernelId];
+    }
+    save();
+}
+/**
+ * Drop the names of the sandboxes that are no longer running.
+ *
+ * @param runningKernelIds The kernels that are still there
+ */
+export function pruneCodeSandboxGivenNames(runningKernelIds) {
+    const alive = new Set(runningKernelIds);
+    const stored = load();
+    let dropped = false;
+    Object.keys(stored).forEach(kernelId => {
+        if (!alive.has(kernelId)) {
+            delete stored[kernelId];
+            dropped = true;
+        }
+    });
+    if (dropped) {
+        save();
+    }
+}
+/**
+ * A name a sandbox can wear, out of whatever it was built from.
+ *
+ * A kernelspec is free to call itself with a picture — a laptop, a snake —
+ * and some do. A glyph makes a poor name: it says nothing about WHICH sandbox
+ * this is, it reads as a broken character in the fonts of the toolbar, and it
+ * is not what anyone would type. Pictures and their variation selectors are
+ * dropped, and a name left with nothing is replaced rather than shown empty.
+ */
+function asGivenName(base) {
+    const stripped = (base ?? '')
+        // Pictographs, their skin tones, their joiners and their selectors.
+        .replace(/[\u{1F000}-\u{1FAFF}\u{2190}-\u{2BFF}\u{FE00}-\u{FE0F}\u{200D}]/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return stripped || 'Code Sandbox';
+}
+/**
+ * Every given name in use by a sandbox of a server or of the browser.
+ */
+export function listCodeSandboxGivenNames() {
+    return Object.values(load());
+}
+/**
+ * The next free name built on a base, numbered when the base is taken.
+ *
+ * "Python 3 (ipykernel)", then "Python 3 (ipykernel) 2", then 3 — one rule for
+ * the name a sandbox is given on first sight and for the name the launcher
+ * offers, so what the launcher proposes is what an unnamed one would get.
+ *
+ * @param base What to call it, before any numbering
+ * @param taken The names already in use
+ */
+export function nextCodeSandboxGivenName(base, taken) {
+    const used = new Set(taken);
+    const stem = asGivenName(base);
+    let candidate = stem;
+    let ordinal = 1;
+    while (used.has(candidate)) {
+        ordinal += 1;
+        candidate = `${stem} ${ordinal}`;
+    }
+    return candidate;
+}
+/**
+ * The given name of a sandbox, giving it one when it has none.
+ *
+ * The name of what it runs, and a number when a sandbox of that kind is
+ * already named — the way two runtimes of one environment are told apart.
+ * Assigned once and kept: a name that changed with what else is running would
+ * be no name at all.
+ *
+ * @param kernelId Kernel of the sandbox
+ * @param specDisplayName What the kernelspec of the sandbox is called
+ */
+export function ensureCodeSandboxGivenName(kernelId, specDisplayName) {
+    const existing = getCodeSandboxGivenName(kernelId);
+    if (existing) {
+        return existing;
+    }
+    const candidate = nextCodeSandboxGivenName(specDisplayName, listCodeSandboxGivenNames());
+    setCodeSandboxGivenName(kernelId, candidate);
+    return candidate;
+}
+export default ensureCodeSandboxGivenName;

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

@@ -2,7 +2,8 @@ import { ReactElement, ReactNode } from 'react';
 import { ISessionContext } from '@jupyterlab/apputils';
 import { ITranslator } from '@jupyterlab/translation';
 import { IRuntimeDesc } from '../../models';
-import { IMultiServiceManager } from '../../runtimes';
+import { type IMultiServiceManager } from '../../runtimes';
+import type { CodeSandboxTransfer } from './CodeSandboxTransfer';
 type IDisplayMode = 'menu' | 'radio';
 /**
  * {@link CodeSandboxPicker} properties
@@ -38,13 +39,18 @@ export interface ICodeSandboxPickerProps {
         location?: string;
     };
     /**
-     * Runtime description.
+     * The sandbox shown as chosen.
+     *
+     * Given with {@link setRuntimeDesc}, the choice belongs to the host — a
+     * cell keeps it in its metadata. Omitted, the picker holds it itself and
+     * reports it through {@link onTransferChange}, which is what a dialog with
+     * no state of its own needs.
      */
     runtimeDesc?: IRuntimeDesc;
     /**
      * Set runtime description.
      */
-    setRuntimeDesc: (desc?: IRuntimeDesc) => void;
+    setRuntimeDesc?: (desc?: IRuntimeDesc) => void;
     /**
      * Document session context.
      */
@@ -61,11 +67,30 @@ export interface ICodeSandboxPickerProps {
      * Change the look depending on the menu integration.
      */
     variant?: 'document' | 'cell';
+    /**
+     * Whether the questions of a NEW sandbox are asked below the list.
+     *
+     * They are the launcher's own — see `NewCodeSandboxControls` — and only
+     * concern a sandbox that does not run yet.
+     */
+    withNewSandboxControls?: boolean;
+    /**
+     * Whether the variables of the current sandbox may be carried to the
+     * chosen one, when both speak a language the snippets can serialize.
+     */
+    withVariablesTransfer?: boolean;
+    /**
+     * Called with the answer a dialog would return: the sandbox to assign and
+     * the variables to carry over.
+     *
+     * The sandbox is named the way the callers start it: `remote-` and
+     * `browser-` prefix an environment to start one in, a local environment is
+     * named by its specification alone, and `id` names one that already runs.
+     */
+    onTransferChange?: (transfer: CodeSandboxTransfer) => void;
 }
 /**
  * The picker of a code sandbox: what runs already, and what could run.
  */
 export declare function CodeSandboxPicker(props: ICodeSandboxPickerProps): ReactElement;
-export declare const RuntimePickerBase: typeof CodeSandboxPicker;
-export type IRuntimePickerBaseProps = ICodeSandboxPickerProps;
 export default CodeSandboxPicker;