xtralab 0.15.0 → 0.15.1

package/src/askAgent/popup.tsx

@@ -9,21 +9,13 @@ import type { IAgent } from '../launcher/agents';
 import { AgentChoices, ISessionTarget, TargetChips } from './targetPicker';
 import type { AskAgentTarget, IAskAgentContext } from './tokens';
 
-/**
- * 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: IAskAgentContext,
@@ -66,7 +58,6 @@ function AskAgentPopupComponent(props: AskAgentPopup.IOptions): JSX.Element {
     const known = agents.find(agent => agent.id === initialAgentId);
     return (known ?? agents[0])?.id ?? '';
   });
-  // The running session the prompt goes to, or `null` for a new terminal.
   const [targetName, setTargetName] = React.useState<string | null>(
     initialTargetName
   );
@@ -77,9 +68,8 @@ function AskAgentPopupComponent(props: AskAgentPopup.IOptions): JSX.Element {
   const popupRef = React.useRef<HTMLDivElement>(null);
   const textareaRef = React.useRef<HTMLTextAreaElement>(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) {
@@ -111,10 +101,8 @@ function AskAgentPopupComponent(props: AskAgentPopup.IOptions): JSX.Element {
     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(() => {
     if (position !== null) {
       (textareaRef.current ?? popupRef.current)?.focus();
@@ -123,17 +111,15 @@ function AskAgentPopupComponent(props: AskAgentPopup.IOptions): JSX.Element {
 
   const dismiss = React.useCallback(
     (restoreFocus: boolean) => {
-      // 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: PointerEvent): void => {
       const node = popupRef.current;
@@ -157,8 +143,6 @@ function AskAgentPopupComponent(props: AskAgentPopup.IOptions): JSX.Element {
     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((): AskAgentTarget | null => {
     const session = targets.find(entry => entry.name === targetName);
     if (session !== undefined) {
@@ -177,8 +161,7 @@ function AskAgentPopupComponent(props: AskAgentPopup.IOptions): JSX.Element {
     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);
@@ -200,8 +183,6 @@ function AskAgentPopupComponent(props: AskAgentPopup.IOptions): JSX.Element {
     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);
     }
   };
@@ -234,9 +215,8 @@ function AskAgentPopupComponent(props: AskAgentPopup.IOptions): JSX.Element {
       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: position?.left ?? 0,
@@ -324,10 +304,8 @@ function AskAgentPopupComponent(props: AskAgentPopup.IOptions): JSX.Element {
 }
 
 /**
- * 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: AskAgentPopup.IOptions) {
@@ -338,6 +316,9 @@ export class AskAgentPopup extends ReactWidget {
     this.addClass('jp-ThemedContainer');
   }
 
+  /**
+   * Render the popup content.
+   */
   render(): JSX.Element {
     return <AskAgentPopupComponent {...this._options} />;
   }
@@ -379,8 +360,7 @@ export 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;
     /**
@@ -392,15 +372,13 @@ export 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/src/askAgent/prompt.ts

@@ -14,10 +14,8 @@ export function serverPath(context: IAskAgentContext): string {
 }
 
 /**
- * Cap on the snippet embedded in the prompt, in characters. The path and
- * line range are the authoritative pointers — agents open the file
- * themselves — so a very long selection is trimmed instead of being typed
- * into the terminal wholesale.
+ * Cap on the embedded snippet; the path and line range are the
+ * authoritative pointers, so a very long selection is trimmed.
  */
 const MAX_SNIPPET_CHARS = 2000;
 
@@ -33,10 +31,6 @@ function fenceFor(text: string): string {
   return '`'.repeat(Math.max(3, longest + 1));
 }
 
