xtralab 0.15.0 → 0.15.1

package/src/agentSessions.ts

@@ -3,28 +3,14 @@ import { Token } from '@lumino/coreutils';
 import { ISignal, Signal } from '@lumino/signaling';
 
 /**
- * A shared map from a terminal session name to the agent command it was
- * *launched* with (e.g. `claude`).
- *
- * This is the optimistic half of the running-agent badge: when the launcher
- * (or the terminals panel's `+` menu) starts an agent via a
- * `xtralab:start-agent:<id>` command, it records the session here so the
- * panel can show the agent's logo immediately, before the server-side
- * process detection has had a chance to confirm it. Server detection is the
- * authoritative source once it reports on a session; this tag only fills the
- * gap right after launch (and serves as a fallback if detection is
- * unavailable).
- *
- * It exists as its own token, provided by a tiny dependency-free plugin,
- * specifically so the launcher (the writer) and the terminals panel (the
- * reader) can share it without depending on each other — a direct
- * launcher↔terminals token pair would form an activation cycle.
+ * Shared map from terminal session name to the agent command it was launched
+ * with — the optimistic half of the running-agent badge, shown until server
+ * detection confirms. Its own token so the launcher (writer) and terminals
+ * panel (reader) can share it without an activation cycle.
  */
 export interface IAgentSessions {
   /**
-   * The agent command a session was launched with, or `null` if we never
-   * launched an agent into it (e.g. a plain terminal, or one started before
-   * this ran).
+   * The agent command a session was launched with, or `null` if unknown.
    */
   get(sessionName: string): string | null;
 
@@ -34,21 +20,16 @@ export interface IAgentSessions {
   set(sessionName: string, command: string): void;
 
   /**
-   * Forget a session — called when it shuts down so the map stays bounded.
+   * Forget a session so the map stays bounded.
    */
   delete(sessionName: string): void;
 
   /**
-   * Emitted with the affected session name whenever a record is added or
-   * removed, so readers can re-render.
+   * Emitted with the session name whenever a record is added or removed.
    */
   readonly changed: ISignal<IAgentSessions, string>;
 }
 
-/**
- * DI token for {@link IAgentSessions}. Provided by `xtralab:agent-sessions`;
- * consumed (optionally) by both `xtralab:launcher` and `xtralab:terminals`.
- */
 export const IAgentSessions = new Token<IAgentSessions>(
   'xtralab:IAgentSessions',
   'A shared map from terminal session name to the agent command it was launched with.'
@@ -82,9 +63,8 @@ class AgentSessions implements IAgentSessions {
 }
 
 /**
- * Provides {@link IAgentSessions}. Deliberately has no dependencies so it can
- * sit underneath both the launcher and the terminals panel without creating
- * a dependency cycle between them.
+ * Provides {@link IAgentSessions}; dependency-free so it can sit underneath
+ * both the launcher and the terminals panel.
  */
 const plugin: JupyterFrontEndPlugin<IAgentSessions> = {
   id: 'xtralab:agent-sessions',

package/src/askAgent/editorSelection.ts

@@ -8,13 +8,21 @@ import type { Widget } from '@lumino/widgets';
 import type { IAskAgentContext, IAskAgentRequest } from './tokens';
 
 /**
- * A CodeMirror view a selection can be asked about, plus the context needed
- * to describe it to an agent: the document path and, for notebooks, which
- * cell the view belongs to.
+ * A CodeMirror view a selection can be asked about, plus the document path
+ * and, for notebooks, the owning cell.
  */
 interface IEditorTarget {
+  /**
+   * The CodeMirror view holding the selection.
+   */
   view: EditorView;
+  /**
+   * The path of the document the view belongs to.
+   */
   path: string;
+  /**
+   * The index and type of the owning notebook cell; absent for file editors.
+   */
   cell?: {
     index: number;
     type: string;
@@ -22,19 +30,10 @@ interface IEditorTarget {
 }
 
 /**
- * Resolve the CodeMirror view a selection in `widget` would live in, or
- * `null` when the widget holds no such editor. Two widget shapes are
- * recognized:
- *
- * - a notebook panel, where the active cell carries the editor and
- *   `activeCellIndex` names its 0-based position in the nbformat `cells`
- *   array. A rendered markdown cell keeps its (hidden) editor, but a
- *   selection in the rendered HTML never passes {@link domSelectionInView},
- *   so no pill appears there; and
- * - a document widget whose content is a `FileEditor`. The wrapper is not
- *   checked with `instanceof DocumentWidget`: `@jupyterlab/docregistry` is
- *   not a core singleton, so another copy of the class could be in play.
- *   `FileEditor` and `NotebookPanel` come from singleton packages.
+ * Resolve the CodeMirror view a selection in `widget` would live in — the
+ * active notebook cell or a `FileEditor` document — or `null`. The wrapper is
+ * duck-typed, not `instanceof DocumentWidget`: `@jupyterlab/docregistry` is
+ * not a core singleton, unlike `FileEditor` and `NotebookPanel`.
  */
 export function resolveEditorTarget(
   widget: Widget | null
@@ -63,10 +62,8 @@ export function resolveEditorTarget(
 }
 
 /**
- * Whether the current DOM selection lives inside `view`. Guards the
- * selection-change listener against selections made elsewhere (a terminal,
- * a sidebar, another notebook cell) while the widget owning `view` happens
- * to be the shell's current widget.
+ * Whether the current DOM selection lives inside `view`; guards against
+ * selections made elsewhere while the owning widget is current.
  */
 export function domSelectionInView(
   view: EditorView,
@@ -80,12 +77,9 @@ export function domSelectionInView(
 
 /**
  * Build an ask-agent request from the current selection in the shell's
- * current widget — a file editor or the active notebook cell — or return
- * `null` when that widget holds no CodeMirror document editor.
- *
- * With `allowEmpty`, a collapsed selection falls back to the cursor's line
- * (used by the command/shortcut path so it works without a mouse
- * selection); otherwise an empty selection yields `null`.
+ * current widget, or `null` when it holds no CodeMirror document editor.
+ * With `allowEmpty`, a collapsed selection falls back to the cursor's line;
+ * otherwise it yields `null`.
  */
 export function editorAskRequest(
   app: JupyterFrontEnd,
@@ -110,15 +104,14 @@ export function editorAskRequest(
     endLine = startLine;
     text = state.doc.lineAt(main.from).text;
   } else {
-    // A selection that ends exactly at the start of a line (the common
-    // "drag over whole lines" gesture) should not count that line.
+    // A selection ending exactly at a line start (the whole-line drag
+    // gesture) should not count that line.
     const endPos =
       main.to === state.doc.lineAt(main.to).from ? main.to - 1 : main.to;
     endLine = state.doc.lineAt(endPos).number;
     text = state.sliceDoc(main.from, main.to);
   }
 
-  // Anchor the popup at the selection head (where the cursor ended up).
   // `coordsAtPos` returns `null` for positions scrolled out of view.
   const coords = view.coordsAtPos(main.head);
   const anchor = coords

package/src/askAgent/icons.ts

@@ -1,9 +1,8 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 
 /**
- * Four-point sparkle used by the ask-agent affordances (selection pill,
- * command palette entry). Drawn in-repo; the `jp-icon3` class lets the
- * active theme recolor the glyph like other JupyterLab UI icons.
+ * Four-point sparkle used by the ask-agent affordances; the `jp-icon3`
+ * class lets the active theme recolor the glyph.
  */
 export const askAgentIcon = new LabIcon({
   name: 'xtralab:ask-agent',

package/src/askAgent/index.ts

@@ -43,99 +43,43 @@ import {
 
 const PLUGIN_ID = 'xtralab:ask-agent';
 
-/**
- * Command id that reveals the queued-prompts panel.
- */
 const QUEUE_PANEL_COMMAND = 'xtralab:ask-agent-queue';
 
-/**
- * Widget id of the queued-prompts side panel.
- */
 const QUEUE_PANEL_ID = 'xtralab-ask-agent-queue';
 
-/**
- * State-database key remembering the last agent picked in the popup.
- */
 const LAST_AGENT_STATE_KEY = 'xtralab:ask-agent:agent';
 
-/**
- * State-database key remembering the last target picked in the popup.
- */
 const LAST_TARGET_STATE_KEY = 'xtralab:ask-agent:target';
 
-/**
- * State-database key holding the queued prompts across page loads.
- */
 const QUEUE_STATE_KEY = 'xtralab:ask-agent:queue';
 
-/**
- * Debounce for mirroring the queue into the state database, so typing in
- * the panel's textareas does not issue a write per keystroke.
- */
 const QUEUE_PERSIST_MS = 500;
 
-/**
- * Stored target value for "start the agent in a new terminal".
- */
 const NEW_TARGET_VALUE = 'new';
 
-/**
- * Stored-target prefix for an existing session; the session name follows.
- */
 const SESSION_TARGET_PREFIX = 'session:';
 
 /**
- * Delay between a selection change and showing the pill, so the affordance
- * appears once the selection settles rather than flickering along a drag.
+ * Delay before showing the pill, so it does not flicker along a drag.
  */
 const SELECTION_SETTLE_MS = 250;
 
 /**
- * Keystroke that opens the popup in a file editor. `Accel I` would be the
- * familiar "inline chat" chord but CodeMirror's default keymap owns `Mod-i`
- * (selectParentSyntax) inside editors and prevents-default before Lumino
- * sees it; `Accel .` — the "quick fix" chord elsewhere — is free in the
- * editor, the browser and JupyterLab.
+ * `Accel I` would be the familiar "inline chat" chord but CodeMirror's
+ * default keymap owns `Mod-i` and prevents-default before Lumino sees it;
+ * `Accel .` is free in the editor, the browser and JupyterLab.
  */
 const ASK_AGENT_KEYS = 'Accel .';
 
-/**
- * Gap between the pill and the selection anchor, in pixels.
- */
 const PILL_GAP = 6;
 
-/**
- * Minimum distance kept between the pill and the viewport edges.
- */
 const PILL_VIEWPORT_MARGIN = 8;
 
 /**
- * Select code in a file editor (or pick diff lines) and prompt a coding
- * agent about it.
- *
- * The plugin watches the document selection: a non-empty selection inside a
- * CodeMirror file editor or notebook cell grows a small floating "Ask agent"
- * pill next to the selection. Clicking it (or running `xtralab:ask-agent`,
- * bound to Accel+. in editors and notebooks) opens a popup where the user
- * types an instruction, picks one of the launcher's agents and picks where
- * the prompt goes; submitting either starts that agent in a fresh terminal
- * via `xtralab:start-agent:<id>`, or pastes the prompt into an agent already
- * running in one of the open terminal sessions (via `IAgentTerminals`; the
- * agent CLIs queue prompts that arrive while they are busy). Sends to a
- * running agent stay in the background — focus never leaves the editor, and
- * a success toast offers to open the terminal. Either way the prompt embeds
- * the file path, cell index for notebooks, line range and selected snippet.
- *
- * The popup's Queue button (or Accel+Enter) defers the send instead: the
- * comment lands in a persistent queue, stamped with the popup's selected
- * destination — every queued prompt is independent and may aim at a
- * different agent or session. A right-sidebar panel reviews the queue
- * (edit, retarget, remove) and flushes it in one go, combining prompts that
- * share a destination into a single numbered message. The queue survives
- * page reloads.
- *
- * The same popup is provided on the `IAskAgent` token so the git diff
- * viewers can open it for a selected diff line range.
+ * Prompt a coding agent about selected code: a pill/popup over editor,
+ * notebook-cell and git-diff selections sends the instruction to a fresh
+ * agent terminal or into a running one, or defers it into a persistent
+ * queue reviewed in a right-sidebar panel and flushed as one batch.
  */
 const plugin: JupyterFrontEndPlugin<IAskAgent> = {
   id: PLUGIN_ID,
@@ -165,8 +109,7 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
     const trans = (translator ?? nullTranslator).load('jupyterlab');
 
     /**
-     * Best-effort write to the state database; a failure only loses the
-     * convenience of restoring this value on the next page load.
+     * Best-effort state-database write; a failure only loses a restored default.
      */
     const saveState = (key: string, value: ReadonlyPartialJSONValue): void => {
       state?.save(key, value).catch(error => {
@@ -174,8 +117,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       });
     };
 
-    // The last-used picks, restored asynchronously from the state database
-    // and kept in memory so the popup can read them synchronously.
+    // Last-used picks, restored asynchronously but read synchronously by
+    // the popup.
     let lastAgentId: string | null = null;
     let lastTarget: string | null = null;
     if (state !== null) {
@@ -206,21 +149,15 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       saveState(LAST_TARGET_STATE_KEY, value);
     };
 
-    /**
-     * Agents that can receive an initial prompt on their command line.
-     */
     const promptAgents = (): IAgent[] =>
       (agentRegistry?.agents ?? []).filter(
         agent => agent.promptArgs !== undefined
       );
 
     /**
-     * Running agent terminals offered as prompt targets, each resolved to
-     * its agent's icon the same way the terminals panel badges its rows
-     * (matching either the configured command or the canonical id, falling
-     * back to the plain terminal icon when the agent has since been removed
-     * from the settings). Unlike {@link promptAgents} this does not require
-     * `promptArgs`: pasting into a running TUI needs no command-line recipe.
+     * Running agent terminals offered as prompt targets, badged with the
+     * matching agent's icon like the terminals panel (configured command or
+     * canonical id). Pasting into a running TUI needs no `promptArgs`.
      */
     const sessionTargets = (): ISessionTarget[] =>
       (agentTerminals?.sessions() ?? []).map(session => ({
@@ -252,9 +189,6 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       }
     };
 
-    /**
-     * Open the named terminal's tab (the success toast's call to action).
-     */
     const openTerminal = (name: string): void => {
       app.commands.execute('terminal:open', { name }).catch(reason => {
         console.error('xtralab: failed to open the terminal', reason);
@@ -262,10 +196,9 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
     };
 
     /**
-     * Paste `prompt` into the running agent in session `name`. Delivery is
-     * background — focus stays where it is — so `successMessage` is toasted
-     * with an "Open" action instead. Failures are toasted too; the promise
-     * still rejects so callers can chain their own cleanup to success only.
+     * Paste `prompt` into the running agent in session `name`, in the
+     * background. Failures are toasted but still reject, so callers can
+     * chain their own cleanup to success only.
      */
     const deliverToSession = async (
       name: string,
@@ -273,8 +206,6 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       successMessage: string
     ): Promise<void> => {
       if (agentTerminals === null) {
-        // Session targets are only offered when the terminals plugin is
-        // present; fail loudly rather than resolving as a delivered send.
         throw new Error('xtralab: agent terminals are unavailable');
       }
       try {
@@ -303,8 +234,7 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
 
     /**
      * Start `agentId` in a fresh terminal with `prompt` on its command
-     * line. Failures are toasted; the promise still rejects so callers can
-     * chain their own cleanup to success only.
+     * line. Failures are toasted but still reject.
      */
     const startAgentTerminal = async (
       agentId: string,
@@ -327,9 +257,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       }
     };
 
-    // The queue feature needs a side area to dock the review panel into, so
-    // everything below stays off (and the popup hides its Queue button)
-    // without the full Lab shell.
+    // The queue needs a side area for its review panel, so it stays off
+    // (and the popup hides its Queue button) without the full Lab shell.
     let queue: PromptQueue | null = null;
     let queuePrompt:
       | ((
@@ -345,8 +274,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       let panel: AskAgentQueuePanel | null = null;
       let flushing = false;
 
-      // Mirror every queue change into the state database, debounced so
-      // typing in the panel's textareas does not write on each keystroke.
+      // Debounced so typing in the panel's textareas does not write on
+      // each keystroke.
       const persistQueue = new Debouncer(() => {
         saveState(QUEUE_STATE_KEY, serializeQueuedPrompts(promptQueue.items));
       }, QUEUE_PERSIST_MS);
@@ -355,12 +284,9 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       });
 
       /**
-       * The prompt (and working directory) for a batch sent to a new
-       * terminal. When every item agrees on a repository root the terminal
-       * starts there and the item paths stay relative to it; a mixed batch
-       * starts at the server root instead, with every locator rewritten to
-       * a server-relative path so none of them depends on the terminal's
-       * cwd.
+       * The prompt (and cwd) for a batch sent to a new terminal: a shared
+       * repository root becomes the cwd; a mixed batch starts at the server
+       * root with every locator rewritten server-relative instead.
        */
       const newTerminalBatch = (
         items: readonly IQueuedPrompt[]
@@ -385,13 +311,10 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       };
 
       /**
-       * Flush the queue: prompts are grouped by destination — every prompt
-       * is independent and may target a different agent or session — and
-       * each group goes out as one numbered message. A group's prompts
-       * leave the queue only when its delivery succeeds, so one dead
-       * session never loses the comments aimed elsewhere. One flush runs
-       * at a time — deliveries span server round trips, and a second click
-       * meanwhile would re-send every still-queued group.
+       * Flush the queue: prompts are grouped by destination and each group
+       * goes out as one numbered message, leaving the queue only when its
+       * delivery succeeds. One flush at a time — a second click mid-flight
+       * would re-send every still-queued group.
        */
       const sendQueue = (): void => {
         if (flushing) {
@@ -403,8 +326,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
         >();
         for (const item of promptQueue.items) {
           if (item.target === null) {
-            // The panel disables sending while a target is missing; skip
-            // defensively if a send races a target loss.
+            // The panel disables sending without a target; skip if a send
+            // races a target loss.
             continue;
           }
           const key =
@@ -419,9 +342,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
         for (const { target, items } of groups.values()) {
           /**
            * Remove the delivered prompts — except any edited or retargeted
-           * while the send was in flight: an edit makes a new object, so
-           * identity is the "unchanged" check, and the edited prompt stays
-           * queued for the next flush instead of being dropped unsent.
+           * in flight: an edit makes a new object, so identity is the
+           * "unchanged" check and the edited prompt stays queued.
            */
           const delivered = (): void => {
             promptQueue.removeMany(
@@ -466,17 +388,13 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
         }
         flushing = true;
         panel?.update();
-        // Every delivery caught its own failure above, so this resolves
-        // once all groups have settled either way.
+        // Every delivery caught its own failure, so this settles either way.
         void Promise.all(deliveries).then(() => {
           flushing = false;
           panel?.update();
         });
       };
 
-      /**
-       * Empty the queue, with an undo toast (typed comments are work).
-       */
       const clearQueue = (): void => {
         const removed = promptQueue.items;
         if (removed.length === 0) {
@@ -494,8 +412,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
             actions: [
               {
                 label: trans.__('Undo'),
-                // Prompts queued after the clear are newer; keep them,
-                // after the restored ones.
+                // Prompts queued after the clear are newer; keep them after
+                // the restored ones.
                 callback: () =>
                   promptQueue.reset([...removed, ...promptQueue.items])
               }
@@ -520,12 +438,9 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
           created.title.icon = askAgentIcon;
           created.title.label = trans.__('Prompt Queue');
           created.title.caption = trans.__('Queued ask-agent prompts');
-          // Closable so it gets a close button if the user drags it out of
-          // the side area; closing disposes it, and it is recreated on
-          // demand (same arrangement as the walkthrough panel).
+          // Closable so it gets a close button when dragged out of the side
+          // area; closing disposes it and it is recreated on demand.
           created.title.closable = true;
-          // The panel re-renders on queue changes itself; the chips also
-          // mirror the live agent list and terminal sessions.
           agentRegistry?.changed.connect(created.update, created);
           agentTerminals?.changed.connect(created.update, created);
           labShell.add(created, 'right', { rank: 900 });
@@ -546,8 +461,6 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
 
       queuePrompt = (request, target, instruction) => {
         const wasEmpty = promptQueue.items.length === 0;
-        // Queueing is a target choice like sending: remember it for the
-        // next popup's preselection.
         if (target.kind === 'session') {
           rememberTarget(SESSION_TARGET_PREFIX + target.name);
         } else {
@@ -555,18 +468,14 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
           rememberTarget(NEW_TARGET_VALUE);
         }
         promptQueue.add(request.context, instruction, target);
-        // Queueing is background like a session send: hand focus straight
-        // back to the widget the ask came from.
         app.shell.currentWidget?.activate();
         const queuePanel = ensurePanel();
         if (queuePanel.isVisible) {
-          // The list visibly grows; no extra feedback needed.
           return;
         }
         if (wasEmpty) {
-          // First prompt of a batch: reveal the panel once, so the user
-          // sees where queued prompts accumulate. Later additions respect
-          // a deliberately closed sidebar and toast instead.
+          // Reveal the panel once for the first prompt; later additions
+          // respect a deliberately closed sidebar and toast instead.
           labShell.activateById(queuePanel.id);
           return;
         }
@@ -592,10 +501,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
         execute: revealPanel
       });
 
-      // Restore the queue persisted by a previous page load. Anything
-      // queued before the fetch resolves is newer and stays, after the
-      // restored prompts. A restored queue should be discoverable without
-      // queueing anything new, so its sidebar tab is recreated (collapsed).
+      // Prompts queued before the fetch resolves are newer and stay, after
+      // the restored ones; the tab is recreated so the restore is discoverable.
       if (state !== null) {
         void state
           .fetch(QUEUE_STATE_KEY)
@@ -617,11 +524,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       closePopup();
       const agents = promptAgents();
       const targets = sessionTargets();
-      // Preselect where the prompt goes. Queueing into a running agent is
-      // the common follow-up loop, so a live session wins by default — the
-      // last-used one when it is still running, otherwise the first — unless
-      // the user explicitly chose a new terminal last time (and one can
-      // still be started).
+      // Preselect: a live session wins (last-used if still running, else the
+      // first) unless a new terminal was last chosen and can still start.
       const storedTarget = lastTarget;
       let initialTargetName: string | null =
         targets.length > 0 ? targets[0].name : null;
@@ -664,9 +568,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
           const prompt = buildPrompt(request.context, instruction);
           if (target.kind === 'session') {
             rememberTarget(SESSION_TARGET_PREFIX + target.name);
-            // The send is background, so hand focus straight back to the
-            // widget the ask came from (the editor or diff under the popup);
-            // disposing the popup alone would drop it on `document.body`.
+            // The send is background: hand focus back to the widget the ask
+            // came from — disposing the popup alone drops it on `document.body`.
             app.shell.currentWidget?.activate();
             const label =
               targets.find(entry => entry.name === target.name)?.label ??
@@ -738,9 +641,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       const button = ensurePill();
       pillRequest = request;
       button.style.display = 'flex';
-      // Measure after display so the rect is real, then sit the pill just
-      // above the selection head (below it when that would leave the
-      // viewport).
+      // Measure after display so the rect is real; the pill sits above the
+      // selection head, below it when that would leave the viewport.
       const rect = button.getBoundingClientRect();
       let left = anchor.left;
       let top = anchor.top - rect.height - PILL_GAP;
@@ -773,9 +675,6 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
         hidePill();
         return;
       }
-      // The popup can send somewhere as long as an agent takes a prompt on
-      // its command line (new terminal) or one is already running (existing
-      // session) — only with neither is there nothing to offer.
       if (
         promptAgents().length === 0 &&
         (agentTerminals?.sessions() ?? []).length === 0
@@ -791,9 +690,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       showPill(request);
     };
 
-    // Each invocation resets the timer, so evaluation runs once the
-    // selection has settled. Mid-drag the selection is still moving; the
-    // pointerup listener invokes it again once the drag ends.
+    // Mid-drag the selection is still moving; the pointerup listener
+    // re-invokes once the drag ends.
     const settled = new Debouncer(() => {
       if (!pointerIsDown) {
         evaluateSelection();
@@ -802,8 +700,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
 
     document.addEventListener('selectionchange', () => {
       if (popup !== null) {
-        // Typing in the popup's textarea moves the document selection; the
-        // pill must not resurface underneath the open popup.
+        // Typing in the popup moves the document selection; the pill must
+        // not resurface underneath it.
         return;
       }
       hidePill();
@@ -845,9 +743,8 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
         return;
       }
       if (popup !== null) {
-        // Focus is outside the popup — its own key handler consumes Escape
-        // when focus is inside — so close it here and hand focus back to
-        // the widget the ask came from.
+        // The popup's own handler consumes Escape while focus is inside it;
+        // here focus is elsewhere, so close and restore focus.
         closePopup();
         app.shell.currentWidget?.activate();
         return;
@@ -875,7 +772,6 @@ const plugin: JupyterFrontEndPlugin<IAskAgent> = {
       }
     });
 
-    // One binding per editing surface: file editors and notebooks.
     for (const selector of ['.jp-FileEditor', '.jp-Notebook']) {
       app.commands.addKeyBinding({
         command: ASK_AGENT_COMMAND,