xtralab 0.15.0 → 0.15.2

package/lib/highlight/index.js

@@ -6,26 +6,16 @@ import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { StateEffect, StateField } from '@codemirror/state';
 import { Decoration, EditorView } from '@codemirror/view';
 const PLUGIN_ID = 'xtralab:highlight';
-/**
- * Highlight a contiguous range of lines, or clear every highlight. These are
- * the only two commands the plugin contributes; both are designed to be driven
- * by a coding agent over the MCP command bridge to walk a user through code.
- */
 const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
 const CLEAR_HIGHLIGHTS_COMMAND = 'xtralab:clear-highlights';
-/**
- * CodeMirror line-decoration class; styled in style/highlight.css.
- */
 const HIGHLIGHT_LINE_CLASS = 'jp-xtralab-highlightLine';
 /**
- * A CodeMirror effect carrying the 1-indexed, inclusive line range to
- * highlight, or `null` to clear the editor's highlights.
+ * Carries the 1-indexed inclusive line range to highlight, or `null` to clear.
  */
 const setHighlight = StateEffect.define();
 /**
- * Holds the highlight decorations for one editor. It is injected lazily (the
- * first time an editor is highlighted) via `StateEffect.appendConfig`, so
- * editors that are never highlighted pay nothing.
+ * Highlight decorations for one editor; injected lazily via
+ * `StateEffect.appendConfig` so editors never highlighted pay nothing.
  */
 const highlightField = StateField.define({
     create: () => Decoration.none,
@@ -54,11 +44,6 @@ const highlightField = StateField.define({
     },
     provide: field => EditorView.decorations.from(field)
 });
-/**
- * Return the CodeMirror view backing a widget's file editor, or `null` when
- * the widget is not a CodeMirror-based text editor (a notebook, a terminal,
- * the settings editor, …).
- */
 function viewForWidget(widget) {
     const content = widget === null || widget === void 0 ? void 0 : widget.content;
     return content instanceof FileEditor &&
@@ -66,25 +51,15 @@ function viewForWidget(widget) {
         ? content.editor.editor
         : null;
 }
-/**
- * Coerce a JSON command argument to a positive integer line number, falling
- * back to `fallback` when it is missing or not a finite number.
- */
 function toLine(value, fallback) {
     const n = Math.trunc(Number(value));
     return Number.isFinite(n) && n >= 1 ? n : fallback;
 }
 /**
- * Contribute `xtralab:highlight-lines` and `xtralab:clear-highlights`.
- *
- * The built-in command surface can open a file (`docmanager:open`) and move
- * the cursor to a line (`fileeditor:go-to-line`), but it cannot persistently
- * highlight a span of lines — `documentsearch:start` only marks text matches
- * and hijacks the find box. This plugin fills that gap with a CodeMirror line
- * decoration, so an agent can point at "lines 31–43 of src/index.ts" while it
- * narrates a walkthrough. `xtralab:highlight-lines` opens the file when needed,
- * scrolls the range into view, and replaces any previous highlight in that
- * editor; `xtralab:clear-highlights` removes every highlight.
+ * Contributes `xtralab:highlight-lines` and `xtralab:clear-highlights`,
+ * filling the persistent span-highlight gap in the core command surface
+ * (`documentsearch:start` only marks text matches and hijacks the find box)
+ * so an agent can point at lines while narrating a walkthrough.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -95,8 +70,6 @@ const plugin = {
     activate: (app, docManager, palette, translator) => {
         const { commands, shell } = app;
         const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
-        // Editors that currently carry a highlight, so a single clear can reach
-        // them all. Disposed editors are dropped on the next clear.
         const highlighted = new Set();
         const ensureField = (view) => {
             if (view.state.field(highlightField, false) === undefined) {
@@ -106,8 +79,7 @@ const plugin = {
         commands.addCommand(HIGHLIGHT_LINES_COMMAND, {
             label: trans.__('Highlight Lines'),
             caption: trans.__('Highlight a range of lines in a text editor'),
-            // Advertise the argument shape so agents listing commands over the MCP
-            // bridge can see how to call it, the same way core commands do.
+            // Advertise the argument shape to agents listing commands over the MCP bridge.
             describedBy: {
                 args: {
                     type: 'object',
@@ -136,9 +108,8 @@ const plugin = {
                 const endLine = toLine(args['endLine'], line);
                 const path = typeof args['path'] === 'string' ? args['path'] : undefined;
                 const reveal = args['reveal'] !== false;
-                // With a path, bind strictly to that document: never fall back to the
-                // active widget, or an explicit path could silently highlight an
-                // unrelated editor that happens to be focused.
+                // With a path, bind strictly to that document — falling back to the
+                // active widget could silently highlight an unrelated editor.
                 let widget;
                 if (path) {
                     // Fail fast on a missing path instead of opening a phantom widget
@@ -153,7 +124,6 @@ const plugin = {
                     if (!opened) {
                         throw new Error(`xtralab: could not open "${path}"`);
                     }
-                    // Wait for the model and the editor view to be ready.
                     await opened.context.ready;
                     await opened.revealed;
                     widget = opened;
@@ -179,7 +149,6 @@ const plugin = {
                     effects.push(EditorView.scrollIntoView(anchor, { y: 'center' }));
                 }
                 view.dispatch({ effects });
-                // Forget editors that have since been closed before tracking this one.
                 for (const tracked of highlighted) {
                     if (!tracked.dom.isConnected) {
                         highlighted.delete(tracked);

package/lib/index.d.ts

@@ -1,12 +1,3 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
-/**
- * Every plugin contributed by `xtralab`. The entry point of the
- * labextension is an array because the package bundles several independent
- * enhancements (file browser, git diff providers, …) — JupyterLab activates
- * each plugin individually and only the ones whose required tokens are
- * available end up running. `gitPlugins` and `launcherPlugins` are themselves
- * arrays (the git diff providers; the launcher plus its editor registry), so
- * they are spread in.
- */
 declare const plugins: JupyterFrontEndPlugin<unknown>[];
 export default plugins;

package/lib/index.js

@@ -20,15 +20,6 @@ import terminalNotificationsPlugin from './terminalNotifications';
 import terminalsPlugin from './terminals';
 import topBarPlugin from './topBar';
 import walkthroughPlugin from './walkthrough';
-/**
- * Every plugin contributed by `xtralab`. The entry point of the
- * labextension is an array because the package bundles several independent
- * enhancements (file browser, git diff providers, …) — JupyterLab activates
- * each plugin individually and only the ones whose required tokens are
- * available end up running. `gitPlugins` and `launcherPlugins` are themselves
- * arrays (the git diff providers; the launcher plus its editor registry), so
- * they are spread in.
- */
 const plugins = [
     aboutPlugin,
     agentSessionsPlugin,

package/lib/launcher/agents.d.ts

@@ -1,95 +1,99 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 /**
- * The shape of an agent card on the launcher. The `command` is the literal
- * text typed into the new terminal session — interactive shells expand
- * aliases, so users can point at `claude`, `cl`, or whatever runs their
- * preferred wrapper.
+ * An agent card on the launcher. `command` is the literal text typed into the
+ * new terminal, so interactive-shell aliases resolve.
  */
 export interface IAgent {
+    /**
+     * Stable id; keys the settings merge and the per-agent launch command.
+     */
     id: string;
+    /**
+     * Card label, e.g. "Claude".
+     */
     label: string;
+    /**
+     * Card tooltip; also the palette command caption.
+     */
     caption: string;
+    /**
+     * The literal command typed into the new terminal.
+     */
     command: string;
+    /**
+     * Brand icon for the card.
+     */
     icon: LabIcon;
+    /**
+     * Sort position among the launcher's agent cards.
+     */
     rank: number;
     /**
-     * When false, the launcher skips the `which`-based availability check for
-     * this entry — useful for aliases or shell functions that aren't on PATH
-     * but still resolve when typed in a real terminal. Defaults to true.
+     * When false, skip the `which`-based availability check — for aliases or
+     * shell functions not on PATH. Defaults to true.
      */
     requireAvailable: boolean;
     /**
-     * Argv tokens spliced between `command` and a shell-quoted prompt when
-     * the user types one into the launcher's prompt box. The semantics:
-     *
-     *   - `[]` → prompt is appended as a positional argument:
-     *     `<command> 'PROMPT'`. (Used by claude, codex, vibe, pi.)
-     *   - `['-i']` / `['--prompt']` → the prompt is preceded by a flag:
-     *     `<command> -i 'PROMPT'`. (Used by copilot, opencode.)
-     *   - `undefined` → the agent does not accept an initial prompt. The
-     *     launcher dims the agent's button while the prompt textarea is
-     *     non-empty, so the user gets a clear signal rather than a silently
-     *     dropped prompt.
-     *
-     * The prompt itself is always single-quoted with embedded single quotes
-     * escaped, so multi-line prompts and shell metacharacters are safe.
+     * Argv tokens spliced between `command` and the shell-quoted prompt:
+     * `[]` appends the prompt positionally, `['-i']` prefixes a flag, and
+     * `undefined` means no prompt support (the launcher dims the button).
      */
     promptArgs?: string[];
 }
 /**
- * The settings-side shape: every field except `id` is optional, so a user
- * can override a single field on a default agent (e.g. swap the command for
- * an alias) without restating the whole entry. New ids define brand-new
- * agent cards.
+ * The settings-side shape: every field except `id` is optional so a user can
+ * override a single field on a default agent; new ids define new agent cards.
  */
 export interface IAgentSettings {
+    /**
+     * Id of the agent to override; a new id defines a new card.
+     */
     id: string;
+    /**
+     * See `IAgent.label`.
+     */
     label?: string;
+    /**
+     * See `IAgent.caption`.
+     */
     caption?: string;
+    /**
+     * See `IAgent.command`.
+     */
     command?: string;
     /**
-     * Inline SVG for a custom agent's icon. Required for new ids whose icon
-     * isn't shipped with xtralab; ignored for default ids unless explicitly
-     * set (in which case it overrides the built-in).
+     * Inline SVG icon. Required for new ids; overrides the built-in when set on
+     * a default id.
      */
     iconSvg?: string;
+    /**
+     * See `IAgent.rank`.
+     */
     rank?: number;
     /**
-     * When false, the agent is hidden from the launcher and the command
-     * palette. Defaults to true.
+     * When false, hides the agent from the launcher and the command palette.
      */
     enabled?: boolean;
     /**
-     * See `IAgent.requireAvailable`. Defaults to true for a built-in agent that
-     * still uses its shipped command, and to false once you override the
-     * `command` (a user-chosen command — often a shell alias — is trusted and
-     * always shown). Set it explicitly to force the check on or off.
+     * See `IAgent.requireAvailable`. Defaults to true, but flips to false once
+     * `command` is overridden (a user-chosen alias is trusted).
      */
     requireAvailable?: boolean;
     /**
-     * See `IAgent.promptArgs`. Pass an empty array to mark the agent as
-     * accepting a positional prompt; pass an array like `["-p"]` to use a
-     * flag. Pass `null` to explicitly turn off prompt support for an agent
-     * that has it on by default.
+     * See `IAgent.promptArgs`. `null` explicitly turns off an agent's default
+     * prompt support.
      */
     promptArgs?: string[] | null;
 }
 /**
- * The built-in agents projected into the JSON settings shape
- * ({@link IAgentSettings}), dropping the runtime-only {@link LabIcon}.
- * {@link registerLauncherSchemaDefaults} injects this as the `agents` setting's
- * schema default so the Settings Editor shows the shipped list.
+ * The built-in agents projected into the settings shape (no runtime LabIcon),
+ * injected as the `agents` schema default so the Settings Editor shows them.
  */
 export declare function defaultAgentSettings(): IAgentSettings[];
 /**
- * Merge xtralab's defaults with the user's settings. Default entries keep
- * their built-in fields unless explicitly overridden; user-only entries are
- * appended. `enabled: false` filters an entry out of the result entirely
- * (so callers don't need to check the flag again).
- *
- * Overriding a built-in agent's `command` also turns its `requireAvailable`
- * off, so the card survives the launcher's `which`-based availability filter
- * even when the new command is a shell alias the server can't resolve. See the
- * built-in branch below for the rationale.
+ * Merge xtralab's defaults with the user's settings: defaults keep their
+ * fields unless overridden, user-only ids are appended, and `enabled: false`
+ * removes an entry entirely. Overriding a built-in's `command` also turns
+ * `requireAvailable` off so an aliased command survives the `which` filter.
  */
 export declare function mergeAgents(overrides: IAgentSettings[]): IAgent[];

package/lib/launcher/agents.js

@@ -1,15 +1,10 @@
 import { LabIcon, terminalIcon } from '@jupyterlab/ui-components';
 import { BUILTIN_AGENT_ICONS } from './icons';
 /**
- * Default agent cards shipped with xtralab. Seven of these (Claude, Codex,
- * Copilot, Goose, OpenCode, Kiro, Mistral Vibe) mirror first-class personas
- * in `jupyter-ai-contrib/jupyter-ai-acp-client` (which is also where their
- * icons come from), but use the bare CLI names a user would type in a
- * terminal rather than the ACP wrapper binaries that project spawns.
- * Antigravity (Google's agent-first IDE/CLI, `agy`) is the Google agent.
- * Pi (https://pi.dev, `earendil-works/pi`) is a minimal extensible coding
- * agent; its mark comes straight from its site. Anything not on the user's
- * `$PATH` is filtered out at activation time, so the wider list is harmless.
+ * Default agent cards. Most mirror `jupyter-ai-contrib/jupyter-ai-acp-client`
+ * personas but use the bare CLI names a user would type, not the ACP wrappers.
+ * Anything not on `$PATH` is filtered out at activation, so the wide list is
+ * harmless.
  */
 const DEFAULTS = [
     {
@@ -40,13 +35,8 @@ const DEFAULTS = [
         icon: BUILTIN_AGENT_ICONS.antigravity,
         rank: 2,
         requireAvailable: true
-        // `agy` is the Antigravity launcher binary — a VS Code-derived editor
-        // CLI that opens the Agent Manager / workspace, not a terminal REPL.
-        // Its positional args are file/folder paths, so there is no inline
-        // natural-language prompt form; like goose/kiro we omit promptArgs so a
-        // typed prompt dims the button instead of being mangled into a path.
-        // The command stays the bare binary (no `agy .`) so the server-side
-        // `shutil.which` availability check still resolves it.
+        // `agy` opens the Antigravity editor; its positional args are paths, not
+        // prompts, and the bare binary keeps the server-side `which` check working.
     },
     {
         id: 'copilot',
@@ -56,8 +46,7 @@ const DEFAULTS = [
         icon: BUILTIN_AGENT_ICONS.copilot,
         rank: 3,
         requireAvailable: true,
-        // `-i "PROMPT"` is the documented way to start interactive mode and
-        // auto-execute the prompt; `-p` exits after responding (non-interactive).
+        // `-i` starts interactive mode with the prompt; `-p` exits after responding.
         promptArgs: ['-i']
     },
     {
@@ -68,8 +57,7 @@ const DEFAULTS = [
         icon: BUILTIN_AGENT_ICONS.goose,
         rank: 4,
         requireAvailable: true
-        // `goose` does not accept an inline interactive prompt; users would
-        // need to type the prompt after `goose session` starts.
+        // `goose` takes no inline prompt; it must be typed after `goose session`.
     },
     {
         id: 'opencode',
@@ -89,8 +77,7 @@ const DEFAULTS = [
         icon: BUILTIN_AGENT_ICONS.kiro,
         rank: 6,
         requireAvailable: true
-        // The Kiro chat session only takes initial prompts via the in-session
-        // `/chat new <prompt>` slash command, not a CLI argument.
+        // Kiro only takes initial prompts via the in-session `/chat new` command.
     },
     {
         id: 'mistral-vibe',
@@ -110,16 +97,12 @@ const DEFAULTS = [
         icon: BUILTIN_AGENT_ICONS.pi,
         rank: 8,
         requireAvailable: true,
-        // `pi [messages...]` starts the interactive TUI and sends the messages
-        // as the first user prompt, so the positional form applies.
         promptArgs: []
     }
 ];
 /**
- * The built-in agents projected into the JSON settings shape
- * ({@link IAgentSettings}), dropping the runtime-only {@link LabIcon}.
- * {@link registerLauncherSchemaDefaults} injects this as the `agents` setting's
- * schema default so the Settings Editor shows the shipped list.
+ * The built-in agents projected into the settings shape (no runtime LabIcon),
+ * injected as the `agents` schema default so the Settings Editor shows them.
  */
 export function defaultAgentSettings() {
     return DEFAULTS.map(agent => {
@@ -131,8 +114,6 @@ export function defaultAgentSettings() {
             rank: agent.rank,
             requireAvailable: agent.requireAvailable
         };
-        // Omit `promptArgs` for agents that don't take an inline prompt, so the
-        // default doesn't show a prompt form they lack.
         if (agent.promptArgs !== undefined) {
             entry.promptArgs = agent.promptArgs;
         }
@@ -147,15 +128,10 @@ function resolveIcon(id, iconSvg) {
     return (_a = BUILTIN_AGENT_ICONS[id]) !== null && _a !== void 0 ? _a : terminalIcon;
 }
 /**
- * Merge xtralab's defaults with the user's settings. Default entries keep
- * their built-in fields unless explicitly overridden; user-only entries are
- * appended. `enabled: false` filters an entry out of the result entirely
- * (so callers don't need to check the flag again).
- *
- * Overriding a built-in agent's `command` also turns its `requireAvailable`
- * off, so the card survives the launcher's `which`-based availability filter
- * even when the new command is a shell alias the server can't resolve. See the
- * built-in branch below for the rationale.
+ * Merge xtralab's defaults with the user's settings: defaults keep their
+ * fields unless overridden, user-only ids are appended, and `enabled: false`
+ * removes an entry entirely. Overriding a built-in's `command` also turns
+ * `requireAvailable` off so an aliased command survives the `which` filter.
  */
 export function mergeAgents(overrides) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
@@ -181,32 +157,14 @@ export function mergeAgents(overrides) {
                 ? resolveIcon(base.id, override.iconSvg)
                 : base.icon,
             rank: (_d = override.rank) !== null && _d !== void 0 ? _d : base.rank,
-            // The availability filter exists to prune xtralab's *built-in* command
-            // from the launcher when it isn't installed. Once the user points the
-            // agent at their own command — e.g. the `ccm` alias wrapping `claude
-            // --effort=max …` — the server's `shutil.which` probe can't see it
-            // (aliases and shell functions only exist inside an interactive shell),
-            // so keeping the check on would wrongly hide the card. We therefore only
-            // require availability while the command is still xtralab's default; a
-            // user-chosen command is trusted and always shown. An explicit
-            // `requireAvailable` still applies to the unchanged default command, so a
-            // user can alias `claude` itself and set `requireAvailable: false` (or
-            // force the check back on).
             requireAvailable: command === base.command
                 ? ((_e = override.requireAvailable) !== null && _e !== void 0 ? _e : base.requireAvailable)
                 : false,
-            // `null` is the explicit way to opt out of an agent's default prompt
-            // support; an absent key keeps the default. `undefined` from `??` is
-            // pruned below.
             promptArgs: override.promptArgs === null
                 ? undefined
                 : ((_f = override.promptArgs) !== null && _f !== void 0 ? _f : base.promptArgs)
         });
     }
-    // What remains in `overrideById` are entries with ids that don't match a
-    // default — treat them as new agents the user is adding. Skip silently
-    // when a required field is missing rather than throwing; the settings
-    // schema validates the shape, so this is just a defensive fallback.
     let nextRank = merged.reduce((max, agent) => Math.max(max, agent.rank), -1) + 1;
     for (const entry of overrideById.values()) {
         if (entry.enabled === false) {

package/lib/launcher/availability.d.ts

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

package/lib/launcher/availability.js

@@ -1,15 +1,9 @@
 import { URLExt } from '@jupyterlab/coreutils';
 import { ServerConnection } from '@jupyterlab/services';
 /**
- * Hit the xtralab server extension's `which`-proxy endpoint and turn the
- * response into a Set of commands that resolved to a real binary on the
- * server's `$PATH`. The frontend uses this set to filter the launcher's
- * agent cards.
- *
- * On any failure (server extension not loaded, network error, malformed
- * response) the returned Set is `null` — callers should treat that as
- * "availability unknown" and either fall back to showing all agents or
- * surface the error, depending on context.
+ * Ask the server extension's `which`-proxy endpoint which commands resolve on
+ * its `$PATH`. Returns `null` on any failure — callers should treat that as
+ * "availability unknown", not as "nothing available".
  */
 export async function fetchAvailableCommands(commands) {
     if (commands.length === 0) {

package/lib/launcher/commands.d.ts

@@ -5,48 +5,23 @@ import type { CommandRegistry } from '@lumino/commands';
 import { type IDisposable } from '@lumino/disposable';
 import type { IAgentSessions } from '../agentSessions';
 import type { IAgent } from './agents';
-/**
- * The command id for opening the launcher.
- */
 export declare const CREATE_LAUNCHER_COMMAND = "launcher:create";
 /**
- * Register a JupyterLab command per agent. Each command opens a new
- * terminal via `terminal:create-new` and feeds the agent's shell command
- * into the fresh session as if the user had typed it.
- *
- * Returns a single disposable that tears down every registered command —
- * the launcher disposes the previous set before re-registering on settings
- * changes so the command palette stays in sync with the configured agents.
- *
- * When an `agentSessions` registry is supplied, each launch tags its terminal
- * session with the agent's command, so the terminals panel can badge the row
- * with the agent's logo immediately (before server-side detection confirms
- * it).
+ * Register a JupyterLab command per agent that opens a new terminal and types
+ * the agent's shell command into it. Returns one disposable tearing down every
+ * command, so a settings change can re-register without stale palette entries.
+ * `agentSessions`, when given, launch-tags each session for the terminals panel.
  */
 export declare function registerAgentCommands(app: JupyterFrontEnd, agents: IAgent[], agentSessions?: IAgentSessions | null): IDisposable;
 /**
  * Open a fresh terminal, type `invocation` into it as if the user had, and
- * label the tab. Shared by the per-agent launch commands and the launcher's
- * editor tile so the fiddly "wait for the websocket, then write stdin"
- * sequence lives in one place.
- *
- * `onSession`, when given, is called once with the new session's name right
- * after the terminal is revealed. Callers use it to optimistically tag the
- * session so the terminals panel can badge it with the agent's (or editor's)
- * logo before server-side detection confirms the running process.
- *
- * Resolves with the host `MainAreaWidget` so the caller can place it — the
- * launcher swaps it into its own tab.
+ * label the tab. `onSession` receives the new session's name so callers can
+ * launch-tag it for the terminals panel. Resolves with the host
+ * `MainAreaWidget` so the caller can place it.
  */
 export declare function launchInTerminal(commands: CommandRegistry, options: {
     cwd?: string;
-    /**
-     * The literal command line typed into the fresh terminal.
-     */
     invocation: string;
-    /**
-     * Tab/title label applied once the command is sent.
-     */
     label: string;
     onSession?: (sessionName: string) => void;
 }): Promise<MainAreaWidget<ITerminal.ITerminal>>;

package/lib/launcher/commands.js

@@ -1,23 +1,12 @@
 import { DisposableSet } from '@lumino/disposable';
 import { buildAgentInvocation } from './invocation';
 import { agentCommandId } from './tokens';
-/**
- * The command id for opening the launcher.
- */
 export const CREATE_LAUNCHER_COMMAND = 'launcher:create';
 /**
- * Register a JupyterLab command per agent. Each command opens a new
- * terminal via `terminal:create-new` and feeds the agent's shell command
- * into the fresh session as if the user had typed it.
- *
- * Returns a single disposable that tears down every registered command —
- * the launcher disposes the previous set before re-registering on settings
- * changes so the command palette stays in sync with the configured agents.
- *
- * When an `agentSessions` registry is supplied, each launch tags its terminal
- * session with the agent's command, so the terminals panel can badge the row
- * with the agent's logo immediately (before server-side detection confirms
- * it).
+ * Register a JupyterLab command per agent that opens a new terminal and types
+ * the agent's shell command into it. Returns one disposable tearing down every
+ * command, so a settings change can re-register without stale palette entries.
+ * `agentSessions`, when given, launch-tags each session for the terminals panel.
  */
 export function registerAgentCommands(app, agents, agentSessions = null) {
     const disposables = new DisposableSet();
@@ -35,9 +24,7 @@ export function registerAgentCommands(app, agents, agentSessions = null) {
                     cwd,
                     invocation,
                     label: agent.label,
-                    // Optimistically tag the session with this agent so the terminals
-                    // panel can show its logo right away; server-side detection takes
-                    // over as the source of truth on its next poll.
+                    // Optimistic tag; server-side detection takes over on its next poll.
                     onSession: name => agentSessions === null || agentSessions === void 0 ? void 0 : agentSessions.set(name, agent.command)
                 });
             }
@@ -48,27 +35,17 @@ export function registerAgentCommands(app, agents, agentSessions = null) {
 }
 /**
  * Open a fresh terminal, type `invocation` into it as if the user had, and
- * label the tab. Shared by the per-agent launch commands and the launcher's
- * editor tile so the fiddly "wait for the websocket, then write stdin"
- * sequence lives in one place.
- *
- * `onSession`, when given, is called once with the new session's name right
- * after the terminal is revealed. Callers use it to optimistically tag the
- * session so the terminals panel can badge it with the agent's (or editor's)
- * logo before server-side detection confirms the running process.
- *
- * Resolves with the host `MainAreaWidget` so the caller can place it — the
- * launcher swaps it into its own tab.
+ * label the tab. `onSession` receives the new session's name so callers can
+ * launch-tag it for the terminals panel. Resolves with the host
+ * `MainAreaWidget` so the caller can place it.
  */
 export async function launchInTerminal(commands, options) {
     const { cwd, invocation, label, onSession } = options;
     const main = (await commands.execute('terminal:create-new', {
         cwd
     }));
-    // `MainAreaWidget.revealed` chains off the `reveal` promise the terminal
-    // extension passes in (the xterm.js widget's own `ready` promise), so
-    // awaiting it guarantees the Terminal widget has finished its constructor
-    // and connected its session listeners.
+    // `revealed` chains off the terminal's `ready` promise, so awaiting it
+    // guarantees the widget finished construction and connected its listeners.
     await main.revealed;
     const session = main.content.session;
     onSession === null || onSession === void 0 ? void 0 : onSession(session.name);
@@ -83,20 +60,12 @@ export async function launchInTerminal(commands, options) {
             type: 'stdin',
             content: [invocation + '\r']
         });
-        // Give the tab and the status-bar list a meaningful default label. The
-        // XTerm widget's `_initialConnection` listener overwrites the title with
-        // `Terminal {N}` when the WebSocket first reports `connected`; we connect
-        // *after* that listener (and call `applyLabel` after `sendCommand`), so by
-        // the time we run the upstream listener has already had its turn. Programs
-        // that publish a real xterm title escape sequence still win —
-        // `XTerm.onTitleChange` resets the label whenever it fires.
+        // XTerm's `_initialConnection` resets the title on first connect; we run
+        // after it, so this label survives. A title escape still wins (`onTitleChange`).
         applyLabel();
     };
-    // Match how the Terminal widget itself sends its `initialCommand`: either
-    // fire immediately if the session is already connected, or wait for the next
-    // `connectionStatusChanged` that flips it to `connected`. Without this the
-    // stdin write races the websocket handshake and the command silently
-    // disappears.
+    // Without waiting for `connected` the stdin write races the websocket
+    // handshake and the command silently disappears.
     if (session.connectionStatus === 'connected') {
         sendCommand();
     }