-/**
- * Trim `text` to {@link MAX_SNIPPET_CHARS}, cutting at a line boundary.
- * Returns the (possibly shortened) snippet and whether anything was dropped.
- */
 function clampSnippet(text: string): { snippet: string; truncated: boolean } {
   if (text.length <= MAX_SNIPPET_CHARS) {
     return { snippet: text, truncated: false };
@@ -58,7 +52,7 @@ function locatorFor(context: IAskAgentContext): string {
   const where: string[] = [`\`${context.path}\``];
   if (context.cell !== undefined) {
     // Both orderings so the agent can count cells or index the nbformat
-    // `cells` array, whichever its notebook tooling prefers.
+    // `cells` array.
     where.push(
       `${context.cell.type} cell ${context.cell.index + 1} ` +
         `(0-based index ${context.cell.index})`
@@ -78,11 +72,6 @@ function locatorFor(context: IAskAgentContext): string {
   return where.join(', ');
 }
 
-/**
- * The blocks describing one comment: `headline`, the selected snippet in a
- * code fence (when there is one), then the user's instruction. Blocks are
- * joined with blank lines by the callers.
- */
 function commentParts(
   context: IAskAgentContext,
   instruction: string,
@@ -102,11 +91,9 @@ function commentParts(
 }
 
 /**
- * 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 function buildPrompt(
   context: IAskAgentContext,

package/src/askAgent/queue.ts

@@ -5,8 +5,8 @@ import type { AskAgentTarget, IAskAgentContext } from './tokens';
 
 /**
  * One queued prompt: a code selection, the user's instruction about it, and
- * where it should go. Every prompt is independent — a queue can mix targets
- * (different agents, new terminals, different running sessions) freely.
+ * where it should go. Every prompt is independent — a queue mixes targets
+ * freely.
  */
 export interface IQueuedPrompt {
   /**
@@ -25,9 +25,8 @@ export interface IQueuedPrompt {
   instruction: string;
 
   /**
-   * The destination picked for this prompt (captured from the popup when it
-   * was queued, editable in the panel). `null` when a persisted target no
-   * longer parses — the panel then asks for a new pick before sending.
+   * The destination picked in the popup, editable in the panel. `null` when
+   * a persisted target no longer parses — the panel then asks for a new pick.
    */
   target: AskAgentTarget | null;
 }
@@ -39,15 +38,9 @@ function nextId(): string {
 }
 
 /**
- * The accumulated ask-agent prompts awaiting a batch send.
- *
- * Queueing decouples writing review comments from deciding where they go:
- * the popup appends entries here instead of sending, the side panel lists
- * and edits them, and one batch send flushes the lot, delivering each
- * destination's prompts as one numbered message. The queue itself is a
- * plain in-memory model; the plugin mirrors it into the JupyterLab state
- * database (via {@link serializeQueuedPrompts}) so a page reload does not
- * silently drop typed comments.
+ * The accumulated ask-agent prompts awaiting a batch send. A plain
+ * in-memory model; the plugin mirrors it into the state database so a page
+ * reload does not silently drop typed comments.
  */
 export class PromptQueue {
   constructor(items: IQueuedPrompt[] = []) {
@@ -125,8 +118,7 @@ export class PromptQueue {
   }
 
   /**
-   * Remove several queued prompts at once (one signal emission) — used when
-   * a batch send succeeds for one target while other targets' prompts stay.
+   * Remove several queued prompts at once (one signal emission).
    */
   removeMany(ids: readonly string[]): void {
     const drop = new Set(ids);
@@ -160,9 +152,8 @@ export class PromptQueue {
 }
 
 /**
- * Validate one persisted context. Only fields that still match the
- * `IAskAgentContext` contract are kept, so schema drift (or manual
- * state-database edits) degrades an entry instead of poisoning the queue.
+ * Validate one persisted context; schema drift degrades an entry instead
+ * of poisoning the queue.
  */
 function sanitizeContext(value: unknown): IAskAgentContext | null {
   if (value === null || typeof value !== 'object') {
@@ -225,9 +216,8 @@ function sanitizeTarget(value: unknown): AskAgentTarget | null {
 }
 
 /**
- * Rebuild queued prompts from a value read back from the state database.
- * Entries that no longer parse are dropped silently — the queue is a
- * convenience buffer, not a document.
+ * Rebuild queued prompts from the state database; entries that no longer
+ * parse are dropped silently.
  */
 export function deserializeQueuedPrompts(value: unknown): IQueuedPrompt[] {
   if (!Array.isArray(value)) {
@@ -255,8 +245,7 @@ export function deserializeQueuedPrompts(value: unknown): IQueuedPrompt[] {
 
 /**
  * The queue as a JSON value for the state database. Ids are session-scoped
- * handles, so they are not persisted; {@link deserializeQueuedPrompts}
- * assigns fresh ones on load.
+ * and not persisted; fresh ones are assigned on load.
  */
 export function serializeQueuedPrompts(
   items: readonly IQueuedPrompt[]

package/src/askAgent/queuePanel.tsx

@@ -19,25 +19,16 @@ import type { IQueuedPrompt, PromptQueue } from './queue';
 import type { ISessionTarget } from './targetPicker';
 import type { AskAgentTarget } from './tokens';
 
-/**
- * Command the context buttons dispatch; keeps the panel decoupled from the plugin.
- */
 const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
 
 /**
- * Textarea height that fits `text` without scrolling, within sane bounds:
- * tall enough to look editable, short enough that one long comment cannot
- * crowd out the rest of the queue.
+ * Textarea height that fits `text` without scrolling, bounded so one long
+ * comment cannot crowd out the rest of the queue.
  */
 function rowsFor(text: string): number {
   return Math.min(8, Math.max(2, text.split('\n').length));
 }
 
-/**
- * A target as a `<select>` option value: `session:<name>` for a running
- * agent terminal, `new:<agentId>` for a fresh terminal, `''` for a missing
- * target (the placeholder option).
- */
 function encodeTarget(target: AskAgentTarget | null): string {
   if (target === null) {
     return '';
@@ -57,10 +48,6 @@ function decodeTarget(value: string): AskAgentTarget | null {
   return null;
 }
 
-/**
- * Whether `target` can be sent to right now: its session is still running,
- * or its agent still accepts a command-line prompt.
- */
 function targetIsLive(
   target: AskAgentTarget | null,
   agents: readonly IAgent[],
@@ -86,8 +73,8 @@ function QueuePanelComponent(props: AskAgentQueuePanel.IOptions): JSX.Element {
     onClear
   } = props;
 
-  // Snapshots for this render; the widget re-renders on every queue, agent
-  // registry and terminal change, so these stay current.
+  // The widget re-renders on every queue, agent registry and terminal
+  // change, so these snapshots stay current.
   const items = queue.items;
   const agents = readAgents();
   const targets = readTargets();
@@ -102,10 +89,8 @@ function QueuePanelComponent(props: AskAgentQueuePanel.IOptions): JSX.Element {
   const jumpTo = (item: IQueuedPrompt): void => {
     const { context } = item;
     const path = serverPath(context);
-    // The highlighter needs line numbers that index the working file:
-    // notebook lines are cell-relative (or raw-JSON offsets), and diff
-    // selections may come from another revision — just open the document
-    // in those cases.
+    // The highlighter needs working-file line numbers: notebook lines are
+    // cell-relative and diff lines may index another revision — just open.
     const jump =
       context.cell === undefined &&
       context.startLine !== undefined &&
@@ -145,9 +130,6 @@ function QueuePanelComponent(props: AskAgentQueuePanel.IOptions): JSX.Element {
           const missing = item.instruction.trim().length === 0;
           const target = item.target;
           const live = targetIsLive(target, agents, targets);
-          // Say what sending will do for this prompt — paste into a running
-          // terminal, or start a fresh one — and badge it with the agent's
-          // icon, so a mixed queue can be scanned without opening dropdowns.
           let icon: LabIcon | null = null;
           let targetTitle = trans.__(
             'The destination picked for this prompt is gone — choose another'
@@ -202,10 +184,8 @@ function QueuePanelComponent(props: AskAgentQueuePanel.IOptions): JSX.Element {
                   {item.context.text}
                 </pre>
               )}
-              {/* Uncontrolled on purpose: the queue re-renders through a
-                  posted Lumino update, and a controlled value fed back that
-                  late reverts keystrokes and jumps the caret. The `key` on
-                  the surrounding <li> still remounts it per queue entry. */}
+              {/* Uncontrolled on purpose: re-renders arrive as posted Lumino
+                  updates, late enough to revert keystrokes if controlled. */}
               <textarea
                 className="jp-xtralab-AskAgentQueue-instruction"
                 rows={rowsFor(item.instruction)}
@@ -324,15 +304,10 @@ function QueuePanelComponent(props: AskAgentQueuePanel.IOptions): JSX.Element {
 }
 
 /**
- * The right-sidebar review panel for queued ask-agent prompts.
- *
- * Lists every queued comment — jump-to-code context line, snippet preview,
- * editable instruction, its own destination picker, remove button — plus a
- * send button that flushes the whole queue in one go: prompts sharing a
- * destination are combined into one numbered message, and each destination
- * gets its own delivery. The widget re-renders on queue changes itself; the
- * plugin additionally ties it to the agent registry and terminal signals so
- * the destination choices stay current.
+ * The right-sidebar review panel for queued ask-agent prompts: an editable
+ * list with per-prompt destinations, plus a send button that flushes the
+ * whole queue, combining prompts that share a destination into one
+ * numbered message.
  */
 export class AskAgentQueuePanel extends ReactWidget {
   constructor(options: AskAgentQueuePanel.IOptions) {
@@ -342,15 +317,16 @@ export class AskAgentQueuePanel extends ReactWidget {
     options.queue.changed.connect(this._onQueueChanged, this);
   }
 
+  /**
+   * Render the panel content.
+   */
   render(): JSX.Element {
     return <QueuePanelComponent {...this._options} />;
   }
 
   /**
-   * Dispose on close (e.g. the close button when the panel has been dragged
-   * to the main area) rather than leaving a detached, reusable widget
-   * behind. The plugin recreates the panel in the side area on demand; the
-   * queue itself lives on in the model.
+   * Dispose on close rather than leaving a detached widget behind; the
+   * plugin recreates the panel on demand and the queue lives on in the model.
    */
   protected onCloseRequest(msg: Message): void {
     super.onCloseRequest(msg);
@@ -393,9 +369,8 @@ export namespace AskAgentQueuePanel {
     targets: () => ISessionTarget[];
 
     /**
-     * Live reader of whether a batch send is in flight (called on every
-     * render). While true the send and clear buttons are disabled, so one
-     * flush cannot be double-delivered.
+     * Live reader of whether a batch send is in flight; while true the send
+     * and clear buttons are disabled.
      */
     sending: () => boolean;
 
@@ -405,8 +380,8 @@ export namespace AskAgentQueuePanel {
     trans: TranslationBundle;
 
     /**
-     * Send every queued prompt to its own destination (the panel only calls
-     * this while all instructions and destinations are valid).
+     * Send every queued prompt to its own destination (called only while
+     * all instructions and destinations are valid).
      */
     onSend: () => void;
 

package/src/askAgent/targetPicker.tsx

@@ -32,11 +32,9 @@ export interface ISessionTarget {
 }
 
 /**
- * Keyboard support shared by the two radiogroups below, following the ARIA
- * radio-group pattern: the group is one tab stop (only the checked radio is
- * tabbable) and the arrow keys move the selection to the neighbouring
- * radio, wrapping around. Selection follows focus, so the handler clicks
- * the neighbour and the re-render moves the roving tabindex along.
+ * Keyboard support for the radiogroups, per the ARIA radio pattern: one tab
+ * stop, arrow keys move and select — the handler clicks the neighbour and
+ * the re-render moves the roving tabindex along.
  */
 function onRadioGroupKeyDown(event: React.KeyboardEvent<HTMLElement>): void {
   let delta: number;
@@ -67,18 +65,11 @@ function onRadioGroupKeyDown(event: React.KeyboardEvent<HTMLElement>): void {
 
 /**
  * The chip row picking where a prompt goes: "New terminal" plus one chip
- * per running agent session. Renders nothing while no agent session is
- * running (a new terminal is then the only possibility and the row would
- * be noise).
+ * per running agent session. Renders nothing while no session is running
+ * (a new terminal is then the only possibility).
  */
 export function TargetChips(props: {
-  /**
-   * Agents that could start in a new terminal; gates the "New terminal" chip.
-   */
   agents: IAgent[];
-  /**
-   * The running agent sessions.
-   */
   targets: ISessionTarget[];
   /**
    * The selected session name, or `null` for a new terminal.
@@ -194,7 +185,6 @@ export function AgentChoices(props: {
             'jp-xtralab-AskAgent-agentButton' +
             (agent.id === agentId ? ' jp-mod-selected' : '')
           }
-          // Keep focus where the user is typing while picking an agent.
           onMouseDown={event => event.preventDefault()}
           onClick={() => onSelect(agent.id)}
         >

package/src/askAgent/tokens.ts

@@ -1,39 +1,34 @@
 import { Token } from '@lumino/coreutils';
 
 /**
- * The command id that opens the ask-agent popup for the current text-editor
- * selection. Registered by `xtralab:ask-agent`; exposed here so menus and
- * other plugins can reference it without importing the plugin internals.
+ * Command id opening the ask-agent popup for the current editor selection;
+ * exposed so other plugins can reference it without the plugin internals.
  */
 export const ASK_AGENT_COMMAND = 'xtralab:ask-agent';
 
 /**
- * A code location (and optionally the selected source text) that a prompt
- * should point an agent at. The structured fields are composed into the
- * final prompt by the ask-agent plugin so every entry point — editor
- * selection, diff line selection — produces consistently worded prompts.
+ * A code location (and optionally the selected text) a prompt should point
+ * an agent at; the plugin composes the fields into consistently worded
+ * prompts for every entry point.
  */
 export interface IAskAgentContext {
   /**
-   * Path of the file the selection belongs to, relative to {@link cwd} (or
-   * to the server root when no cwd is given) so the launched agent can open
-   * it directly.
+   * Path of the file, relative to {@link cwd} (or to the server root when
+   * no cwd is given).
    */
   path: string;
 
   /**
-   * Server-relative directory the agent's terminal starts in. Omit to start
-   * in the server root. Diff selections pass the git repository root here so
-   * the agent can run git commands right away.
+   * Server-relative directory the agent's terminal starts in. Diff
+   * selections pass the git repository root so the agent can run git
+   * commands right away.
    */
   cwd?: string;
 
   /**
-   * The notebook cell the selection lives in, when {@link path} is a
-   * notebook. `index` is the cell's 0-based position in the nbformat
-   * `cells` array; `type` is the nbformat cell type (`code`, `markdown`,
-   * `raw`). When set, {@link startLine}/{@link endLine} count within the
-   * cell's source rather than within a file.
+   * The notebook cell the selection lives in. `index` is the 0-based
+   * nbformat position, `type` the nbformat cell type; when set,
+   * {@link startLine}/{@link endLine} count within the cell's source.
    */
   cell?: {
     index: number;
@@ -41,8 +36,8 @@ export interface IAskAgentContext {
   };
 
   /**
-   * First selected line, 1-indexed and inclusive. Omit when no line range is
-   * known (the prompt then only references the file).
+   * First selected line, 1-indexed and inclusive. Omit when no line range
+   * is known.
    */
   startLine?: number;
 
@@ -53,40 +48,34 @@ export interface IAskAgentContext {
   endLine?: number;
 
   /**
-   * Whether {@link startLine}/{@link endLine} index the file's current
-   * working-tree content. `false` for diff selections taken from another
-   * revision (the old side, or a challenger that is not the working tree),
-   * whose numbers must not be used to highlight the working file. Omitted
-   * means `true`.
+   * Whether the lines index the file's current working-tree content.
+   * `false` for diff selections taken from another revision, whose numbers
+   * must not highlight the working file. Omitted means `true`.
    */
   linesInWorkingFile?: boolean;
 
   /**
-   * The selected source text. May be empty when only a location is known;
-   * the prompt then relies on the path and line range alone.
+   * The selected source text; may be empty when only a location is known.
    */
   text: string;
 
   /**
-   * Extra agent-facing locator appended after the line range in the prompt,
-   * e.g. `the old side (INDEX) of the git diff`. Written in English because
-   * it is consumed by the agent, not shown in the UI.
+   * Extra agent-facing locator appended after the line range, e.g. `the old
+   * side (INDEX) of the git diff`. English — consumed by the agent, not the UI.
    */
   location?: string;
 
   /**
-   * Short user-facing tag shown in the popup header next to the file name,
-   * e.g. "old version". Translated, unlike {@link location}. Omit when the
-   * range reads naturally as the file's current content.
+   * Short user-facing tag shown in the popup header, e.g. "old version".
+   * Translated, unlike {@link location}.
    */
   note?: string;
 }
 
 /**
  * Where a submitted prompt goes: a fresh terminal started with the chosen
- * agent's command, or an existing terminal session whose running agent
- * receives the prompt in its input box (queued by the agent itself when it
- * is busy).
+ * agent's command, or an existing session whose running agent receives the
+ * prompt in its input box (queued by the agent itself when busy).
  */
 export type AskAgentTarget =
   | { kind: 'new'; agentId: string }
@@ -103,18 +92,16 @@ export interface IAskAgentRequest {
   context: IAskAgentContext;
 
   /**
-   * Viewport rectangle the popup anchors to (typically the selection end or
-   * the button that was clicked). `null` positions the popup near the top
-   * center of the viewport.
+   * Viewport rectangle the popup anchors to; `null` positions it near the
+   * top center of the viewport.
    */
   anchor: DOMRect | null;
 }
 
 /**
- * The ask-agent popup: a small floating prompt box that sends the given
- * code selection, plus the user's typed instruction, to one of the
- * configured coding agents — in a fresh terminal, or into an agent already
- * running in an existing one.
+ * The ask-agent popup: a floating prompt box that sends the given code
+ * selection plus the user's instruction to a coding agent, in a fresh or
+ * running terminal.
  */
 export interface IAskAgent {
   /**
@@ -129,9 +116,8 @@ export interface IAskAgent {
 }
 
 /**
- * DI token for {@link IAskAgent}. Provided by `xtralab:ask-agent` and
- * consumed — optionally, so diffs still render when the plugin is disabled —
- * by the git diff plugins to offer "ask an agent about these lines".
+ * DI token for {@link IAskAgent}; consumed optionally by the git diff
+ * plugins so diffs still render when the plugin is disabled.
  */
 export const IAskAgent = new Token<IAskAgent>(
   'xtralab:IAskAgent',