xtralab 0.4.0 → 0.6.0

package/lib/terminals/detection.js

@@ -0,0 +1,50 @@
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+/**
+ * Ask the xtralab server which of `commands` is currently running inside each
+ * open terminal session. Resolves to a map from session name to the matched
+ * agent command, or `null` for a session sitting at its prompt.
+ *
+ * On any failure (endpoint missing on an older server, network error,
+ * malformed response) the whole result is `null` — callers should treat that
+ * as "detection unavailable" and fall back to the optimistic launch tags
+ * rather than clearing any badges.
+ */
+export async function fetchRunningAgents(commands) {
+    if (commands.length === 0) {
+        return {};
+    }
+    const settings = ServerConnection.makeSettings();
+    const url = URLExt.join(settings.baseUrl, 'xtralab', 'terminals', 'agents');
+    let response;
+    try {
+        response = await ServerConnection.makeRequest(url, {
+            method: 'POST',
+            body: JSON.stringify({ commands })
+        }, settings);
+    }
+    catch (error) {
+        console.warn('xtralab: running-agent detection failed', error);
+        return null;
+    }
+    if (!response.ok) {
+        console.warn(`xtralab: detection endpoint returned HTTP ${response.status}`);
+        return null;
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch (error) {
+        console.warn('xtralab: detection response was not JSON', error);
+        return null;
+    }
+    if (!payload || typeof payload !== 'object') {
+        return null;
+    }
+    const result = {};
+    for (const [name, command] of Object.entries(payload)) {
+        result[name] = typeof command === 'string' && command ? command : null;
+    }
+    return result;
+}

package/lib/terminals/index.d.ts

@@ -0,0 +1,27 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Adds a left-sidebar panel that lists every running terminal session.
+ *
+ * Each row is labelled with the *real* title the running program
+ * published — the launcher's agent name, or whatever title an xterm
+ * escape sequence set — which the registry caches so it survives the
+ * user closing the tab while the session keeps running on the server.
+ * JupyterLab's built-in "Running Terminals and Kernels" panel lists the
+ * same sessions but only by their `terminals/<n>` name, so this panel
+ * resolves and caches the published title to show something meaningful.
+ *
+ * Clicking a row activates the existing tab if one is open, or reopens
+ * the session in a fresh terminal widget (`terminal:open`). The inline
+ * `×` button shuts the session down on the server. The header carries a
+ * `+` button and a stop button (the latter shuts every session down at
+ * once, after a confirmation).
+ *
+ * The `+` button drops down a menu — built from the launcher's shared
+ * `IAgentRegistry` — listing each available agent (Claude, Codex, …)
+ * followed by a plain terminal, so starting an agent session is as
+ * consistent here as in the launcher and reuses the very same registered
+ * commands and icons. When the launcher is disabled or no agents are
+ * installed, the button falls back to opening a plain terminal directly.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/terminals/index.js

@@ -0,0 +1,194 @@
+import { ILayoutRestorer } from '@jupyterlab/application';
+import { Dialog, showDialog } from '@jupyterlab/apputils';
+import { ITerminalTracker } from '@jupyterlab/terminal';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { MenuSvg, terminalIcon } from '@jupyterlab/ui-components';
+import { IAgentSessions } from '../agentSessions';
+import { IEditorRegistry } from '../launcher/editorRegistry';
+import { agentCommandId, IAgentRegistry } from '../launcher/tokens';
+import { SessionRegistry } from './model';
+import { RunningTerminals } from './widget';
+const PLUGIN_ID = 'xtralab:terminals';
+/**
+ * Adds a left-sidebar panel that lists every running terminal session.
+ *
+ * Each row is labelled with the *real* title the running program
+ * published — the launcher's agent name, or whatever title an xterm
+ * escape sequence set — which the registry caches so it survives the
+ * user closing the tab while the session keeps running on the server.
+ * JupyterLab's built-in "Running Terminals and Kernels" panel lists the
+ * same sessions but only by their `terminals/<n>` name, so this panel
+ * resolves and caches the published title to show something meaningful.
+ *
+ * Clicking a row activates the existing tab if one is open, or reopens
+ * the session in a fresh terminal widget (`terminal:open`). The inline
+ * `×` button shuts the session down on the server. The header carries a
+ * `+` button and a stop button (the latter shuts every session down at
+ * once, after a confirmation).
+ *
+ * The `+` button drops down a menu — built from the launcher's shared
+ * `IAgentRegistry` — listing each available agent (Claude, Codex, …)
+ * followed by a plain terminal, so starting an agent session is as
+ * consistent here as in the launcher and reuses the very same registered
+ * commands and icons. When the launcher is disabled or no agents are
+ * installed, the button falls back to opening a plain terminal directly.
+ */
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'A left-sidebar panel listing every running terminal session by its real (program-published) title, with activate/reopen, shutdown and new-terminal actions.',
+    autoStart: true,
+    requires: [ITerminalTracker],
+    optional: [
+        ILayoutRestorer,
+        ITranslator,
+        IAgentRegistry,
+        IEditorRegistry,
+        IAgentSessions
+    ],
+    activate: (app, tracker, restorer, translator, agentRegistry, editorRegistry, agentSessions) => {
+        const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
+        // Resolve a session's running command to an icon: the matching agent's
+        // logo, the matching editor's logo (Neovim/Vim), or the plain terminal
+        // icon when nothing recognised is running. Reads `agentRegistry.agents`
+        // live so it tracks settings changes. Used by the panel to badge each row.
+        const iconForCommand = (command) => {
+            var _a;
+            if (!command) {
+                return terminalIcon;
+            }
+            const agent = agentRegistry === null || agentRegistry === void 0 ? void 0 : agentRegistry.agents.find(a => a.command === command);
+            if (agent) {
+                return agent.icon;
+            }
+            // A terminal running an editor (Neovim/Vim, or a user-configured one) is
+            // badged with its logo, the same as an agent.
+            const editor = editorRegistry === null || editorRegistry === void 0 ? void 0 : editorRegistry.editors.find(e => e.command === command);
+            return (_a = editor === null || editor === void 0 ? void 0 : editor.icon) !== null && _a !== void 0 ? _a : terminalIcon;
+        };
+        const registry = new SessionRegistry({
+            serviceManager: app.serviceManager,
+            tracker,
+            // The shell tells the registry which widget is current, so the panel can
+            // highlight the terminal that is the current main-area widget (and
+            // nothing while a notebook or other widget is current instead).
+            shell: app.shell,
+            agentSessions,
+            // The commands the server should look for: the current agent and editor
+            // lists, each read live from its registry so they track settings changes
+            // — a terminal running an agent or an editor (Neovim/Vim, or a configured
+            // one) is badged.
+            detectCommands: () => {
+                var _a, _b;
+                return [
+                    ...((_a = agentRegistry === null || agentRegistry === void 0 ? void 0 : agentRegistry.agents.map(a => a.command)) !== null && _a !== void 0 ? _a : []),
+                    ...((_b = editorRegistry === null || editorRegistry === void 0 ? void 0 : editorRegistry.editors.map(e => e.command)) !== null && _b !== void 0 ? _b : [])
+                ];
+            }
+        });
+        // Mirror the agent/editor detected in each open terminal onto its main-area
+        // tab icon, so the tab matches its sidebar row. Re-running on every
+        // `stateChanged` is safe: `Title.icon` ignores an unchanged assignment, so
+        // the writes neither loop nor churn.
+        const syncTabIcons = () => {
+            tracker.forEach(widget => {
+                var _a;
+                const session = (_a = widget.content) === null || _a === void 0 ? void 0 : _a.session;
+                if (!session) {
+                    return;
+                }
+                widget.title.icon = iconForCommand(registry.agentCommandFor(session.name));
+            });
+        };
+        registry.stateChanged.connect(syncTabIcons);
+        syncTabIcons();
+        const onActivate = (name) => {
+            // `terminal:open` is the upstream entry point that handles both
+            // sides of this: if a widget is already attached to the named
+            // session it activates that tab, otherwise it spins up a fresh
+            // widget connected to the live session.
+            void app.commands.execute('terminal:open', { name });
+        };
+        const onShutdown = (name) => {
+            void app.serviceManager.terminals.shutdown(name).catch(reason => {
+                console.error(`xtralab: failed to shut down terminal ${name}: ${reason}`);
+            });
+        };
+        const onShutdownAll = () => {
+            // Tearing down every session at once is hard to undo (each may be a
+            // running agent), so confirm before calling the manager's bulk
+            // shutdown. `runningChanged` then clears the list and the panel
+            // re-renders empty.
+            void showDialog({
+                title: trans.__('Shut Down All Terminals?'),
+                body: trans.__('Are you sure you want to permanently shut down all running terminals?'),
+                buttons: [
+                    Dialog.cancelButton({ label: trans.__('Cancel') }),
+                    Dialog.warnButton({ label: trans.__('Shut Down All') })
+                ]
+            })
+                .then(result => {
+                if (result.button.accept) {
+                    return app.serviceManager.terminals.shutdownAll();
+                }
+            })
+                .catch(reason => {
+                console.error(`xtralab: failed to shut down all terminals: ${reason}`);
+            });
+        };
+        // The header "+" button. With the launcher's agent registry available
+        // it drops down a menu of the available agents (reusing their registered
+        // `xtralab:start-agent:<id>` commands, so the icons and labels match the
+        // launcher exactly) followed by a separator and a plain terminal. Built
+        // lazily and repopulated on each open so it always reflects the current,
+        // settings-driven agent list. Without the registry (launcher disabled)
+        // or with no agents installed, there is nothing to choose between, so
+        // the button opens a plain terminal directly in one click.
+        //
+        // `MenuSvg` (not the bare Lumino `Menu`) is what every JupyterLab menu
+        // uses: its renderer applies the `menuItem` LabIcon stylesheet, which
+        // sizes the agent icons to 16px and centers them vertically — the bare
+        // `Menu` renders the raw, oversized, misaligned SVGs.
+        let newMenu = null;
+        const onCreate = (anchor) => {
+            var _a;
+            const agents = (_a = agentRegistry === null || agentRegistry === void 0 ? void 0 : agentRegistry.agents) !== null && _a !== void 0 ? _a : [];
+            if (agents.length === 0) {
+                void app.commands.execute('terminal:create-new');
+                return;
+            }
+            if (!newMenu) {
+                newMenu = new MenuSvg({ commands: app.commands });
+            }
+            newMenu.clearItems();
+            for (const agent of agents) {
+                newMenu.addItem({ command: agentCommandId(agent.id) });
+            }
+            newMenu.addItem({ type: 'separator' });
+            newMenu.addItem({ command: 'terminal:create-new' });
+            newMenu.open(anchor.x, anchor.y);
+        };
+        const panel = new RunningTerminals({
+            registry,
+            trans,
+            iconForCommand,
+            onActivate,
+            onShutdown,
+            onShutdownAll,
+            onCreate
+        });
+        // Added to the left sidebar. The shipped `layout` setting in
+        // jupyter-config/labconfig gives each sidebar widget a default rank —
+        // this Terminals panel ranks first, so running agents sit one click
+        // away at the top. That setting assigns rank only and pins no area, so
+        // the "Move Widget" context menu can relocate the panel and the layout
+        // restorer remembers where the user puts it. The `rank` here is the
+        // in-code fallback used when the setting is absent. Sessions restored
+        // from a previous lab run land via `runningChanged` once the terminal
+        // manager is ready, which the panel's `UseSignal` picks up.
+        app.shell.add(panel, 'left', { rank: 1 });
+        if (restorer) {
+            restorer.add(panel, panel.id);
+        }
+    }
+};
+export default plugin;

