xtralab 0.14.1 → 0.15.1

package/src/terminals/agentTerminals.ts

@@ -8,35 +8,23 @@ import type { SessionRegistry, TerminalWidget } from './model';
 import type { IAgentTerminalSession, IAgentTerminals } from './tokens';
 
 /**
- * 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 = 10_000;
 
 /**
  * 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(
@@ -67,11 +55,8 @@ function waitUntilConnected(
 
 /**
  * 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 implements IAgentTerminals {
   constructor(options: AgentTerminals.IOptions) {
@@ -84,6 +69,9 @@ export class AgentTerminals implements IAgentTerminals {
     this._registry.stateChanged.connect(this._onRegistryStateChanged, this);
   }
 
+  /**
+   * Snapshot of the sessions with a detection-confirmed running agent.
+   */
   sessions(): IAgentTerminalSession[] {
     const result: IAgentTerminalSession[] = [];
     for (const name of this._registry.sessionNames()) {
@@ -101,15 +89,20 @@ export class AgentTerminals implements IAgentTerminals {
     return result;
   }
 
+  /**
+   * A signal emitted whenever the {@link sessions} snapshot may have changed.
+   */
   get changed(): ISignal<IAgentTerminals, void> {
     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: string, prompt: string): Promise<void> {
-    // 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
@@ -119,9 +112,8 @@ export class AgentTerminals implements IAgentTerminals {
     }
     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.')
       );
@@ -133,11 +125,6 @@ export class AgentTerminals implements IAgentTerminals {
       );
     }
 
-    // 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
@@ -148,12 +135,8 @@ export class AgentTerminals implements IAgentTerminals {
         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]
@@ -162,16 +145,14 @@ export class AgentTerminals implements IAgentTerminals {
         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();
       }
@@ -209,27 +190,22 @@ export namespace AgentTerminals {
      * The panel's session registry — the source of the session snapshot.
      */
     registry: SessionRegistry;
-
     /**
      * Tracker of open terminal widgets, to reuse an open tab's connection.
      */
     tracker: ITerminalTracker;
-
     /**
      * The terminal session manager, for validation and ad-hoc connections.
      */
     terminals: Terminal.IManager;
-
     /**
      * Names to detect — same list the registry polls with.
      */
     detectCommands: () => string[];
-
     /**
      * Whether a detected command belongs to a coding agent (not an editor).
      */
     isAgentCommand: (command: string) => boolean;
-
     /**
      * Translation bundle for the error messages thrown to callers.
      */

package/src/terminals/detection.ts

@@ -2,14 +2,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: string[]

package/src/terminals/index.ts

@@ -3,7 +3,11 @@ import {
   JupyterFrontEnd,
   JupyterFrontEndPlugin
 } from '@jupyterlab/application';
-import { Dialog, showDialog } from '@jupyterlab/apputils';
+import {
+  Dialog,
+  IMovableSectionRegistry,
+  showDialog
+} from '@jupyterlab/apputils';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { ITerminalTracker } from '@jupyterlab/terminal';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
@@ -19,39 +23,6 @@ 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 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.
- *
- * 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: JupyterFrontEndPlugin<IAgentTerminals> = {
   id: PLUGIN_ID,
   description:
@@ -65,7 +36,8 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
     IAgentRegistry,
     IEditorRegistry,
     IAgentSessions,
-    ISettingRegistry
+    ISettingRegistry,
+    IMovableSectionRegistry
   ],
   activate: (
     app: JupyterFrontEnd,
@@ -75,17 +47,13 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
     agentRegistry: IAgentRegistry | null,
     editorRegistry: IEditorRegistry | null,
     agentSessions: IAgentSessions | null,
-    settingRegistry: ISettingRegistry | null
+    settingRegistry: ISettingRegistry | null,
+    movableSections: IMovableSectionRegistry | null
   ): IAgentTerminals => {
     const trans = (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: string | null): LabIcon => {
       if (!command) {
         return terminalIcon;
@@ -96,21 +64,12 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
       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?.editors.find(
         e => e.command === command || e.id === command
       );
       return editor?.icon ?? 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 = (): string[] => {
       const names = new Set<string>();
       for (const agent of agentRegistry?.agents ?? []) {
@@ -124,10 +83,6 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
       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: string): boolean =>
       agentRegistry?.agents.some(
         a => a.command === command || a.id === command
@@ -136,19 +91,14 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
     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 = (): void => {
       tracker.forEach(widget => {
         const session = widget.content.session;
@@ -164,10 +114,8 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
     syncTabIcons();
 
     const onActivate = (name: string): void => {
-      // `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 });
     };
 
@@ -180,10 +128,6 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
     };
 
     const onShutdownAll = (): void => {
-      // 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.__(
@@ -206,19 +150,8 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
         });
     };
 
-    // 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: MenuSvg | null = null;
     const onCreate = (anchor: { x: number; y: number }): void => {
       const agents = agentRegistry?.agents ?? [];
@@ -248,23 +181,23 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
       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);
     }
 
-    // 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.
+    void app.restored.then(() => {
+      panel.expandOwnSection();
+    });
+
+    if (movableSections) {
+      movableSections.registerSource(PLUGIN_ID, trans.__('Terminals'), panel);
+      movableSections.registerTarget(PLUGIN_ID, trans.__('Terminals'), panel);
+      panel.announceSections();
+    }
+
     if (settingRegistry) {
       settingRegistry
         .load(PLUGIN_ID)
@@ -275,9 +208,8 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
             );
           };
           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 => {
@@ -299,9 +231,6 @@ const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
   }
 };
 
-/**
- * Read a boolean setting value, falling back when it is missing or invalid.
- */
 function boolOption(value: unknown, fallback: boolean): boolean {
   return typeof value === 'boolean' ? value : fallback;
 }