xtralab 0.15.0 → 0.15.2

package/lib/terminals/index.js

@@ -12,41 +12,6 @@ import { SessionRegistry } from './model';
 import { IAgentTerminals } from './tokens';
 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.
- * Rows running a coding agent carry a smaller second line below the
- * title with the agent's latest line of output, so the panel shows what
- * each agent is doing at a glance — on by default, and switchable off
- * through the `showAgentActivity` setting.
- *
- * 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 Terminals
- * section's title toolbar carries a `+` button and a stop button (the
- * latter shuts every session down at once, after a confirmation).
- *
- * The list is one movable section, and other panels' sections can move in.
- *
- * 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.
- *
- * The plugin also provides {@link IAgentTerminals} — the sessions with a
- * detection-confirmed running agent, plus a "paste a prompt into one"
- * action — which the ask-agent popup uses to offer running agents as
- * targets next to "new terminal".
- */
 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.',
@@ -64,13 +29,8 @@ const plugin = {
     ],
     activate: (app, tracker, restorer, translator, agentRegistry, editorRegistry, agentSessions, settingRegistry, movableSections) => {
         const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
-        // Resolve a running agent/editor identifier 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. Detection reports
-        // either the configured `command` or the canonical `id` (see
-        // `detectCommands`), so a row whose command is an alias — e.g. `ccm` for
-        // `claude` — still resolves to the right logo via its id. Reads the
-        // registries live so it tracks settings changes. Used to badge each row.
+        // Detection reports either the configured `command` or the canonical `id`,
+        // so an aliased command (e.g. `ccm` for `claude`) still maps to its logo.
         const iconForCommand = (command) => {
             var _a;
             if (!command) {
@@ -80,18 +40,9 @@ const plugin = {
             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 || e.id === command);
             return (_a = editor === null || editor === void 0 ? void 0 : editor.icon) !== null && _a !== void 0 ? _a : terminalIcon;
         };
-        // The names the server should look for in each terminal's process tree:
-        // for every agent and editor, its configured `command` plus its canonical
-        // `id`. The id is the real CLI name (e.g. `claude`, `nvim`), so an agent
-        // whose command points at an alias — e.g. `ccm` running `claude` — is
-        // still recognised by the process it actually spawns. Read live so the
-        // list tracks settings changes; deduplicated since command and id usually
-        // coincide.
         const detectCommands = () => {
             var _a, _b;
             const names = new Set();
@@ -105,10 +56,6 @@ const plugin = {
             }
             return Array.from(names);
         };
-        // Whether a detected command/id belongs to a coding agent rather than an
-        // editor. Only agent sessions get a latest-activity line (editor
-        // terminals stay badge-only), and only they are offered as prompt
-        // targets through `IAgentTerminals`.
         const isAgentCommand = (command) => {
             var _a;
             return (_a = agentRegistry === null || agentRegistry === void 0 ? void 0 : agentRegistry.agents.some(a => a.command === command || a.id === command)) !== null && _a !== void 0 ? _a : false;
@@ -116,18 +63,13 @@ const plugin = {
         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,
             detectCommands,
             isAgentCommand
         });
-        // 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.
+        // `Title.icon` ignores an unchanged assignment, so re-running per
+        // stateChanged is cheap.
         const syncTabIcons = () => {
             tracker.forEach(widget => {
                 const session = widget.content.session;
@@ -140,10 +82,8 @@ const plugin = {
         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.
+            // `terminal:open` activates an attached tab or spins up a fresh widget
+            // connected to the live session.
             void app.commands.execute('terminal:open', { name });
         };
         const onShutdown = (name) => {
@@ -152,10 +92,6 @@ const plugin = {
             });
         };
         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?'),
@@ -173,19 +109,8 @@ const plugin = {
                 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.
+        // `MenuSvg`, not the bare Lumino `Menu`: its renderer applies the `menuItem`
+        // LabIcon stylesheet — the bare menu renders raw, oversized SVGs.
         let newMenu = null;
         const onCreate = (anchor) => {
             var _a;
@@ -214,15 +139,8 @@ const plugin = {
             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.
+        // The shipped labconfig `layout` setting ranks this panel first (rank only,
+        // no area pin, so "Move Widget" works); this rank is the fallback.
         app.shell.add(panel, 'left', { rank: 1 });
         if (restorer) {
             restorer.add(panel, panel.id);
@@ -235,9 +153,6 @@ const plugin = {
             movableSections.registerTarget(PLUGIN_ID, trans.__('Terminals'), panel);
             panel.announceSections();
         }
-        // The latest-activity line under each agent row is on by default; honour
-        // the `showAgentActivity` setting so it can be turned off. Read on load and
-        // re-applied on every change.
         if (settingRegistry) {
             settingRegistry
                 .load(PLUGIN_ID)
@@ -246,9 +161,8 @@ const plugin = {
                     registry.setActivityEnabled(boolOption(settings.composite.showAgentActivity, true));
                 };
                 applyActivitySetting();
-                // Bind the slot to the panel so disposing the panel (which clears
-                // its signal data) drops the connection — the disposed registry is
-                // then never reached on a later settings change.
+                // Bound to the panel so disposing it drops the connection — the
+                // disposed registry is never reached on a later settings change.
                 settings.changed.connect(applyActivitySetting, panel);
             })
                 .catch(reason => {
@@ -265,9 +179,6 @@ const plugin = {
         });
     }
 };
-/**
- * Read a boolean setting value, falling back when it is missing or invalid.
- */
 function boolOption(value, fallback) {
     return typeof value === 'boolean' ? value : fallback;
 }

package/lib/terminals/model.d.ts

@@ -5,191 +5,114 @@ 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.
- *
- * For sessions running a coding agent it also surfaces a *latest activity*
- * line — the freshest meaningful line of the terminal's output, read from the
- * open tab's xterm buffer on a poll (see {@link activityFor}) — so each row
- * shows what its agent is doing, not just its name.
- *
- * 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.
+ * Source-of-truth model for the running-terminals panel: live sessions,
+ * labels cached across tab closes, agent badges (launch tags reconciled with
+ * polled detection, see {@link agentCommandFor}), and per-row latest-activity
+ * lines. `stateChanged` fires on every kind of update.
  */
 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.
+     * Emitted on any change to the session list, labels, badges, or activity.
      */
     get stateChanged(): ISignal<this, void>;
+    /**
+     * Whether the registry has been disposed.
+     */
     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.
+     * Names of all live sessions in stable (roughly creation) order.
      */
     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.
+     * True iff the named session is still on the server.
      */
     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).
+     * Display name for the session. The cache wins — it holds only "real"
+     * labels (see `_cacheLabel`), so the transient `Terminal {name}` an xterm
+     * widget shows during reconnect never flickers into the panel; the final
+     * fallback covers sessions never seen with a widget (e.g. a lab reload).
      */
     labelFor(name: string): string;
     /**
-     * An identifier for the agent running in the session — its configured
-     * command, or its canonical id when detection matched the spawned process by
-     * id rather than by an aliased command — or `null` if none. Callers resolve
-     * it to a logo through the plugin's `iconForCommand`, which accepts either.
-     *
-     * 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.
+     * Agent identifier for the session (configured command or canonical id), or
+     * `null`. Detection wins when it reports an agent; a launch tag fills the
+     * grace window and detection outages, and is ignored once detection says
+     * idle — that is how the badge clears when an agent exits.
      */
     agentCommandFor(name: string): string | null;
     /**
-     * The agent command server-side detection currently reports for the
-     * session, or `null` when it has not confirmed one (the session is idle,
-     * not yet covered by a poll, or detection is unavailable). Unlike
-     * {@link agentCommandFor} this never falls back to the optimistic launch
-     * tags: callers about to *write into* a session use it, and text must only
-     * ever be sent to a confirmed running agent — pasted into a shell prompt it
-     * would be executed.
+     * The agent command detection currently confirms for the session, or
+     * `null`. Never falls back to launch tags: callers about to *write into* a
+     * session use it, and text pasted into a shell prompt would be executed.
      */
     detectedCommandFor(name: string): string | null;
     /**
-     * The most recent meaningful line of output from the session's terminal, or
-     * `null` when there is nothing to surface — no coding agent is running in the
-     * session, its tab is closed (so there is no live buffer to read), or the
-     * buffer holds only the agent's input box and chrome. Refreshed on a poll by
-     * {@link _refreshActivity}; shown as a smaller line under the row's title.
-     * Always `null` while the activity line is disabled (see
-     * {@link setActivityEnabled}).
+     * The most recent meaningful line of the session's output, or `null` when
+     * nothing qualifies (no running agent, closed tab, chrome-only buffer, or
+     * the activity line is disabled).
      */
     activityFor(name: string): string | null;
     /**
-     * Turn the per-row latest-activity line on or off, driven by the
-     * `xtralab:terminals` `showAgentActivity` setting. When turned off the
-     * activity poll stops reading terminal buffers and any cached lines are
-     * dropped, so rows fall back to their title alone; when turned back on the
-     * lines are repopulated on the spot. A no-op when the value is unchanged.
+     * Turn the per-row activity line on or off (the `showAgentActivity`
+     * setting). Off drops cached lines; on repopulates them on the spot.
      */
     setActivityEnabled(enabled: boolean): void;
     /**
-     * Return the open widget for a session, if any. The panel uses this to
-     * switch behavior between "activate existing tab" and "open a new tab
-     * connected to the live session".
+     * The open widget for a session, if any.
      */
     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.
+     * Session name of the terminal that is the shell's current main-area
+     * widget, or `null` when the current widget is not a terminal.
      */
     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.
+     * Stable per-session rank in observation order, so rows don't reshuffle as
+     * sessions come and go.
      */
     rankFor(name: string): number;
+    /**
+     * Dispose of the registry's polls and signal connections.
+     */
     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.
+     * Adopt `next` as the live set and prune every per-session map, so the
+     * maps and rank counter don't grow without bound.
      */
     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.
+     * Poll body: update the detection map from the server. On failure the
+     * previous results are kept, so a transient error doesn't strip every badge.
      */
     private _refreshDetection;
     /**
-     * Poll body: re-read the buffer of each open coding-agent terminal and cache
-     * its latest meaningful line of output. Only sessions that have a running
-     * *agent* (not an editor) and an open tab qualify — a closed tab has no live
-     * buffer, editors run full-screen UIs that are not "activity", and plain
-     * shells would only echo their prompt. While a tab is reopening (its xterm
-     * is not ready yet) any existing line is kept; once the buffer is readable
-     * but has nothing worth showing the line is dropped, so a screen the agent
-     * has cleared doesn't leave a frozen line behind. Cached lines for sessions
-     * that no longer qualify are pruned. Emits only when something changed.
+     * Poll body: cache the latest meaningful output line of each open agent
+     * terminal (closed tabs have no live buffer; editors and shells don't
+     * qualify). Emits only when something changed.
      */
     private _refreshActivity;
     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.
+     * Recompute which terminal (if any) is the active main-area widget; emits
+     * only on change. Anything not a tracked terminal 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`. 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.
+     * Cache a label only when it is "real" — not `'...'` or `Terminal {name}`,
+     * the transient defaults xterm cycles through during reconnect. Without the
+     * filter, reopening a tab before the agent re-emits its title escape would
+     * clobber the cached agent name.
      */
     private _cacheLabel;
     private _onWidgetDisposed;
@@ -217,15 +140,21 @@ export declare class SessionRegistry implements IDisposable {
  * Construction options for {@link SessionRegistry}.
  */
 export declare namespace SessionRegistry {
+    /**
+     * The instantiation options for a session registry.
+     */
     interface IOptions {
+        /**
+         * The service manager whose terminal manager supplies the sessions.
+         */
         serviceManager: ServiceManager.IManager;
+        /**
+         * The tracker of open terminal widgets.
+         */
         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.
+         * Used to highlight the row of the current main-area terminal. Optional:
+         * without it (or its `currentChanged`) the highlight stays off.
          */
         shell?: JupyterFrontEnd.IShell | null;
         /**
@@ -234,19 +163,15 @@ export declare namespace SessionRegistry {
          */
         agentSessions?: IAgentSessions | null;
         /**
-         * Returns the names the server should look for when detecting running
-         * agents — each agent's command together with its canonical id, so a
-         * command pointed at an alias (e.g. `ccm` running `claude`) is still
-         * matched by the process it spawns. Read on every poll so it tracks the
-         * live agent list.
+         * Names to detect: each agent's command plus its canonical id, so an
+         * aliased command (e.g. `ccm` running `claude`) is still matched by the
+         * process it spawns. Read on every poll.
          */
         detectCommands?: () => string[];
         /**
-         * Whether a detected command (or id) belongs to a coding agent rather than
-         * an editor. Only agent sessions get a latest-activity line — editors
-         * (Neovim/Vim) are badged too, but run full-screen UIs whose buffer is not
-         * meaningfully "activity". Defaults to treating every detected command as an
-         * agent.
+         * Whether a detected command (or id) belongs to a coding agent rather
+         * than an editor; only agent sessions get a latest-activity line.
+         * Defaults to treating every detected command as an agent.
          */
         isAgentCommand?: (command: string) => boolean;
     }