xtralab 0.1.1 → 0.2.0

package/lib/git/diffWidget.js

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { MainAreaWidget } from '@jupyterlab/apputils';
 import { PathExt } from '@jupyterlab/coreutils';
-import { ReactWidget, undoIcon } from '@jupyterlab/ui-components';
+import { ReactWidget, ToolbarButton, launchIcon, undoIcon } from '@jupyterlab/ui-components';
 import { Signal } from '@lumino/signaling';
 import { FileDiff } from '@pierre/diffs/react';
 import { diffAcceptRejectHunk, parseDiffFromFile } from '@pierre/diffs';
@@ -13,6 +13,10 @@ import { buildNotebookDiff, NotebookDiffView } from './notebookDiff';
  * style the embedded `@pierre/diffs` viewer hang off this class.
  */
 export const DIFF_WIDGET_CSS_CLASS = 'jp-xtralab-DiffWidget';
+export const PREVIEW_DIFF_WIDGET_ID = 'xtralab:diff:preview';
+export function pinnedDiffWidgetId(change) {
+    return `xtralab:diff:pinned:${change.group}:${change.path}`;
+}
 /**
  * `localStorage` key for the user's last-chosen split ratio. Persisted so
  * the preference survives reloads — the library has no built-in way to
@@ -100,6 +104,9 @@ function writeStoredNotebookViewMode(mode) {
 export function diffWidgetId(change) {
     return `xtralab:diff:${change.group}:${change.path}`;
 }
+function toServerPath(repoPath, filePath) {
+    return repoPath.length > 0 ? PathExt.join(repoPath, filePath) : filePath;
+}
 /**
  * Resolve the pair of git references whose `content` should appear on the
  * left and right side of the diff for a given file change. Mirrors VS
@@ -128,6 +135,7 @@ export function resolveReferences(change) {
  * read-only main-area widgets in the JupyterLab ecosystem.
  */
 export function createGitDiffWidget(options) {
+    var _a;
     // `widget` is captured by the `onEmpty` closure we pass into the content,
     // but doesn't exist yet at construction time — declare it up front so the
     // closure can read it once the widget is wired.
@@ -143,38 +151,81 @@ export function createGitDiffWidget(options) {
         }
     });
     widget = new MainAreaWidget({ content });
-    widget.id = diffWidgetId(options.change);
+    widget.id =
+        options.pinned === true
+            ? pinnedDiffWidgetId(options.change)
+            : PREVIEW_DIFF_WIDGET_ID;
     widget.title.label = formatTitle(options.change);
     widget.title.caption = options.change.path;
     widget.title.closable = true;
     widget.title.icon = getTreeIcon(options.change.path);
+    widget.title.className = options.pinned === true ? '' : 'jp-mod-preview';
+    const onPinned = (_a = options.onPinned) !== null && _a !== void 0 ? _a : (() => { });
     widget.addClass(DIFF_WIDGET_CSS_CLASS);
     // Wire the notebook view-mode selector into the `MainAreaWidget` toolbar
     // — the proper home for document chrome controls. The toolbar starts
     // hidden and becomes visible once the React content reports a parsed
     // notebook diff via `setHasNotebookView`. Plain text / code diffs never
-    // flip that flag, so their toolbar bar stays collapsed and the
-    // resulting layout matches what other read-only main-area documents
-    // look like in JupyterLab.
+    // flip that flag, and pin state can hide the toolbar again, so the host
+    // chrome tracks the active mode.
+    const pinButton = new ToolbarButton({
+        icon: launchIcon,
+        tooltip: 'Pin tab',
+        onClick: () => content.pin()
+    });
+    if (content.pinned) {
+        pinButton.hide();
+    }
+    widget.toolbar.addItem('pin', pinButton);
     widget.toolbar.addItem('notebook-view-mode', new NotebookViewModeToolbarItem(content));
