xtralab 0.15.0 → 0.15.2

package/lib/searchReplace/index.d.ts

@@ -1,25 +1,9 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Bind Accel+Shift+F (Cmd+Shift+F on macOS, Ctrl+Shift+F elsewhere) to the
- * project-wide Search and Replace panel, matching the equivalent shortcut in
- * editors like VS Code.
- *
- * Two pieces are needed because that chord is already taken: JupyterLab core
- * binds Accel+Shift+F to `filebrowser:toggle-main`.
- *
- * 1. The chord is freed declaratively. `SettingRegistry.reconcileShortcuts`
- *    keys collisions and disables on (keys, selector) — not on command — so the
- *    `@jupyterlab/shortcuts-extension:shortcuts` override in
- *    `default_setting_overrides.d/00-xtralab.json` disables the file-browser
- *    binding. The file browser stays reachable from its sidebar tab and the
- *    View menu; only the keyboard shortcut moves.
- *
- * 2. The new binding is added imperatively below rather than as another shipped
- *    default. A `disabled` default and a re-binding default land on the same
- *    (keys, selector) slot, and the disable suppresses every default on that
- *    slot — including the re-binding. `commands.addKeyBinding` runs outside the
- *    reconcile pass, so it is unaffected and wins cleanly once the file-browser
- *    binding is gone.
+ * Bind Accel+Shift+F to the Search and Replace panel (VS Code parity). Core
+ * binds the chord to `filebrowser:toggle-main`; a `default_setting_overrides.d`
+ * override disables it. The re-binding is imperative: `reconcileShortcuts` keys
+ * on (keys, selector), so the disable would suppress a shipped default too.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/searchReplace/index.js

