jupyterlab_ai_code_assistants_extension 0.6.15

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Stellars Henson
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,44 @@
+# jupyterlab_ai_code_assistants_extension
+
+[![GitHub Actions](https://github.com/stellarshenson/jupyterlab_ai_code_assistants_extension/actions/workflows/build.yml/badge.svg)](https://github.com/stellarshenson/jupyterlab_ai_code_assistants_extension/actions/workflows/build.yml)
+[![npm version](https://img.shields.io/npm/v/jupyterlab_ai_code_assistants_extension.svg)](https://www.npmjs.com/package/jupyterlab_ai_code_assistants_extension)
+[![PyPI version](https://img.shields.io/pypi/v/jupyterlab-ai-code-assistants-extension.svg)](https://pypi.org/project/jupyterlab-ai-code-assistants-extension/)
+[![Total PyPI downloads](https://static.pepy.tech/badge/jupyterlab-ai-code-assistants-extension)](https://pepy.tech/project/jupyterlab-ai-code-assistants-extension)
+[![JupyterLab 4](https://img.shields.io/badge/JupyterLab-4-orange.svg)](https://jupyterlab.readthedocs.io/en/stable/)
+[![Brought To You By KOLOMOLO](https://img.shields.io/badge/Brought%20To%20You%20By-KOLOMOLO-00ffff?style=flat)](https://kolomolo.com)
+[![Donate PayPal](https://img.shields.io/badge/Donate-PayPal-blue?style=flat)](https://www.paypal.com/donate/?hosted_button_id=B4KPBJDLLXTSA)
+
+One extension for every AI code assistant in JupyterLab. Replaces the separate `jupyterlab_claude_code_extension`, `jupyterlab_codex_extension` and `jupyterlab_kimi_code_extension` packages with a single install that keeps each assistant's own side panel while sharing one settings page and one session-handling core underneath.
+
+> [!NOTE]
+> Early development. The scaffolding, build lifecycle and packaging are in place; the assistant panels are being ported from the standalone extensions.
+
+## Features
+
+- **One install, every assistant** - Claude Code, Codex, Kimi and Gemini supported from a single package
+- **Individual right-panel per assistant** - each assistant keeps its own side panel with Favorites, Recent and All projects
+- **Joint settings page** - one settings section covering all assistants, replacing three separate ones
+- **Per-assistant toggles** - switch any assistant's support on or off in settings; all are enabled by default
+- **Shared session core** - resume, branch, switch and clean up conversations through one common mechanism across assistants
+- **Auto-disabled when absent** - an assistant whose CLI is not installed does not show a panel
+
+## Requirements
+
+- JupyterLab >= 4.0.0
+- Python >= 3.10
+
+## Install
+
+To install the extension, execute:
+
+```bash
+pip install jupyterlab_ai_code_assistants_extension
+```
+
+## Uninstall
+
+To remove the extension, execute:
+
+```bash
+pip uninstall jupyterlab_ai_code_assistants_extension
+```

package/lib/core/colour.d.ts

@@ -0,0 +1,57 @@
+import { ServerConnection } from '@jupyterlab/services';
+import { ColourSource, ISession } from './types';
+/** The colour vocabulary of `jupyterlab_colourful_tab_extension`, in its own
+ * order - that extension owns the tab CSS and these six ids; this module only
+ * feeds it one of them. The order is load-bearing: its localStorage records a
+ * user's menu choice as an INDEX into this list. */
+export declare const TAB_COLOUR_IDS: readonly string[];
+/** Map a conversation id onto one of the six colour ids. FNV-1a (32-bit) - a
+ * stable string hash with good avalanche on short hex-ish ids; `Math.imul`
+ * keeps the multiplication in 32-bit integer semantics. The same id always
+ * yields the same colour, on every reload and in every browser. */
+export declare function fnv1aColour(sessionId: string): string;
+/** Colour the user set by hand on a terminal tab, or null.
+ *
+ * The colourful-tab extension stores its right-click menu choices as
+ * `{ "terminal:<session name>": <index into TAB_COLOUR_IDS> }`. Reading it is
+ * what makes "set the colour on the tab" register as the conversation's
+ * colour for assistants whose CLI has no colour concept at all. */
+export declare function readUserSetTabColour(terminalName: string): string | null;
+/** Resolve the ladder for one conversation. `userSet` is this extension's own
+ * store, `native` the conversation's own colour (only ever populated by a
+ * `native` provider). */
+export declare function effectiveColour(sessionId: string | null, source: ColourSource, userSet: string | null, native: string | null | undefined): string | null;
+/** Fall back from an unreadable conversation to the project a terminal sits
+ * in: longest matching path wins, so a nested project beats its parent.
+ * Never the first resort - a row carries only its representative
+ * conversation, so resolving colour by row tints every terminal of a project
+ * with the representative's colour. */
+export declare function sessionForCwds(cwds: string[], sessions: ISession[]): ISession | null;
+/**
+ * Client for one provider's user-set colour store.
+ *
+ * The store is server-side and per provider (`providers/<id>/colours`), so
+ * colours survive a reload and one assistant's colours can never be read or
+ * written through another's routes. Reads are cached in memory and refreshed
+ * with the session poll; writes go straight through and update the cache.
+ */
+export declare class ColourStore {
+    constructor(providerId: string, serverSettings: ServerConnection.ISettings);
+    /** User-set colour for a conversation, from the in-memory cache. */
+    get(sessionId: string | null | undefined): string | null;
+    /** Reload the whole store. Failures leave the previous cache in place - a
+     * momentarily unreachable server must not clear every user colour. */
+    load(): Promise<void>;
+    /** Record a colour as this conversation's own. Passing null drops the entry,
+     * which is also how a deleted conversation leaves no orphan key behind. */
+    set(sessionId: string, colour: string | null): Promise<void>;
+    /** Drop stored colours for conversations that no longer exist. */
+    forget(sessionIds: string[]): Promise<void>;
+    /** Copy the parent's EFFECTIVE colour onto a fresh branch, so a branch of a
+     * branch inherits whatever its immediate parent actually shows, user-set
+     * override included. Called at the fork sites, once the new id is known. */
+    inherit(parentColour: string | null, childId: string): Promise<void>;
+    private readonly _providerId;
+    private readonly _serverSettings;
+    private _colours;
+}

package/lib/core/colour.js

@@ -0,0 +1,190 @@
+// Terminal tab tint per conversation.
+//
+// Effective colour, highest wins:
+//   1. user-set     - the write-back store this module keeps, per provider
+//   2. native       - the conversation's own colour, when the assistant has one
+//   3. derived      - a stable hash of the conversation id
+//   4. none         - no tint
+//
+// Every step of that ladder is pure and exported on its own, because the tint
+// is the part of this panel that regressed twice behind a green suite that
+// never ran the logic.
+import { requestProvider } from './request';
+/** The colour vocabulary of `jupyterlab_colourful_tab_extension`, in its own
+ * order - that extension owns the tab CSS and these six ids; this module only
+ * feeds it one of them. The order is load-bearing: its localStorage records a
+ * user's menu choice as an INDEX into this list. */
+export const TAB_COLOUR_IDS = [
+    'rose',
+    'peach',
+    'lemon',
+    'mint',
+    'sky',
+    'lavender'
+];
+/** Key `jupyterlab_colourful_tab_extension` persists menu-set tab colours
+ * under, and the `terminal:<session name>` shape of its entries. Read only -
+ * this module never writes into another extension's storage. */
+const TAB_COLOUR_STORAGE_KEY = 'jupyterlab-colourful-tab-colours';
+/** Map a conversation id onto one of the six colour ids. FNV-1a (32-bit) - a
+ * stable string hash with good avalanche on short hex-ish ids; `Math.imul`
+ * keeps the multiplication in 32-bit integer semantics. The same id always
+ * yields the same colour, on every reload and in every browser. */
+export function fnv1aColour(sessionId) {
+    let hash = 0x811c9dc5; // FNV offset basis
+    for (let i = 0; i < sessionId.length; i++) {
+        hash ^= sessionId.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193); // FNV prime
+    }
+    return TAB_COLOUR_IDS[(hash >>> 0) % TAB_COLOUR_IDS.length];
+}
+/** Colour the user set by hand on a terminal tab, or null.
+ *
+ * The colourful-tab extension stores its right-click menu choices as
+ * `{ "terminal:<session name>": <index into TAB_COLOUR_IDS> }`. Reading it is
+ * what makes "set the colour on the tab" register as the conversation's
+ * colour for assistants whose CLI has no colour concept at all. */
+export function readUserSetTabColour(terminalName) {
+    var _a;
+    try {
+        const raw = window.localStorage.getItem(TAB_COLOUR_STORAGE_KEY);
+        if (!raw) {
+            return null;
+        }
+        const parsed = JSON.parse(raw);
+        const index = parsed[`terminal:${terminalName}`];
+        if (typeof index !== 'number') {
+            return null;
+        }
+        return (_a = TAB_COLOUR_IDS[index]) !== null && _a !== void 0 ? _a : null;
+    }
+    catch (_err) {
+        // localStorage unavailable, or another extension's schema changed under
+        // us - no user colour is a valid answer, a thrown error is not.
+        return null;
+    }
+}
+/** Resolve the ladder for one conversation. `userSet` is this extension's own
+ * store, `native` the conversation's own colour (only ever populated by a
+ * `native` provider). */
+export function effectiveColour(sessionId, source, userSet, native) {
+    if (userSet) {
+        return userSet;
+    }
+    if (source === 'native') {
+        return native !== null && native !== void 0 ? native : null;
+    }
+    if (source === 'derived' && sessionId) {
+        return fnv1aColour(sessionId);
+    }
+    return null;
+}
+/** Fall back from an unreadable conversation to the project a terminal sits
+ * in: longest matching path wins, so a nested project beats its parent.
+ * Never the first resort - a row carries only its representative
+ * conversation, so resolving colour by row tints every terminal of a project
+ * with the representative's colour. */
+export function sessionForCwds(cwds, sessions) {
+    let best = null;
+    let bestLen = -1;
+    for (const raw of cwds) {
+        const cwd = raw.replace(/\/+$/, '');
+        for (const s of sessions) {
+            const p = s.project_path.replace(/\/+$/, '');
+            if ((cwd === p || cwd.startsWith(p + '/')) && p.length > bestLen) {
+                best = s;
+                bestLen = p.length;
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Client for one provider's user-set colour store.
+ *
+ * The store is server-side and per provider (`providers/<id>/colours`), so
+ * colours survive a reload and one assistant's colours can never be read or
+ * written through another's routes. Reads are cached in memory and refreshed
+ * with the session poll; writes go straight through and update the cache.
+ */
+export class ColourStore {
+    constructor(providerId, serverSettings) {
+        this._colours = new Map();
+        this._providerId = providerId;
+        this._serverSettings = serverSettings;
+    }
+    /** User-set colour for a conversation, from the in-memory cache. */
+    get(sessionId) {
+        var _a;
+        if (!sessionId) {
+            return null;
+        }
+        return (_a = this._colours.get(sessionId)) !== null && _a !== void 0 ? _a : null;
+    }
+    /** Reload the whole store. Failures leave the previous cache in place - a
+     * momentarily unreachable server must not clear every user colour. */
+    async load() {
+        var _a;
+        try {
+            const data = await requestProvider(this._providerId, 'colours', this._serverSettings, { cache: 'no-store' });
+            const next = new Map();
+            for (const [id, colour] of Object.entries((_a = data.colours) !== null && _a !== void 0 ? _a : {})) {
+                if (typeof colour === 'string' && colour) {
+                    next.set(id, colour);
+                }
+            }
+            this._colours = next;
+        }
+        catch (_err) {
+            // Keep the cache; the next poll retries.
+        }
+    }
+    /** Record a colour as this conversation's own. Passing null drops the entry,
+     * which is also how a deleted conversation leaves no orphan key behind. */
+    async set(sessionId, colour) {
+        if (!sessionId) {
+            return;
+        }
+        if (colour) {
+            this._colours.set(sessionId, colour);
+        }
+        else {
+            this._colours.delete(sessionId);
+        }
+        try {
+            await requestProvider(this._providerId, 'colours', this._serverSettings, {
+                method: 'POST',
+                body: JSON.stringify({ session_id: sessionId, colour })
+            });
+        }
+        catch (_err) {
+            // The cache already reflects the intent; the next load reconciles.
+        }
+    }
+    /** Drop stored colours for conversations that no longer exist. */
+    async forget(sessionIds) {
+        const present = sessionIds.filter(id => this._colours.has(id));
+        if (present.length === 0) {
+            return;
+        }
+        present.forEach(id => this._colours.delete(id));
+        try {
+            await requestProvider(this._providerId, 'colours', this._serverSettings, {
+                method: 'DELETE',
+                body: JSON.stringify({ session_ids: present })
+            });
+        }
+        catch (_err) {
+            // Same as `set`: the cache is authoritative until the next load.
+        }
+    }
+    /** Copy the parent's EFFECTIVE colour onto a fresh branch, so a branch of a
+     * branch inherits whatever its immediate parent actually shows, user-set
+     * override included. Called at the fork sites, once the new id is known. */
+    async inherit(parentColour, childId) {
+        if (!parentColour || !childId) {
+            return;
+        }
+        await this.set(childId, parentColour);
+    }
+}

package/lib/core/icons.d.ts

@@ -0,0 +1,12 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+export declare const assistantsIcon: LabIcon;
+export declare const starFilledIcon: LabIcon;
+export declare const refreshIcon: LabIcon;
+export declare const removeIcon: LabIcon;
+export declare const warningIcon: LabIcon;
+export declare const addIcon: LabIcon;
+export declare const branchIcon: LabIcon;
+export declare const switchIcon: LabIcon;
+export declare const filterIcon: LabIcon;
+/** Build (or reuse) the LabIcon for a provider's own glyph. */
+export declare function providerIcon(name: string, svgstr: string): LabIcon;

package/lib/core/icons.js

@@ -0,0 +1,99 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+// Shared panel chrome icons. Provider icons are NOT here - each provider
+// carries its own SVG on its descriptor and the registry builds the LabIcon
+// from it, so adding an assistant touches no core file.
+//
+// Material-style glyphs matched to the rest of the sidebar so header and menu
+// icons render at identical size and theme.
+const ICON_PREFIX = 'jupyterlab_ai_code_assistants_extension';
+// The extension's own identity, used by the settings entry - one section for
+// all assistants, so it cannot borrow any one assistant's glyph. Material
+// "smart_toy" outline.
+const assistantsSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
+  <path class="jp-icon3" fill="#616161" d="M20 9V7c0-1.1-.9-2-2-2h-3c0-1.66-1.34-3-3-3S9 3.34 9 5H6c-1.1 0-2 .9-2 2v2c-1.66 0-3 1.34-3 3s1.34 3 3 3v4c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2v-4c1.66 0 3-1.34 3-3s-1.34-3-3-3zm-2 10H6V7h12v12zM9 13.5c-.83 0-1.5-.67-1.5-1.5s.67-1.5 1.5-1.5 1.5.67 1.5 1.5-.67 1.5-1.5 1.5zm7.5-1.5c0 .83-.67 1.5-1.5 1.5s-1.5-.67-1.5-1.5.67-1.5 1.5-1.5 1.5.67 1.5 1.5zM8 15h8v2H8v-2z"/>
+</svg>`;
+export const assistantsIcon = new LabIcon({
+    name: `${ICON_PREFIX}:assistants`,
+    svgstr: assistantsSvgStr
+});
+const starFilledSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
+  <path class="jp-icon3" fill="#616161" d="M12 2.5l2.9 6.4 7 .7-5.3 4.7 1.6 6.9L12 17.7l-6.2 3.5 1.6-6.9-5.3-4.7 7-.7z"/>
+</svg>`;
+export const starFilledIcon = new LabIcon({
+    name: `${ICON_PREFIX}:star-filled`,
+    svgstr: starFilledSvgStr
+});
+const refreshSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
+  <path class="jp-icon3" fill="#616161" d="M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z"/>
+</svg>`;
+export const refreshIcon = new LabIcon({
+    name: `${ICON_PREFIX}:refresh`,
+    svgstr: refreshSvgStr
+});
+const removeSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
+  <path class="jp-icon3" fill="#616161" d="M6 19c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V7H6v12zM8 9h8v10H8V9zm7.5-5l-1-1h-5l-1 1H5v2h14V4h-3.5z"/>
+</svg>`;
+export const removeIcon = new LabIcon({
+    name: `${ICON_PREFIX}:remove`,
+    svgstr: removeSvgStr
+});
+// Marks the unsafe launch variants. A shield reads as "protected", which is
+// the inverse of what these entries do, so the caution triangle carries them
+// instead. Material "warning" outline.
+const warningSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="13" height="13">
+  <path class="jp-icon3" fill="#616161" d="M1 21h22L12 2 1 21zm12-3h-2v-2h2v2zm0-4h-2v-4h2v4z"/>
+</svg>`;
+export const warningIcon = new LabIcon({
+    name: `${ICON_PREFIX}:warning`,
+    svgstr: warningSvgStr
+});
+const addSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
+  <path class="jp-icon3" fill="#616161" d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"/>
+</svg>`;
+export const addIcon = new LabIcon({
+    name: `${ICON_PREFIX}:add`,
+    svgstr: addSvgStr
+});
+// Git-branch glyph (Octicons git-branch-16, MIT) - marks rows carrying
+// parallel conversations and the Branch Session entries.
+const branchSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16">
+  <path class="jp-icon3" fill="#616161" d="M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.493 2.493 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628a2.25 2.25 0 0 1-1.5-2.122Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z"/>
+</svg>`;
+export const branchIcon = new LabIcon({
+    name: `${ICON_PREFIX}:branch`,
+    svgstr: branchSvgStr
+});
+// Arrow-switch glyph (Octicons arrow-switch-16, MIT) - the switch-and-manage
+// submenu.
+const switchSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16">
+  <path class="jp-icon3" fill="#616161" d="M5.22 14.78a.75.75 0 0 0 1.06-1.06L4.56 12h8.69a.75.75 0 0 0 0-1.5H4.56l1.72-1.72a.75.75 0 0 0-1.06-1.06l-3 3a.75.75 0 0 0 0 1.06l3 3Zm5.56-6.5a.75.75 0 1 1-1.06-1.06l1.72-1.72H2.75a.75.75 0 0 1 0-1.5h8.69L9.72 2.28a.75.75 0 0 1 1.06-1.06l3 3a.75.75 0 0 1 0 1.06l-3 3Z"/>
+</svg>`;
+export const switchIcon = new LabIcon({
+    name: `${ICON_PREFIX}:switch`,
+    svgstr: switchSvgStr
+});
+// Funnel copied verbatim from @jupyterlab/ui-components' `search/filter.svg` -
+// the same image the file browser's filter toggle uses. `class="jp-icon3"`
+// lets the theme drive the fill, so the source `fill="#FFF"` is inert under
+// the standard light/dark themes.
+const filterSvgStr = `<svg xmlns="http://www.w3.org/2000/svg" width="16" viewBox="0 0 24 24">
+  <path fill="#FFF" d="M14 12v7.88c.04.3-.06.62-.29.83a.996.996 0 0 1-1.41 0l-2.01-2.01a.99.99 0 0 1-.29-.83V12h-.03L4.21 4.62a1 1 0 0 1 .17-1.4c.19-.14.4-.22.62-.22h14c.22 0 .43.08.62.22a1 1 0 0 1 .17 1.4L14.03 12z" class="jp-icon3"/>
+</svg>`;
+export const filterIcon = new LabIcon({
+    name: `${ICON_PREFIX}:filter`,
+    svgstr: filterSvgStr
+});
+// Provider glyphs already built, by icon name. LabIcon warns and returns the
+// first registration for a duplicate name, so a provider re-registered by a
+// live settings toggle must resolve to the icon it built the first time
+// rather than construct a second one on every toggle.
+const _providerIcons = new Map();
+/** Build (or reuse) the LabIcon for a provider's own glyph. */
+export function providerIcon(name, svgstr) {
+    let icon = _providerIcons.get(name);
+    if (!icon) {
+        icon = new LabIcon({ name, svgstr });
+        _providerIcons.set(name, icon);
+    }
+    return icon;
+}

package/lib/core/modes.d.ts

@@ -0,0 +1,13 @@
+import { ILaunchMode } from './types';
+/**
+ * The single launch-mode token for one action, or undefined for a plain launch.
+ *
+ * The payload carries at most one mode, because the server maps one token to
+ * one flag. `force` wins outright - that is what the menu's variant entries
+ * do. Otherwise an enum mode moved off its default takes precedence over any
+ * boolean switch: the enum is the explicit statement of intent, so a boolean
+ * left on must not silently invert it. A boolean fires only while every enum
+ * mode sits at its default. An enum at its default sends nothing - it is what
+ * the CLI would do unasked.
+ */
+export declare function resolveLaunchMode(launchModes: ILaunchMode[], values: Record<string, boolean | string>, force?: string): string | undefined;

package/lib/core/modes.js

@@ -0,0 +1,36 @@
+// Launch-mode resolution: which single mode token, if any, one launch carries.
+//
+// Its own module because the panel is the only caller but not the only reader -
+// the precedence between a boolean switch and an enum ladder is a rule worth
+// asserting on its own, and this file pulls in no JupyterLab surface.
+/**
+ * The single launch-mode token for one action, or undefined for a plain launch.
+ *
+ * The payload carries at most one mode, because the server maps one token to
+ * one flag. `force` wins outright - that is what the menu's variant entries
+ * do. Otherwise an enum mode moved off its default takes precedence over any
+ * boolean switch: the enum is the explicit statement of intent, so a boolean
+ * left on must not silently invert it. A boolean fires only while every enum
+ * mode sits at its default. An enum at its default sends nothing - it is what
+ * the CLI would do unasked.
+ */
+export function resolveLaunchMode(launchModes, values, force) {
+    if (force) {
+        return force;
+    }
+    for (const mode of launchModes) {
+        const value = values[mode.id];
+        if (mode.kind !== 'boolean' &&
+            typeof value === 'string' &&
+            value &&
+            value !== mode.default) {
+            return `${mode.id}=${value}`;
+        }
+    }
+    for (const mode of launchModes) {
+        if (mode.kind === 'boolean' && values[mode.id] === true) {
+            return mode.id;
+        }
+    }
+    return undefined;
+}