-    widget.toolbar.hide();
-    const onHasNotebookViewChanged = (_sender, value) => {
+    const syncToolbarVisibility = () => {
         if (widget === null || widget.isDisposed) {
             return;
         }
-        if (value) {
+        if (!content.pinned || content.hasNotebookView) {
             widget.toolbar.show();
         }
         else {
             widget.toolbar.hide();
         }
     };
+    const onHasNotebookViewChanged = () => {
+        if (widget === null || widget.isDisposed) {
+            return;
+        }
+        syncToolbarVisibility();
+    };
+    const onPinnedChanged = (sender, value) => {
+        if (widget === null || widget.isDisposed) {
+            return;
+        }
+        void sender;
+        if (value) {
+            pinButton.hide();
+            // Keep toolbar state and title styling consistent for promoted tabs.
+            onPinned(widget);
+            if (widget.isDisposed) {
+                return;
+            }
+            widget.title.className = '';
+        }
+        syncToolbarVisibility();
+    };
     content.hasNotebookViewChanged.connect(onHasNotebookViewChanged);
+    content.pinnedChanged.connect(onPinnedChanged);
+    syncToolbarVisibility();
     widget.disposed.connect(() => {
         content.hasNotebookViewChanged.disconnect(onHasNotebookViewChanged);
+        content.pinnedChanged.disconnect(onPinnedChanged);
     });
     return widget;
 }
+export function updateGitDiffWidget(widget, change) {
+    widget.content.setChange(change);
+    widget.title.label = formatTitle(change);
+    widget.title.caption = change.path;
+    widget.title.icon = getTreeIcon(change.path);
+}
 /**
  * The actual React-rendered region of the diff viewer. Held in its own
  * `ReactWidget` so the surrounding `MainAreaWidget` can manage chrome
@@ -193,7 +244,9 @@ export class DiffContentWidget extends ReactWidget {
         this._notebookViewModeChanged = new Signal(this);
         this._hasNotebookView = false;
         this._hasNotebookViewChanged = new Signal(this);
+        this._pinnedChanged = new Signal(this);
         this._options = options;
+        this._pinned = options.pinned === true;
         this._notebookViewMode = readStoredNotebookViewMode();
     }
     /** The change this widget renders, used by callers to identify the widget. */
@@ -236,6 +289,23 @@ export class DiffContentWidget extends ReactWidget {
     get hasNotebookViewChanged() {
         return this._hasNotebookViewChanged;
     }
+    get pinned() {
+        return this._pinned;
+    }
+    pin() {
+        if (this._pinned) {
+            return;
+        }
+        this._pinned = true;
+        this._pinnedChanged.emit(true);
+    }
+    get pinnedChanged() {
+        return this._pinnedChanged;
+    }
+    setChange(change) {
+        this._options = { ...this._options, change };
+        this.update();
+    }
     render() {
         return React.createElement(DiffViewer, { ...this._options, widget: this });
     }
@@ -355,8 +425,16 @@ function DiffViewer(props) {
     }, [themeManager]);
     React.useEffect(() => {
         let cancelled = false;
+        const serverPath = toServerPath(repoPath, change.path);
+        setState({
+            loading: true,
+            metadata: null,
+            notebookDiff: null,
+            serverPath,
+            isBinary: false,
+            error: null
+        });
         const { oldRef, newRef } = resolveReferences(change);
-        const serverPath = repoPath.length > 0 ? PathExt.join(repoPath, change.path) : change.path;
         void (async () => {
             var _a, _b, _c, _d;
             try {
@@ -612,6 +690,9 @@ function NotebookViewModeControl(props) {
             content.notebookViewModeChanged.disconnect(handler);
         };
     }, [content]);
+    if (!content.hasNotebookView) {
+        return React.createElement(React.Fragment, null);
+    }
     return (React.createElement("div", { className: "jp-xtralab-DiffWidget-segmented", role: "tablist", "aria-label": "Notebook diff view mode" },
         React.createElement("button", { type: "button", role: "tab", "aria-selected": mode === 'notebook', "data-active": mode === 'notebook', className: "jp-xtralab-DiffWidget-segmentedButton", onClick: () => content.setNotebookViewMode('notebook') }, "Notebook"),
         React.createElement("button", { type: "button", role: "tab", "aria-selected": mode === 'json', "data-active": mode === 'json', className: "jp-xtralab-DiffWidget-segmentedButton", onClick: () => content.setNotebookViewMode('json') }, "JSON")));

package/lib/git/index.js

@@ -2,7 +2,7 @@ import { ILayoutRestorer } from '@jupyterlab/application';
 import { Dialog, ICommandPalette, IThemeManager, WidgetTracker, showDialog, showErrorMessage } from '@jupyterlab/apputils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import { CommandIDs, registerGitCommands } from './commands';
-import { diffWidgetId } from './diffWidget';
+import { PREVIEW_DIFF_WIDGET_ID, pinnedDiffWidgetId } from './diffWidget';
 import { GitPanel } from './panel';
 const GIT_PLUGIN_ID = 'xtralab:git';
 const GIT_DIFF_TRACKER_NAMESPACE = 'xtralab-git-diff';
@@ -34,14 +34,17 @@ const plugin = {
         const tracker = new WidgetTracker({
             namespace: GIT_DIFF_TRACKER_NAMESPACE
         });
-        const findDiff = (change) => {
-            var _a;
-            const id = diffWidgetId(change);
-            return (_a = tracker.find(widget => widget.id === id)) !== null && _a !== void 0 ? _a : undefined;
+        const findDiff = (change, pin = false) => {
+            const id = pin ? pinnedDiffWidgetId(change) : PREVIEW_DIFF_WIDGET_ID;
+            const existing = tracker.find(widget => !widget.isDisposed && widget.id === id);
+            return existing !== null && existing !== void 0 ? existing : undefined;
         };
         const panel = new GitPanel({
-            openDiff: change => {
+            openDiff: (change, options) => {
                 const args = { repoPath, change };
+                if ((options === null || options === void 0 ? void 0 : options.pin) === true) {
+                    args.pin = true;
+                }
                 void app.commands.execute(CommandIDs.openDiff, args);
             },
             confirm: async (title, body, accept) => {
@@ -54,7 +57,7 @@ const plugin = {
             },
             showError: showErrorMessage
         });
-        app.shell.add(panel, 'left', { rank: 800 });
+        app.shell.add(panel, 'left', { rank: 60 });
         if (restorer !== null) {
             restorer.add(panel, panel.id);
         }
@@ -67,6 +70,19 @@ const plugin = {
             rendermime,
             onChanged: () => panel.refresh(),
             trackDiff: widget => tracker.add(widget),
+            onPinned: current => {
+                const existing = findDiff(current.content.change, true);
+                if (existing !== undefined &&
+                    existing !== current &&
+                    !existing.isDisposed) {
+                    app.shell.activateById(existing.id);
+                    current.close();
+                    return;
+                }
+                current.id = pinnedDiffWidgetId(current.content.change);
+                current.title.className = '';
+                app.shell.activateById(current.id);
+            },
             findDiff
         });
     }

package/lib/git/panelComponent.d.ts

@@ -8,7 +8,9 @@ import { IFileChange } from './tokens';
  */
 export interface IGitPanelHandlers {
     /** Open a diff viewer for the given file in the main area. */
-    openDiff(change: IFileChange): void;
+    openDiff(change: IFileChange, options?: {
+        pin?: boolean;
+    }): void;
     /** Show a confirmation dialog. Returns true when the user accepted. */
     confirm(title: string, body: string, accept: string): Promise<boolean>;
     /** Show an error dialog. */

package/lib/git/panelComponent.js

@@ -169,7 +169,9 @@ export function GitPanelComponent(props) {
                             onClick: onUnstageAll
                         }
                     ]
-                    : undefined }, staged.map(change => (React.createElement(ChangeRow, { key: `${change.group}:${change.path}`, change: change, pendingAction: pendingActions[`${change.group}:${change.path}`], onClick: () => handlers.openDiff(change), actions: [
+                    : undefined }, staged.map(change => (React.createElement(ChangeRow, { key: `${change.group}:${change.path}`, change: change, pendingAction: pendingActions[`${change.group}:${change.path}`], onClick: event => handlers.openDiff(change, {
+                    pin: event.ctrlKey || event.metaKey
+                }), actions: [
                     {
                         label: 'Unstage changes',
                         symbol: '−',
@@ -184,7 +186,9 @@ export function GitPanelComponent(props) {
                             onClick: onStageAll
                         }
                     ]
-                    : undefined }, unstaged.map(change => (React.createElement(ChangeRow, { key: `${change.group}:${change.path}`, change: change, pendingAction: pendingActions[`${change.group}:${change.path}`], onClick: () => handlers.openDiff(change), actions: [
+                    : undefined }, unstaged.map(change => (React.createElement(ChangeRow, { key: `${change.group}:${change.path}`, change: change, pendingAction: pendingActions[`${change.group}:${change.path}`], onClick: event => handlers.openDiff(change, {
+                    pin: event.ctrlKey || event.metaKey
+                }), actions: [
                     {
                         label: 'Discard changes',
                         symbol: '⟲',
@@ -209,7 +213,6 @@ function PanelHeader(props) {
         : null;
     return (React.createElement("div", { className: "jp-xtralab-GitPanel-header" },
         React.createElement("div", { className: "jp-xtralab-GitPanel-headerInfo" },
-            React.createElement("div", { className: "jp-xtralab-GitPanel-title" }, "Source Control"),
             repoName !== null ? (React.createElement("div", { className: "jp-xtralab-GitPanel-repo", title: topLevel !== null && topLevel !== void 0 ? topLevel : '' }, repoName)) : null,
             (result === null || result === void 0 ? void 0 : result.branch) !== undefined && (result === null || result === void 0 ? void 0 : result.branch) !== null ? (React.createElement("div", { className: "jp-xtralab-GitPanel-branch" },
                 result.branch,

package/lib/index.js

@@ -1,5 +1,9 @@
 import fileBrowserPlugin from './fileBrowser';
 import gitPlugin from './git';
+import launcherPlugin from './launcher';
+import menusPlugin from './menus';
+import sidebarPlugin from './sidebar';
+import statusBarPlugin from './statusBar';
 /**
  * Every plugin contributed by `xtralab`. The entry point of the
  * labextension is an array because the package bundles several independent
@@ -9,6 +13,10 @@ import gitPlugin from './git';
  */
 const plugins = [
     fileBrowserPlugin,
-    gitPlugin
+    gitPlugin,
+    launcherPlugin,
+    menusPlugin,
+    sidebarPlugin,
+    statusBarPlugin
 ];
 export default plugins;

package/lib/launcher/agents.d.ts

@@ -0,0 +1,78 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+/**
+ * The shape of an agent card on the launcher. The `command` is the literal
+ * text typed into the new terminal session — interactive shells expand
+ * aliases, so users can point at `claude`, `cl`, or whatever runs their
+ * preferred wrapper.
+ */
+export interface IAgent {
+    id: string;
+    label: string;
+    caption: string;
+    command: string;
+    icon: LabIcon;
+    rank: number;
+    /**
+     * When false, the launcher skips the `which`-based availability check for
+     * this entry — useful for aliases or shell functions that aren't on PATH
+     * but still resolve when typed in a real terminal. Defaults to true.
+     */
+    requireAvailable: boolean;
+    /**
+     * Argv tokens spliced between `command` and a shell-quoted prompt when
+     * the user types one into the launcher's prompt box. The semantics:
+     *
+     *   - `[]` → prompt is appended as a positional argument:
+     *     `<command> 'PROMPT'`. (Used by claude, codex, gemini, vibe.)
+     *   - `['-i']` / `['--prompt']` → the prompt is preceded by a flag:
+     *     `<command> -i 'PROMPT'`. (Used by copilot, opencode.)
+     *   - `undefined` → the agent does not accept an initial prompt. The
+     *     launcher dims the agent's button while the prompt textarea is
+     *     non-empty, so the user gets a clear signal rather than a silently
+     *     dropped prompt.
+     *
+     * The prompt itself is always single-quoted with embedded single quotes
+     * escaped, so multi-line prompts and shell metacharacters are safe.
+     */
+    promptArgs?: string[];
+}
+/**
+ * The settings-side shape: every field except `id` is optional, so a user
+ * can override a single field on a default agent (e.g. swap the command for
+ * an alias) without restating the whole entry. New ids define brand-new
+ * agent cards.
+ */
+export interface IAgentSettings {
+    id: string;
+    label?: string;
+    caption?: string;
+    command?: string;
+    /**
+     * Inline SVG for a custom agent's icon. Required for new ids whose icon
+     * isn't shipped with xtralab; ignored for default ids unless explicitly
+     * set (in which case it overrides the built-in).
+     */
+    iconSvg?: string;
+    rank?: number;
+    /**
+     * When false, the agent is hidden from the launcher and the command
+     * palette. Defaults to true.
+     */
+    enabled?: boolean;
+    /** See `IAgent.requireAvailable`. */
+    requireAvailable?: boolean;
+    /**
+     * See `IAgent.promptArgs`. Pass an empty array to mark the agent as
+     * accepting a positional prompt; pass an array like `["-p"]` to use a
+     * flag. Pass `null` to explicitly turn off prompt support for an agent
+     * that has it on by default.
+     */
+    promptArgs?: string[] | null;
+}
+/**
+ * Merge xtralab's defaults with the user's settings. Default entries keep
+ * their built-in fields unless explicitly overridden; user-only entries are
+ * appended. `enabled: false` filters an entry out of the result entirely
+ * (so callers don't need to check the flag again).
+ */
+export declare function mergeAgents(overrides: IAgentSettings[]): IAgent[];

package/lib/launcher/agents.js

@@ -0,0 +1,168 @@
+import { LabIcon, terminalIcon } from '@jupyterlab/ui-components';
+import { BUILTIN_AGENT_ICONS } from './icons';
+/**
+ * Default agent cards shipped with xtralab. The list mirrors the eight
+ * first-class personas in `jupyter-ai-contrib/jupyter-ai-acp-client` (which
+ * is also where the icons come from), but uses the bare CLI names a user
+ * would type in a terminal rather than the ACP wrapper binaries that
+ * project spawns. Anything not on the user's `$PATH` is filtered out at
+ * activation time, so the wider list is harmless.
+ */
+const DEFAULTS = [
+    {
+        id: 'claude',
+        label: 'Claude',
+        caption: 'Start Claude Code in a new terminal.',
+        command: 'claude',
+        icon: BUILTIN_AGENT_ICONS.claude,
+        rank: 0,
+        requireAvailable: true,
+        promptArgs: []
+    },
+    {
+        id: 'codex',
+        label: 'Codex',
+        caption: 'Start the Codex CLI in a new terminal.',
+        command: 'codex',
+        icon: BUILTIN_AGENT_ICONS.codex,
+        rank: 1,
+        requireAvailable: true,
+        promptArgs: []
+    },
+    {
+        id: 'gemini',
+        label: 'Gemini',
+        caption: 'Start the Gemini CLI in a new terminal.',
+        command: 'gemini',
+        icon: BUILTIN_AGENT_ICONS.gemini,
+        rank: 2,
+        requireAvailable: true,
+        promptArgs: []
+    },
+    {
+        id: 'copilot',
+        label: 'Copilot',
+        caption: 'Start the GitHub Copilot CLI in a new terminal.',
+        command: 'copilot',
+        icon: BUILTIN_AGENT_ICONS.copilot,
+        rank: 3,
+        requireAvailable: true,
+        // `-i "PROMPT"` is the documented way to start interactive mode and
+        // auto-execute the prompt; `-p` exits after responding (non-interactive).
+        promptArgs: ['-i']
+    },
+    {
+        id: 'goose',
+        label: 'Goose',
+        caption: 'Start Goose in a new terminal.',
+        command: 'goose',
+        icon: BUILTIN_AGENT_ICONS.goose,
+        rank: 4,
+        requireAvailable: true
+        // `goose` does not accept an inline interactive prompt; users would
+        // need to type the prompt after `goose session` starts.
+    },
+    {
+        id: 'opencode',
+        label: 'OpenCode',
+        caption: 'Start OpenCode in a new terminal.',
+        command: 'opencode',
+        icon: BUILTIN_AGENT_ICONS.opencode,
+        rank: 5,
+        requireAvailable: true,
+        promptArgs: ['--prompt']
+    },
+    {
+        id: 'kiro',
+        label: 'Kiro',
+        caption: 'Start the Kiro CLI in a new terminal.',
+        command: 'kiro',
+        icon: BUILTIN_AGENT_ICONS.kiro,
+        rank: 6,
+        requireAvailable: true
+        // The Kiro chat session only takes initial prompts via the in-session
+        // `/chat new <prompt>` slash command, not a CLI argument.
+    },
+    {
+        id: 'mistral-vibe',
+        label: 'Mistral Vibe',
+        caption: 'Start Mistral Vibe in a new terminal.',
+        command: 'vibe',
+        icon: BUILTIN_AGENT_ICONS['mistral-vibe'],
+        rank: 7,
+        requireAvailable: true,
+        promptArgs: []
+    }
+];
+function resolveIcon(id, iconSvg) {
+    var _a;
+    if (iconSvg) {
+        return new LabIcon({ name: `xtralab:agent-custom-${id}`, svgstr: iconSvg });
+    }
+    return (_a = BUILTIN_AGENT_ICONS[id]) !== null && _a !== void 0 ? _a : terminalIcon;
+}
+/**
+ * Merge xtralab's defaults with the user's settings. Default entries keep
+ * their built-in fields unless explicitly overridden; user-only entries are
+ * appended. `enabled: false` filters an entry out of the result entirely
+ * (so callers don't need to check the flag again).
+ */
+export function mergeAgents(overrides) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    const overrideById = new Map(overrides.map(entry => [entry.id, entry]));
+    const merged = [];
+    for (const base of DEFAULTS) {
+        const override = overrideById.get(base.id);
+        if (!override) {
+            merged.push({ ...base });
+            continue;
+        }
+        overrideById.delete(base.id);
+        if (override.enabled === false) {
+            continue;
+        }
+        merged.push({
+            id: base.id,
+            label: (_a = override.label) !== null && _a !== void 0 ? _a : base.label,
+            caption: (_b = override.caption) !== null && _b !== void 0 ? _b : base.caption,
+            command: (_c = override.command) !== null && _c !== void 0 ? _c : base.command,
+            icon: override.iconSvg
+                ? resolveIcon(base.id, override.iconSvg)
+                : base.icon,
+            rank: (_d = override.rank) !== null && _d !== void 0 ? _d : base.rank,
+            requireAvailable: (_e = override.requireAvailable) !== null && _e !== void 0 ? _e : base.requireAvailable,
+            // `null` is the explicit way to opt out of an agent's default prompt
+            // support; an absent key keeps the default. `undefined` from `??` is
+            // pruned below.
+            promptArgs: override.promptArgs === null
+                ? undefined
+                : ((_f = override.promptArgs) !== null && _f !== void 0 ? _f : base.promptArgs)
+        });
+    }
+    // What remains in `overrideById` are entries with ids that don't match a
+    // default — treat them as new agents the user is adding. Skip silently
+    // when a required field is missing rather than throwing; the settings
+    // schema validates the shape, so this is just a defensive fallback.
+    let nextRank = merged.reduce((max, agent) => Math.max(max, agent.rank), -1) + 1;
+    for (const entry of overrideById.values()) {
+        if (entry.enabled === false) {
+            continue;
+        }
+        const label = (_g = entry.label) !== null && _g !== void 0 ? _g : entry.id;
+        const command = (_h = entry.command) !== null && _h !== void 0 ? _h : entry.id;
+        merged.push({
+            id: entry.id,
+            label,
+            caption: (_j = entry.caption) !== null && _j !== void 0 ? _j : `Start ${label} in a new terminal.`,
+            command,
+            icon: resolveIcon(entry.id, entry.iconSvg),
+            rank: (_k = entry.rank) !== null && _k !== void 0 ? _k : nextRank++,
+            requireAvailable: (_l = entry.requireAvailable) !== null && _l !== void 0 ? _l : true,
+            promptArgs: entry.promptArgs === null || entry.promptArgs === undefined
+                ? undefined
+                : entry.promptArgs
+        });
+    }
+    merged.sort((a, b) => a.rank - b.rank);
+    return merged;
+}

package/lib/launcher/availability.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hit the xtralab server extension's `which`-proxy endpoint and turn the
+ * response into a Set of commands that resolved to a real binary on the
+ * server's `$PATH`. The frontend uses this set to filter the launcher's
+ * agent cards.
+ *
+ * On any failure (server extension not loaded, network error, malformed
+ * response) the returned Set is `null` — callers should treat that as
+ * "availability unknown" and either fall back to showing all agents or
+ * surface the error, depending on context.
+ */
+export declare function fetchAvailableCommands(commands: string[]): Promise<Set<string> | null>;

package/lib/launcher/availability.js

@@ -0,0 +1,53 @@
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+/**
+ * Hit the xtralab server extension's `which`-proxy endpoint and turn the
+ * response into a Set of commands that resolved to a real binary on the
+ * server's `$PATH`. The frontend uses this set to filter the launcher's
+ * agent cards.
+ *
+ * On any failure (server extension not loaded, network error, malformed
+ * response) the returned Set is `null` — callers should treat that as
+ * "availability unknown" and either fall back to showing all agents or
+ * surface the error, depending on context.
+ */
+export async function fetchAvailableCommands(commands) {
+    if (commands.length === 0) {
+        return new Set();
+    }
+    const settings = ServerConnection.makeSettings();
+    const url = URLExt.join(settings.baseUrl, 'xtralab', 'agents', 'availability');
+    let response;
+    try {
+        response = await ServerConnection.makeRequest(url, {
+            method: 'POST',
+            body: JSON.stringify({ commands })
+        }, settings);
+    }
+    catch (error) {
+        console.warn('xtralab: availability check failed', error);
+        return null;
+    }
+    if (!response.ok) {
+        console.warn(`xtralab: availability endpoint returned HTTP ${response.status}`);
+        return null;
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch (error) {
+        console.warn('xtralab: availability response was not JSON', error);
+        return null;
+    }
+    if (!payload || typeof payload !== 'object') {
+        return null;
+    }
+    const available = new Set();
+    for (const [command, path] of Object.entries(payload)) {
+        if (typeof path === 'string' && path.length > 0) {
+            available.add(command);
+        }
+    }
+    return available;
+}

package/lib/launcher/commands.d.ts

@@ -0,0 +1,22 @@
+import type { JupyterFrontEnd } from '@jupyterlab/application';
+import { type IDisposable } from '@lumino/disposable';
+import type { IAgent } from './agents';
+/**
+ * The command id for opening the launcher.
+ */
+export declare const CREATE_LAUNCHER_COMMAND = "launcher:create";
+/**
+ * Build a JupyterLab command id for a given agent. Centralised so the
+ * plugin and the launcher both use the same names.
+ */
+export declare function agentCommandId(agentId: string): string;
+/**
+ * Register a JupyterLab command per agent. Each command opens a new
+ * terminal via `terminal:create-new` and feeds the agent's shell command
+ * into the fresh session as if the user had typed it.
+ *
+ * Returns a single disposable that tears down every registered command —
+ * the launcher disposes the previous set before re-registering on settings
+ * changes so the command palette stays in sync with the configured agents.
+ */
+export declare function registerAgentCommands(app: JupyterFrontEnd, agents: IAgent[]): IDisposable;