package/lib/terminals/model.d.ts

@@ -0,0 +1,191 @@
+import type { JupyterFrontEnd } from '@jupyterlab/application';
+import type { MainAreaWidget } from '@jupyterlab/apputils';
+import type { ServiceManager } from '@jupyterlab/services';
+import type { ITerminal, ITerminalTracker } from '@jupyterlab/terminal';
+import type { IDisposable } from '@lumino/disposable';
+import { ISignal } from '@lumino/signaling';
+import type { IAgentSessions } from '../agentSessions';
+/**
+ * The widget shape every entry in `ITerminalTracker` takes — kept here
+ * so the registry's call sites read cleanly.
+ */
+export type TerminalWidget = MainAreaWidget<ITerminal.ITerminal>;
+/**
+ * Source-of-truth model for the running-terminals panel. Each running
+ * terminal session known to the server is one entry; the registry caches
+ * the last `widget.title.label` we observed so the agent name (or any
+ * xterm-published title) survives the user closing the tab while the
+ * session continues running on the backend.
+ *
+ * It also resolves *which agent is running* in each session, so the panel can
+ * badge rows with the agent's logo. Two inputs feed that, reconciled by
+ * {@link agentCommandFor}:
+ *   - an optimistic launch tag ({@link IAgentSessions}) written when we start
+ *     an agent ourselves — instant, but blind to the agent later exiting; and
+ *   - authoritative server-side process detection, polled here, which works
+ *     for hand-started agents too and clears once an agent exits.
+ *
+ * Upstream session signals:
+ *   - `serviceManager.terminals.runningChanged` is the authoritative
+ *     list of live sessions; everything not in it has been shut down
+ *     server-side and we must drop it.
+ *   - `tracker.widgetAdded` plus the per-widget `title.changed` /
+ *     `disposed` signals keep our label cache in sync with whatever
+ *     xterm/the launcher has set on the open tabs.
+ *
+ * `stateChanged` is emitted for every kind of update; the panel hooks it
+ * through a `UseSignal` so a single subscription re-renders the list on
+ * any change.
+ */
+export declare class SessionRegistry implements IDisposable {
+    constructor(options: SessionRegistry.IOptions);
+    /**
+     * Emitted whenever the live session list, a cached label, or the detected
+     * running agent changes.
+     */
+    get stateChanged(): ISignal<this, void>;
+    get isDisposed(): boolean;
+    /**
+     * Names of all live sessions, ordered by their stable rank so the
+     * rendered list keeps a consistent order (roughly creation order) as
+     * new sessions are added and old ones shut down.
+     */
+    sessionNames(): string[];
+    /**
+     * True iff the named session is still on the server. Used by the panel
+     * to skip a row during the brief window between the session's shutdown
+     * and the next `runningChanged` arriving.
+     */
+    has(name: string): boolean;
+    /**
+     * Display name for the session. The cache wins because it only
+     * holds "real" labels (the launcher's agent name or an xterm escape
+     * sequence — see `_cacheLabel` for the filter); reading it first
+     * prevents the transient `Terminal {name}` an XTerm widget shows
+     * during reconnect from flickering into the panel. The live widget
+     * title is used when no cache exists, and the `Terminal {name}`
+     * fallback covers sessions we have never seen a widget for (e.g.
+     * surviving a lab reload).
+     */
+    labelFor(name: string): string;
+    /**
+     * The command of the agent running in the session, or `null` if none.
+     *
+     * Server-side detection is authoritative whenever it reports a running
+     * agent. A launch tag fills two gaps: the startup grace window right after
+     * we launch an agent (so its logo shows before its process is detectable),
+     * and any time detection is unavailable (older server, transient error).
+     * Once the grace window has passed and detection has reported the session
+     * as idle, the tag is ignored — that is how the badge clears when an agent
+     * exits.
+     */
+    agentCommandFor(name: string): string | null;
+    /**
+     * Return the open widget for a session, if any. The panel uses this to
+     * switch behaviour between "activate existing tab" and "open a new tab
+     * connected to the live session".
+     */
+    widgetFor(name: string): TerminalWidget | null;
+    /**
+     * Session name of the terminal that is currently the active widget in the
+     * shell's main area, or `null` when that widget is not a terminal (for
+     * example a notebook or text editor is current). The panel uses this to
+     * highlight the current terminal's row — mirroring how the file browser
+     * surfaces the open document — and to leave every row unhighlighted while a
+     * non-terminal tab is current.
+     */
+    currentSessionName(): string | null;
+    /**
+     * Stable per-session rank assigned in observation order. Used to keep
+     * the rendered list in a steady order so rows don't reshuffle as
+     * sessions come and go. Cleaned up when the session is shut down so the
+     * counter does not grow without bound across long sessions.
+     */
+    rankFor(name: string): number;
+    dispose(): void;
+    private _refreshLive;
+    private _onRunningChanged;
+    /**
+     * Adopt `next` as the live set and prune every per-session map for
+     * sessions that have gone away — labels, ranks, first-seen timestamps,
+     * detection results, and the shared launch tag. Without this the maps (and
+     * the rank counter) would grow without bound as terminals come and go.
+     */
+    private _reconcileLive;
+    /**
+     * Poll body: ask the server which agent runs in each terminal and update
+     * the detection map. On failure we keep the previous results rather than
+     * clearing them, so a transient error doesn't strip every badge.
+     */
+    private _refreshDetection;
+    private _onTagChanged;
+    private _onWidgetAdded;
+    private _onShellCurrentChanged;
+    /**
+     * Recompute which terminal (if any) is the active main-area widget and emit
+     * only when it changes. The terminal tracker tells us whether the shell's
+     * current widget is one of our terminals; anything else — a notebook, an
+     * editor, or nothing — clears the highlight.
+     */
+    private _updateCurrent;
+    private _trackWidget;
+    private _untrackWidget;
+    private _onTitleChanged;
+    /**
+     * Update the cached label for a session, but only when the new
+     * label is "real" — non-empty and not one of the transient defaults
+     * the XTerm widget cycles through during reconnect (`'...'` while
+     * the websocket is opening, `'Terminal {name}'` once
+     * `_initialConnection` fires). Without the filter, briefly
+     * reopening a tab while an agent has yet to re-emit its xterm
+     * title escape sequence would clobber the cached agent name with
+     * `Terminal 1`, which is exactly the regression we are guarding
+     * against. Live widget titles still display whatever the widget
+     * currently holds because `labelFor` consults the widget first;
+     * the filter only affects what survives a tab close.
+     */
+    private _cacheLabel;
+    private _onWidgetDisposed;
+    private _terminals;
+    private _tracker;
+    private _agentSessions;
+    private _detectCommands;
+    private _shell;
+    private _poll;
+    private _labels;
+    private _ranks;
+    private _firstSeen;
+    private _detected;
+    private _live;
+    private _currentName;
+    private _nextRank;
+    private _isDisposed;
+    private _stateChanged;
+}
+/**
+ * Construction options for {@link SessionRegistry}.
+ */
+export declare namespace SessionRegistry {
+    interface IOptions {
+        serviceManager: ServiceManager.IManager;
+        tracker: ITerminalTracker;
+        /**
+         * The application shell, used to tell which widget is currently active so
+         * the panel can highlight the terminal that is the current main-area
+         * widget — and highlight nothing when that widget is not a terminal (a
+         * notebook, an editor, …). Optional: without it, or on a shell that cannot
+         * report `currentChanged`, the highlight stays off.
+         */
+        shell?: JupyterFrontEnd.IShell | null;
+        /**
+         * Shared launch-tag registry. When present, its records seed each row's
+         * agent badge until server-side detection takes over.
+         */
+        agentSessions?: IAgentSessions | null;
+        /**
+         * Returns the agent commands the server should look for when detecting
+         * running agents. Read on every poll so it tracks the live agent list.
+         */
+        detectCommands?: () => string[];
+    }
+}