xtralab 0.15.0 → 0.15.2

package/lib/askAgent/index.js

@@ -16,87 +16,31 @@ import { deserializeQueuedPrompts, PromptQueue, serializeQueuedPrompts } from '.
 import { AskAgentQueuePanel } from './queuePanel';
 import { ASK_AGENT_COMMAND, IAskAgent } from './tokens';
 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 = {
     id: PLUGIN_ID,
@@ -115,16 +59,15 @@ const plugin = {
     activate: (app, agentRegistry, palette, translator, agentTerminals, labShell, restorer, state) => {
         const trans = (translator !== null && translator !== void 0 ? 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, value) => {
             state === null || state === void 0 ? void 0 : state.save(key, value).catch(error => {
                 console.error('xtralab: failed to persist ask-agent state', error);
             });
         };
-        // 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 = null;
         let lastTarget = null;
         if (state !== null) {
@@ -152,20 +95,14 @@ const plugin = {
             lastTarget = value;
             saveState(LAST_TARGET_STATE_KEY, value);
         };
-        /**
-         * Agents that can receive an initial prompt on their command line.
-         */
         const promptAgents = () => {
             var _a;
             return ((_a = agentRegistry === null || agentRegistry === void 0 ? void 0 : agentRegistry.agents) !== null && _a !== void 0 ? _a : []).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 = () => {
             var _a;
@@ -194,24 +131,18 @@ const plugin = {
                 pill.style.display = 'none';
             }
         };
-        /**
-         * Open the named terminal's tab (the success toast's call to action).
-         */
         const openTerminal = (name) => {
             app.commands.execute('terminal:open', { name }).catch(reason => {
                 console.error('xtralab: failed to open the terminal', reason);
             });
         };
         /**
-         * 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, prompt, successMessage) => {
             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 {
@@ -234,8 +165,7 @@ const plugin = {
         };
         /**
          * 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, prompt, cwd) => {
             const args = { prompt };
@@ -251,9 +181,8 @@ const plugin = {
                 throw error;
             }
         };
-        // 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 = null;
         let queuePrompt = null;
         if (labShell !== null) {
@@ -261,8 +190,8 @@ const plugin = {
             queue = promptQueue;
             let panel = 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);
@@ -270,12 +199,9 @@ const plugin = {
                 void persistQueue.invoke();
             });
             /**
-             * 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) => {
                 const cwds = new Set(items.map(item => { var _a; return (_a = item.context.cwd) !== null && _a !== void 0 ? _a : ''; }));
@@ -297,13 +223,10 @@ const plugin = {
                 return { prompt: buildBatchPrompt(normalized) };
             };
             /**
-             * 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 = () => {
                 var _a, _b, _c;
@@ -313,8 +236,8 @@ const plugin = {
                 const groups = new Map();
                 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 = item.target.kind === 'session'
@@ -328,9 +251,8 @@ const plugin = {
                 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 = () => {
                         promptQueue.removeMany(items
@@ -359,16 +281,12 @@ const plugin = {
                 }
                 flushing = true;
                 panel === null || panel === void 0 ? void 0 : 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 === null || panel === void 0 ? void 0 : panel.update();
                 });
             };
-            /**
-             * Empty the queue, with an undo toast (typed comments are work).
-             */
             const clearQueue = () => {
                 const removed = promptQueue.items;
                 if (removed.length === 0) {
@@ -380,8 +298,8 @@ const plugin = {
                     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])
                         }
                     ]
@@ -403,12 +321,9 @@ const plugin = {
                     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 === null || agentRegistry === void 0 ? void 0 : agentRegistry.changed.connect(created.update, created);
                     agentTerminals === null || agentTerminals === void 0 ? void 0 : agentTerminals.changed.connect(created.update, created);
                     labShell.add(created, 'right', { rank: 900 });
@@ -428,8 +343,6 @@ const plugin = {
             queuePrompt = (request, target, instruction) => {
                 var _a;
                 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);
                 }
@@ -438,18 +351,14 @@ const plugin = {
                     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.
                 (_a = app.shell.currentWidget) === null || _a === void 0 ? void 0 : _a.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;
                 }
@@ -464,10 +373,8 @@ const plugin = {
                 icon: askAgentIcon,
                 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)
@@ -488,11 +395,8 @@ const plugin = {
             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 = targets.length > 0 ? targets[0].name : null;
             if (storedTarget === NEW_TARGET_VALUE && agents.length > 0) {
@@ -534,9 +438,8 @@ const plugin = {
                     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`.
                         (_a = app.shell.currentWidget) === null || _a === void 0 ? void 0 : _a.activate();
                         const label = (_c = (_b = targets.find(entry => entry.name === target.name)) === null || _b === void 0 ? void 0 : _b.label) !== null && _c !== void 0 ? _c : target.name;
                         deliverToSession(target.name, prompt, trans.__('Prompt sent to %1', label)).catch(() => {
@@ -595,9 +498,8 @@ const plugin = {
             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;
@@ -625,9 +527,6 @@ const plugin = {
                 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 &&
                 ((_a = agentTerminals === null || agentTerminals === void 0 ? void 0 : agentTerminals.sessions()) !== null && _a !== void 0 ? _a : []).length === 0) {
                 hidePill();
@@ -640,9 +539,8 @@ const plugin = {
             }
             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();
@@ -650,8 +548,8 @@ const plugin = {
         }, SELECTION_SETTLE_MS);
         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();
@@ -682,9 +580,8 @@ const plugin = {
                 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();
                 (_a = app.shell.currentWidget) === null || _a === void 0 ? void 0 : _a.activate();
                 return;
@@ -705,7 +602,6 @@ const plugin = {
                 open(request);
             }
         });
-        // One binding per editing surface: file editors and notebooks.
         for (const selector of ['.jp-FileEditor', '.jp-Notebook']) {
             app.commands.addKeyBinding({
                 command: ASK_AGENT_COMMAND,

package/lib/askAgent/popup.d.ts

@@ -4,20 +4,19 @@ import type { IAgent } from '../launcher/agents';
 import { ISessionTarget } from './targetPicker';
 import type { AskAgentTarget, IAskAgentContext } from './tokens';
 /**
- * Short human-readable descriptor of the prompted range, shown in the popup
- * header and the queue panel: file name, notebook cell (when applicable),
- * line range and, for ranges that are not current file content (such as the
- * old side of a diff), a clarifying tag.
+ * Short descriptor of the prompted range for the popup header and the queue
+ * panel: file name, notebook cell, line range and any clarifying tag.
  */
 export declare function contextSummary(context: IAskAgentContext, trans: TranslationBundle): string;
 /**
- * The floating ask-agent prompt box. Hosts {@link AskAgentPopupComponent} in
- * a React root attached to `document.body`; `jp-ThemedContainer` makes
- * JupyterLab's theme variables resolve outside the shell (the omnibox uses
- * the same arrangement).
+ * The floating ask-agent prompt box, attached to `document.body`;
+ * `jp-ThemedContainer` makes theme variables resolve outside the shell.
  */
 export declare class AskAgentPopup extends ReactWidget {
     constructor(options: AskAgentPopup.IOptions);
+    /**
+     * Render the popup content.
+     */
     render(): JSX.Element;
     private _options;
 }
@@ -55,8 +54,7 @@ export declare namespace AskAgentPopup {
          */
         initialTargetName: string | null;
         /**
-         * Number of prompts already queued, shown on the queue button. Only
-         * meaningful together with {@link onQueue}.
+         * Number of prompts already queued, shown on the queue button.
          */
         queueCount?: number;
         /**
@@ -68,15 +66,13 @@ export declare namespace AskAgentPopup {
          */
         onSubmit: (target: AskAgentTarget, instruction: string) => void;
         /**
-         * Add the instruction to the prompt queue instead of sending it, keyed
-         * to the same chosen target (the plugin closes the popup). The queue
-         * button is hidden when omitted.
+         * Queue the instruction for the chosen target instead of sending it.
+         * The queue button is hidden when omitted.
          */
         onQueue?: (target: AskAgentTarget, instruction: string) => void;
         /**
-         * Dismiss the popup (the plugin disposes the widget). `restoreFocus` is
-         * true when the dismissal placed no focus of its own (Escape), asking
-         * the plugin to hand focus back to the widget the ask came from.
+         * Dismiss the popup. `restoreFocus` is true when the dismissal placed
+         * no focus of its own (Escape).
          */
         onCancel: (restoreFocus: boolean) => void;
     }

package/lib/askAgent/popup.js

@@ -3,19 +3,11 @@ import { ReactWidget } from '@jupyterlab/ui-components';
 import { CommandRegistry } from '@lumino/commands';
 import * as React from 'react';
 import { AgentChoices, TargetChips } from './targetPicker';
-/**
- * Gap between the popup and its anchor rectangle, in pixels.
- */
 const ANCHOR_GAP = 6;
-/**
- * Minimum distance kept between the popup and the viewport edges.
- */
 const VIEWPORT_MARGIN = 8;
 /**
- * Short human-readable descriptor of the prompted range, shown in the popup
- * header and the queue panel: file name, notebook cell (when applicable),
- * line range and, for ranges that are not current file content (such as the
- * old side of a diff), a clarifying tag.
+ * Short descriptor of the prompted range for the popup header and the queue
+ * panel: file name, notebook cell, line range and any clarifying tag.
  */
 export function contextSummary(context, trans) {
     var _a;
@@ -43,14 +35,12 @@ function AskAgentPopupComponent(props) {
         const known = agents.find(agent => agent.id === initialAgentId);
         return (_b = (_a = (known !== null && known !== void 0 ? known : agents[0])) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : '';
     });
-    // The running session the prompt goes to, or `null` for a new terminal.
     const [targetName, setTargetName] = React.useState(initialTargetName);
     const [position, setPosition] = React.useState(null);
     const popupRef = React.useRef(null);
     const textareaRef = React.useRef(null);
-    // Place the popup once its size is known: below the anchor, flipped above
-    // when there is no room, clamped into the viewport. Hidden until placed so
-    // the measurement never flashes at the wrong position.
+    // Place the popup once its size is known; hidden until placed so the
+    // measurement never flashes at the wrong position.
     React.useLayoutEffect(() => {
         const node = popupRef.current;
         if (node === null) {
@@ -76,10 +66,8 @@ function AskAgentPopupComponent(props) {
         top = Math.max(VIEWPORT_MARGIN, Math.min(top, viewportHeight - rect.height - VIEWPORT_MARGIN));
         setPosition({ left, top });
     }, [anchor]);
-    // Focus the input only once the popup is placed: while it is still
-    // unpositioned it sits `visibility: hidden`, and hidden elements silently
-    // refuse focus. The empty state renders no textarea; focus the dialog
-    // root itself so it is announced and Escape works without a pointer.
+    // Unpositioned means `visibility: hidden`, and hidden elements refuse focus.
+    // With no textarea (empty state) the dialog root takes focus for Escape.
     React.useEffect(() => {
         var _a, _b;
         if (position !== null) {
@@ -87,14 +75,12 @@ function AskAgentPopupComponent(props) {
         }
     }, [position]);
     const dismiss = React.useCallback((restoreFocus) => {
-        // Defer so unmounting this React root never happens synchronously
-        // inside the event handler that triggered it (same pattern as the
-        // omnibox).
+        // Defer so this React root never unmounts synchronously inside its
+        // own event handler (same pattern as the omnibox).
         window.setTimeout(() => onCancel(restoreFocus), 0);
     }, [onCancel]);
-    // Close when the user clicks anywhere outside the popup. Capture phase so
-    // a click into widgets that swallow events still dismisses it. The click
-    // places focus itself, so none is restored.
+    // Capture phase so a click into event-swallowing widgets still dismisses;
+    // the click places focus itself, so none is restored.
     React.useEffect(() => {
         const onPointerDown = (event) => {
             const node = popupRef.current;
@@ -113,8 +99,6 @@ function AskAgentPopupComponent(props) {
     const selectedSession = targets.find(target => target.name === targetName);
     const canSubmit = instruction.trim().length > 0 &&
         (selectedSession !== undefined || selectedAgent !== undefined);
-    // The destination both actions use: send delivers to it now, queue stamps
-    // it on the queued prompt (still editable in the panel later).
     const resolveTarget = React.useCallback(() => {
         const session = targets.find(entry => entry.name === targetName);
         if (session !== undefined) {
@@ -132,8 +116,7 @@ function AskAgentPopupComponent(props) {
         if (trimmed.length === 0 || target === null) {
             return;
         }
-        // Defer so unmounting this React root never happens synchronously
-        // inside the event handler that triggered it.
+        // Same deferred pattern as dismiss.
         window.setTimeout(() => {
             onSubmit(target, trimmed);
         }, 0);
@@ -153,8 +136,6 @@ function AskAgentPopupComponent(props) {
         if (event.key === 'Escape') {
             event.preventDefault();
             event.stopPropagation();
-            // A keyboard dismissal places no focus of its own; ask the plugin to
-            // hand it back to the widget the ask came from.
             dismiss(true);
         }
     };
@@ -177,9 +158,8 @@ function AskAgentPopupComponent(props) {
     const summary = contextSummary(context, trans);
     const placeholder = trans.__('Describe the change…');
     return (React.createElement("div", { ref: popupRef, className: "jp-xtralab-AskAgent-popup", role: "dialog", "aria-label": trans.__('Ask an agent about %1', summary), 
-        // Focusable so clicks on non-interactive popup content keep focus
-        // inside the dialog (Escape keeps working) and so the empty state
-        // can be focused at all.
+        // Focusable so clicks on non-interactive content keep Escape working
+        // and the empty state can take focus at all.
         tabIndex: -1, style: {
             left: (_a = position === null || position === void 0 ? void 0 : position.left) !== null && _a !== void 0 ? _a : 0,
             top: (_b = position === null || position === void 0 ? void 0 : position.top) !== null && _b !== void 0 ? _b : 0,
@@ -202,10 +182,8 @@ function AskAgentPopupComponent(props) {
                             : trans.__('Ask agent'))))))));
 }
 /**
- * The floating ask-agent prompt box. Hosts {@link AskAgentPopupComponent} in
- * a React root attached to `document.body`; `jp-ThemedContainer` makes
- * JupyterLab's theme variables resolve outside the shell (the omnibox uses
- * the same arrangement).
+ * The floating ask-agent prompt box, attached to `document.body`;
+ * `jp-ThemedContainer` makes theme variables resolve outside the shell.
  */
 export class AskAgentPopup extends ReactWidget {
     constructor(options) {
@@ -215,6 +193,9 @@ export class AskAgentPopup extends ReactWidget {
         this.addClass('jp-xtralab-AskAgent');
         this.addClass('jp-ThemedContainer');
     }
+    /**
+     * Render the popup content.
+     */
     render() {
         return React.createElement(AskAgentPopupComponent, { ...this._options });
     }

package/lib/askAgent/prompt.d.ts

@@ -6,11 +6,9 @@ import type { IAskAgentContext } from './tokens';
  */
 export declare function serverPath(context: IAskAgentContext): string;
 /**
- * Compose the prompt handed to the agent CLI: a one-line locator, the
- * selected snippet in a code fence, then the user's instruction.
- *
- * The scaffold is written in English on purpose — it is consumed by the
- * agent, not shown in the UI, and the agent CLIs are English-first.
+ * Compose the prompt handed to the agent CLI: locator, fenced snippet,
+ * instruction. The scaffold is English on purpose — consumed by the agent,
+ * not shown in the UI.
  */
 export declare function buildPrompt(context: IAskAgentContext, instruction: string): string;
 /**