@@ -4,33 +4,15 @@ import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 const PLUGIN_ID = 'xtralab:search-replace';
 const COMMAND_ID = 'xtralab:activate-search-replace';
 /**
- * Widget id of the panel contributed by `jupyterlab-search-replace`. The
- * extension adds it to the left sidebar but registers no command of its own,
- * so there is nothing to bind a shortcut to out of the box — this plugin adds
- * the missing command.
+ * Widget id of the `jupyterlab-search-replace` left-sidebar panel; the
+ * extension registers no command of its own to bind a shortcut to.
  */
 const SEARCH_REPLACE_WIDGET_ID = 'jp-search-replace';
 /**
- * Bind Accel+Shift+F (Cmd+Shift+F on macOS, Ctrl+Shift+F elsewhere) to the
- * project-wide Search and Replace panel, matching the equivalent shortcut in
- * editors like VS Code.
- *
- * Two pieces are needed because that chord is already taken: JupyterLab core
- * binds Accel+Shift+F to `filebrowser:toggle-main`.
- *
- * 1. The chord is freed declaratively. `SettingRegistry.reconcileShortcuts`
- *    keys collisions and disables on (keys, selector) — not on command — so the
- *    `@jupyterlab/shortcuts-extension:shortcuts` override in
- *    `default_setting_overrides.d/00-xtralab.json` disables the file-browser
- *    binding. The file browser stays reachable from its sidebar tab and the
- *    View menu; only the keyboard shortcut moves.
- *
- * 2. The new binding is added imperatively below rather than as another shipped
- *    default. A `disabled` default and a re-binding default land on the same
- *    (keys, selector) slot, and the disable suppresses every default on that
- *    slot — including the re-binding. `commands.addKeyBinding` runs outside the
- *    reconcile pass, so it is unaffected and wins cleanly once the file-browser
- *    binding is gone.
+ * Bind Accel+Shift+F to the Search and Replace panel (VS Code parity). Core
+ * binds the chord to `filebrowser:toggle-main`; a `default_setting_overrides.d`
+ * override disables it. The re-binding is imperative: `reconcileShortcuts` keys
+ * on (keys, selector), so the disable would suppress a shipped default too.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -45,9 +27,7 @@ const plugin = {
             label: trans.__('Search and Replace'),
             caption: trans.__('Show the Search and Replace panel'),
             execute: () => {
-                // `activateById` expands the left sidebar when collapsed, selects the
-                // tab, and the widget focuses its search input from `onAfterShow`, so
-                // the user can start typing a query immediately. It no-ops if
+                // The widget focuses its search input from `onAfterShow`; no-ops if
                 // `jupyterlab-search-replace` is unavailable.
                 labShell.activateById(SEARCH_REPLACE_WIDGET_ID);
             }

package/lib/showOutput/index.d.ts

@@ -1,17 +1,8 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Contribute `xtralab:show`: render a single MIME bundle into a main-area
- * panel using the application's render-mime registry.
- *
- * This is the kernel-free counterpart to running a notebook. A coding agent
- * generates the content itself (a Vega-Lite spec, a Markdown explainer, an
- * HTML fragment, an SVG, a base64 image) and hands it to this command, which
- * renders it with the same renderers JupyterLab uses for cell output and docks
- * the result beside the code. Nothing is written to disk and no kernel is
- * required, so it works even where the kernel has no plotting libraries.
- *
- * Repeated calls with the same `id` reuse one panel, so a walkthrough can
- * refresh the view in place instead of piling up tabs.
+ * Contributes `xtralab:show`: render a single MIME bundle into a panel with
+ * the same renderers JupyterLab uses for cell output — no kernel, no file on
+ * disk. Repeated calls with the same `id` reuse one panel.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/showOutput/index.js

@@ -5,23 +5,11 @@ import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { Panel } from '@lumino/widgets';
 import { coerceData } from '../mimeData';
 const PLUGIN_ID = 'xtralab:show-output';
-/**
- * Render arbitrary rich content into a panel, with no notebook and no kernel.
- */
 const SHOW_COMMAND = 'xtralab:show';
 /**
- * Contribute `xtralab:show`: render a single MIME bundle into a main-area
- * panel using the application's render-mime registry.
- *
- * This is the kernel-free counterpart to running a notebook. A coding agent
- * generates the content itself (a Vega-Lite spec, a Markdown explainer, an
- * HTML fragment, an SVG, a base64 image) and hands it to this command, which
- * renders it with the same renderers JupyterLab uses for cell output and docks
- * the result beside the code. Nothing is written to disk and no kernel is
- * required, so it works even where the kernel has no plotting libraries.
- *
- * Repeated calls with the same `id` reuse one panel, so a walkthrough can
- * refresh the view in place instead of piling up tabs.
+ * Contributes `xtralab:show`: render a single MIME bundle into a panel with
+ * the same renderers JupyterLab uses for cell output — no kernel, no file on
+ * disk. Repeated calls with the same `id` reuse one panel.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -32,7 +20,6 @@ const plugin = {
     activate: (app, rendermime, labShell, palette, translator) => {
         const { commands } = app;
         const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
-        // One reusable panel per `id`, so repeated shows refresh in place.
         const panels = new Map();
         commands.addCommand(SHOW_COMMAND, {
             label: trans.__('Show Rich Output'),
@@ -89,16 +76,14 @@ const plugin = {
                 }
                 const model = rendermime.createModel({ data: bundle, trusted: true });
                 const renderer = rendermime.createRenderer(chosen);
-                // A scrollable Panel, not a MainAreaWidget: MainAreaWidget does not lay
-                // out its content in the side area, and the panel needs to scroll when
-                // the content is taller than it (style/showOutput.css).
+                // Not a MainAreaWidget: it does not lay out its content in the side
+                // area; the panel scrolls via style/showOutput.css.
                 const widget = new Panel();
                 widget.addClass('jp-xtralab-ShowPanel');
                 widget.id = `xtralab-show-${id}`;
                 widget.title.label = label;
                 widget.title.closable = true;
                 widget.addWidget(renderer);
-                // Replace any existing panel with this id so shows refresh in place.
                 const existing = panels.get(id);
                 if (existing && !existing.isDisposed) {
                     existing.dispose();
@@ -110,8 +95,7 @@ const plugin = {
                     }
                 });
                 // Attach before rendering so renderers that need layout (Vega) size
-                // correctly. Default to the side area so the editor keeps full width;
-                // only split the document area when `area` is "main".
+                // correctly.
                 if (area === 'main') {
                     labShell.add(widget, 'main', {
                         mode,

package/lib/sidebar/index.d.ts

@@ -1,12 +1,9 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Toggles individual sidebar tabs from View > Appearance > Sidebars,
- * whichever side a tab currently lives on. Hiding detaches the widget
- * (`widget.parent = null`) while keeping the instance for a later
- * re-add; the preference persists in this plugin's settings. Which side
- * a hidden tab came from is only tracked in-memory, so after a reload a
- * re-shown tab lands on the left. The menu placement is contributed
- * declaratively in `schema/sidebar.json`.
+ * Toggles individual sidebar tabs from View > Appearance > Sidebars. Hiding
+ * detaches the widget while keeping the instance for a later re-add; which
+ * side it came from is only tracked in-memory, so after a reload a re-shown
+ * tab lands on the left. Menu placement is declared in schema/sidebar.json.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/sidebar/index.js

@@ -47,13 +47,10 @@ const TARGETS = [
     }
 ];
 /**
- * Toggles individual sidebar tabs from View > Appearance > Sidebars,
- * whichever side a tab currently lives on. Hiding detaches the widget
- * (`widget.parent = null`) while keeping the instance for a later
- * re-add; the preference persists in this plugin's settings. Which side
- * a hidden tab came from is only tracked in-memory, so after a reload a
- * re-shown tab lands on the left. The menu placement is contributed
- * declaratively in `schema/sidebar.json`.
+ * Toggles individual sidebar tabs from View > Appearance > Sidebars. Hiding
+ * detaches the widget while keeping the instance for a later re-add; which
+ * side it came from is only tracked in-memory, so after a reload a re-shown
+ * tab lands on the left. Menu placement is declared in schema/sidebar.json.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -67,8 +64,6 @@ const plugin = {
         // Detached widgets are unreachable via `labShell.widgets(...)`; keep
         // instances here so hidden tabs can be re-added.
         const widgetCache = new Map();
-        // Side each hidden widget was removed from, so re-showing restores it
-        // there.
         const hiddenFrom = new Map();
         const findInSidebars = (id) => {
             for (const area of ['left', 'right']) {
@@ -105,7 +100,6 @@ const plugin = {
             var _a;
             const widget = captureWidget(target.id);
             if (!widget) {
-                // Not seen yet (extension disabled or not added) — nothing to do.
                 return;
             }
             const area = locate(target.id);
@@ -155,8 +149,7 @@ const plugin = {
                             console.error(`xtralab: failed to persist ${target.settingKey}`, reason);
                         }
                     }
-                    // No settings registry (or the write failed): apply in-memory
-                    // for the current session only.
+                    // No settings (or the write failed): apply in-memory for this session.
                     apply(target);
                     commands.notifyCommandChanged(target.command);
                 }

package/lib/terminalNotifications/index.d.ts

@@ -1,15 +1,9 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Turns the notifications coding agents already emit (OSC 9, OSC 777, the bell)
- * into desktop notifications. JupyterLab's xterm renders these sequences but
- * never forwards them to the OS, so this plugin hooks each terminal and bridges
- * them through `window.xtralab.notify` (desktop) or the web Notifications API.
- *
- * A notification is suppressed while its terminal is the focused, active tab,
- * and throttled per terminal. The desktop shell advertises
- * `TERM_PROGRAM=iTerm.app` so agents emit OSC 9 in the first place, and the
- * session name is forwarded so clicking a notification focuses the terminal
- * that fired it.
+ * Turns the OSC 9 / OSC 777 / bell sequences agents emit into desktop
+ * notifications via `window.xtralab.notify` (desktop) or the web Notifications
+ * API — JupyterLab's xterm renders them but never forwards them to the OS.
+ * The desktop shell advertises `TERM_PROGRAM=iTerm.app` so agents emit OSC 9.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/terminalNotifications/index.js

@@ -12,16 +12,10 @@ const OSC_ITERM2_GROWL = 9;
 const OSC_RXVT_NOTIFY = 777;
 const MAX_TEXT_LENGTH = 256;
 /**
- * Turns the notifications coding agents already emit (OSC 9, OSC 777, the bell)
- * into desktop notifications. JupyterLab's xterm renders these sequences but
- * never forwards them to the OS, so this plugin hooks each terminal and bridges
- * them through `window.xtralab.notify` (desktop) or the web Notifications API.
- *
- * A notification is suppressed while its terminal is the focused, active tab,
- * and throttled per terminal. The desktop shell advertises
- * `TERM_PROGRAM=iTerm.app` so agents emit OSC 9 in the first place, and the
- * session name is forwarded so clicking a notification focuses the terminal
- * that fired it.
+ * Turns the OSC 9 / OSC 777 / bell sequences agents emit into desktop
+ * notifications via `window.xtralab.notify` (desktop) or the web Notifications
+ * API — JupyterLab's xterm renders them but never forwards them to the OS.
+ * The desktop shell advertises `TERM_PROGRAM=iTerm.app` so agents emit OSC 9.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -34,12 +28,8 @@ const plugin = {
         const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
         let enabled = true;
         let notifyOnBell = true;
-        // Per-widget throttle timestamps and xterm hooks. WeakMaps let disposed
-        // widgets be collected; hooks are torn down when a tab closes.
         const lastNotified = new WeakMap();
         const hooks = new WeakMap();
-        // True when the user is already looking at this terminal, so a banner would
-        // just be noise.
         const isActivelyViewing = (widget) => document.hasFocus() && app.shell.currentWidget === widget;
         const deliver = (title, body, session) => {
             const bridge = window.xtralab;
@@ -49,7 +39,6 @@ const plugin = {
                 });
                 return;
             }
-            // Plain-browser fallback (pip install): the Web Notifications API.
             if (typeof Notification === 'undefined') {
                 return;
             }
@@ -82,9 +71,8 @@ const plugin = {
         // it, so it reads well as the title for body-only sequences (OSC 9, bell).
         const labelOf = (widget) => widget.title.label || trans.__('Terminal');
         const onOsc9 = (widget, data) => {
-            // OSC 9 is overloaded: ConEmu/Windows Terminal use `9 ; <n> ; …`
-            // subcommands (e.g. `9 ; 4` progress), so skip a numeric-subcommand
-            // payload and leave it unconsumed rather than treat it as a notification.
+            // OSC 9 is overloaded: ConEmu/Windows Terminal use numeric subcommands
+            // (e.g. `9 ; 4` progress); leave those unconsumed.
             if (/^\d+(;|$)/.test(data)) {
                 return false;
             }
@@ -129,8 +117,6 @@ const plugin = {
                     console.warn('xtralab: xterm internals not found; terminal notifications are disabled for this terminal');
                     return;
                 }
-                // Handlers are wrapped so a parse slip cannot break xterm's parser; an
-                // OSC handler returns whether it consumed the sequence.
                 const disposables = [
                     term.onBell(() => guard(() => onBell(widget))),
                     term.parser.registerOscHandler(OSC_ITERM2_GROWL, data => guardOsc(() => onOsc9(widget, data))),

package/lib/terminals/agentTerminals.d.ts

@@ -6,16 +6,23 @@ import type { SessionRegistry } from './model';
 import type { IAgentTerminalSession, IAgentTerminals } from './tokens';
 /**
  * The {@link IAgentTerminals} implementation: a read-only view over the
- * terminals panel's {@link SessionRegistry} narrowed to sessions with a
- * detection-confirmed coding agent, plus the "send a prompt into one"
- * action. Lives in the `xtralab:terminals` plugin so the ask-agent popup
- * (and any future caller) can target running agents without duplicating the
- * detection plumbing.
+ * panel's {@link SessionRegistry} narrowed to sessions with a
+ * detection-confirmed coding agent, plus the "send a prompt into one" action.
  */
 export declare class AgentTerminals implements IAgentTerminals {
     constructor(options: AgentTerminals.IOptions);
+    /**
+     * Snapshot of the sessions with a detection-confirmed running agent.
+     */
     sessions(): IAgentTerminalSession[];
+    /**
+     * A signal emitted whenever the {@link sessions} snapshot may have changed.
+     */
     get changed(): ISignal<IAgentTerminals, void>;
+    /**
+     * Paste the prompt into the named session and press Enter, re-validating
+     * with the server first that an agent still runs there.
+     */
     sendPrompt(name: string, prompt: string): Promise<void>;
     private _findWidget;
     private _onRegistryStateChanged;

package/lib/terminals/agentTerminals.js

@@ -1,32 +1,20 @@
 import { Signal } from '@lumino/signaling';
 import { fetchRunningAgents } from './detection';
 /**
- * Pause between pasting the prompt and pressing Enter, so the two reach the
- * agent as separate PTY reads — the same shape as a human pasting and then
- * submitting. Sent back to back, the server can coalesce both websocket
- * messages into one read and the TUI would have to split the paste from the
- * trailing Enter inside a single chunk.
+ * Pause between pasting the prompt and pressing Enter so the server cannot
+ * coalesce both websocket messages into one PTY read.
  */
 const PASTE_SUBMIT_DELAY_MS = 150;
 /**
- * Bracketed-paste markers (`CSI 200~` / `CSI 201~`). The prompt is wrapped
- * in these so the agent's TUI treats it as one pasted block — newlines
- * insert into its input box instead of submitting the message at each line
- * break. Every send target is a terminal where detection just confirmed a
- * running coding agent, and the agent TUIs keep bracketed-paste mode on.
+ * Bracketed-paste markers (`CSI 200~` / `CSI 201~`): a wrapped prompt arrives
+ * as one pasted block, so newlines insert instead of submitting at each break.
  */
 const PASTE_OPEN = '\x1b[200~';
 const PASTE_CLOSE = '\x1b[201~';
-/**
- * How long to wait for the session's websocket to reach `connected` before
- * failing the send, so a server hiccup surfaces as an error notification
- * rather than a silent hang.
- */
 const CONNECT_TIMEOUT_MS = 10000;
 /**
  * Resolve once `session` reports `connected`; reject with `timeoutMessage`
- * after {@link CONNECT_TIMEOUT_MS}. Matches how the launcher waits before
- * typing into a fresh terminal — writes sent while the websocket is still
+ * after {@link CONNECT_TIMEOUT_MS} — writes sent while the websocket is still
  * connecting disappear silently.
  */
 function waitUntilConnected(session, timeoutMessage) {
@@ -53,11 +41,8 @@ function waitUntilConnected(session, timeoutMessage) {
 }
 /**
  * The {@link IAgentTerminals} implementation: a read-only view over the
- * terminals panel's {@link SessionRegistry} narrowed to sessions with a
- * detection-confirmed coding agent, plus the "send a prompt into one"
- * action. Lives in the `xtralab:terminals` plugin so the ask-agent popup
- * (and any future caller) can target running agents without duplicating the
- * detection plumbing.
+ * panel's {@link SessionRegistry} narrowed to sessions with a
+ * detection-confirmed coding agent, plus the "send a prompt into one" action.
  */
 export class AgentTerminals {
     constructor(options) {
@@ -70,6 +55,9 @@ export class AgentTerminals {
         this._trans = options.trans;
         this._registry.stateChanged.connect(this._onRegistryStateChanged, this);
     }
+    /**
+     * Snapshot of the sessions with a detection-confirmed running agent.
+     */
     sessions() {
         const result = [];
         for (const name of this._registry.sessionNames()) {
@@ -86,14 +74,19 @@ export class AgentTerminals {
         }
         return result;
     }
+    /**
+     * A signal emitted whenever the {@link sessions} snapshot may have changed.
+     */
     get changed() {
         return this._changed;
     }
+    /**
+     * Paste the prompt into the named session and press Enter, re-validating
+     * with the server first that an agent still runs there.
+     */
     async sendPrompt(name, prompt) {
-        // Re-validate against the server rather than trusting the caller's
-        // (possibly seconds-old) snapshot: the prompt is prose, and prose pasted
-        // into the shell prompt left behind by an exited agent would be
-        // *executed* on the Enter below.
+        // Re-validate against the server: prose pasted into the shell prompt an
+        // exited agent left behind would be *executed* on the Enter below.
         await this._terminals.refreshRunning();
         const alive = Array.from(this._terminals.running()).some(model => model.name === name);
         if (!alive) {
@@ -101,47 +94,35 @@ export class AgentTerminals {
         }
         const detected = await fetchRunningAgents(this._detectCommands());
         if (detected === null) {
-            // Detection being unavailable (older server, transient failure) is
-            // not proof the agent is gone; refuse the write with a message that
-            // invites the retry that would succeed.
+            // Detection unavailable (older server, transient failure) is not proof
+            // the agent is gone; refuse the write and invite a retry.
             throw new Error(this._trans.__('Could not verify the terminal — try sending again.'));
         }
         const command = detected[name];
         if (typeof command !== 'string' || !this._isAgentCommand(command)) {
             throw new Error(this._trans.__('No agent is running in that terminal anymore.'));
         }
-        // Deliver in the background: write straight to the session over its
-        // websocket instead of revealing its tab, so focus stays wherever the
-        // user is asking from. An open tab's live connection is reused; a
-        // closed tab gets a short-lived client connection to the running server
-        // session, without creating any widget.
         const widget = this._findWidget(name);
         const session = widget !== null
             ? widget.content.session
             : this._terminals.connectTo({ model: { name } });
         try {
             await waitUntilConnected(session, this._trans.__('Timed out connecting to the terminal.'));
-            // Wrapped and newline-normalised exactly like xterm's own paste
-            // handling. Writing the markers directly (rather than through an open
-            // tab's `Terminal.paste`) also sidesteps the one case paste() gets
-            // wrong: a freshly reconnected xterm whose replayed scrollback no
-            // longer holds the agent's original mode-setting escape, which makes
-            // paste() skip the wrapping the application still expects.
+            // Writing the markers directly (not `Terminal.paste`) sidesteps paste()
+            // skipping them on a reconnected xterm that lost the mode-setting escape.
             session.send({
                 type: 'stdin',
                 content: [PASTE_OPEN + prompt.replace(/\r?\n/g, '\r') + PASTE_CLOSE]
             });
             await new Promise(resolve => window.setTimeout(resolve, PASTE_SUBMIT_DELAY_MS));
             if (session.isDisposed) {
-                // The tab closed during the pause; the pasted text already reached
-                // the agent's input box but Enter can no longer be delivered here.
                 throw new Error(this._trans.__('The terminal closed before the prompt was submitted.'));
             }
             session.send({ type: 'stdin', content: ['\r'] });
         }
         finally {
-            // Close a connection we opened just for this send. Disposing the
-            // client connection leaves the server session (and its agent) running.
+            // Disposing an ad-hoc client connection leaves the server session
+            // (and its agent) running.
             if (widget === null && !session.isDisposed) {
                 session.dispose();
             }

package/lib/terminals/detection.d.ts

@@ -1,11 +1,7 @@
 /**
- * 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.
+ * Ask the xtralab server which of `commands` runs in each open terminal
+ * session: a map from session name to matched command (`null` = idle). Any
+ * failure resolves the whole result to `null` — "detection unavailable",
+ * not "no agents"; callers must not clear badges on it.
  */
 export declare function fetchRunningAgents(commands: string[]): Promise<Record<string, string | null> | null>;

package/lib/terminals/detection.js

@@ -1,14 +1,10 @@
 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.
+ * Ask the xtralab server which of `commands` runs in each open terminal
+ * session: a map from session name to matched command (`null` = idle). Any
+ * failure resolves the whole result to `null` — "detection unavailable",
+ * not "no agents"; callers must not clear badges on it.
  */
 export async function fetchRunningAgents(commands) {
     if (commands.length === 0) {

package/lib/terminals/index.d.ts

@@ -1,39 +1,4 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { IAgentTerminals } from './tokens';
-/**
- * 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".
- */
 declare const plugin: JupyterFrontEndPlugin<IAgentTerminals>;
 export default plugin;