xtralab 0.11.0 → 0.12.0

package/lib/askAgent/popup.d.ts

@@ -0,0 +1,83 @@
+import type { TranslationBundle } from '@jupyterlab/translation';
+import { ReactWidget } from '@jupyterlab/ui-components';
+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.
+ */
+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).
+ */
+export declare class AskAgentPopup extends ReactWidget {
+    constructor(options: AskAgentPopup.IOptions);
+    render(): JSX.Element;
+    private _options;
+}
+/**
+ * A namespace for `AskAgentPopup` statics.
+ */
+export declare namespace AskAgentPopup {
+    /**
+     * Construction options for {@link AskAgentPopup}.
+     */
+    interface IOptions {
+        /**
+         * The code selection the prompt is about.
+         */
+        context: IAskAgentContext;
+        /**
+         * Viewport rectangle to anchor to; `null` centers near the top.
+         */
+        anchor: DOMRect | null;
+        /**
+         * Snapshot of the prompt-capable agents, taken when the popup opens.
+         */
+        agents: IAgent[];
+        /**
+         * Snapshot of the running agent terminals, taken when the popup opens.
+         */
+        targets: ISessionTarget[];
+        /**
+         * Preferred agent id (the last one used), when still available.
+         */
+        initialAgentId: string | null;
+        /**
+         * Session to preselect as the target, or `null` to preselect the new
+         * terminal. Must be `null` or the name of an entry in {@link targets}.
+         */
+        initialTargetName: string | null;
+        /**
+         * Number of prompts already queued, shown on the queue button. Only
+         * meaningful together with {@link onQueue}.
+         */
+        queueCount?: number;
+        /**
+         * Translation bundle for the popup's own labels.
+         */
+        trans: TranslationBundle;
+        /**
+         * Send the instruction to the chosen target (the plugin closes the popup).
+         */
+        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.
+         */
+        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.
+         */
+        onCancel: (restoreFocus: boolean) => void;
+    }
+}

package/lib/askAgent/popup.js

@@ -0,0 +1,221 @@
+import { PathExt } from '@jupyterlab/coreutils';
+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.
+ */
+export function contextSummary(context, trans) {
+    var _a;
+    const parts = [PathExt.basename(context.path)];
+    if (context.cell !== undefined) {
+        parts.push(trans.__('cell %1', context.cell.index + 1));
+    }
+    if (context.startLine !== undefined) {
+        const endLine = (_a = context.endLine) !== null && _a !== void 0 ? _a : context.startLine;
+        parts.push(endLine > context.startLine
+            ? trans.__('L%1–%2', context.startLine, endLine)
+            : trans.__('L%1', context.startLine));
+    }
+    if (context.note !== undefined && context.note.length > 0) {
+        parts.push(context.note);
+    }
+    return parts.join(' · ');
+}
+function AskAgentPopupComponent(props) {
+    var _a, _b;
+    const { context, anchor, agents, targets, initialAgentId, initialTargetName, queueCount, trans, onSubmit, onQueue, onCancel } = props;
+    const [instruction, setInstruction] = React.useState('');
+    const [agentId, setAgentId] = React.useState(() => {
+        var _a, _b;
+        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.
+    React.useLayoutEffect(() => {
+        const node = popupRef.current;
+        if (node === null) {
+            return;
+        }
+        const rect = node.getBoundingClientRect();
+        const viewportWidth = window.innerWidth;
+        const viewportHeight = window.innerHeight;
+        let left;
+        let top;
+        if (anchor) {
+            left = anchor.left;
+            top = anchor.bottom + ANCHOR_GAP;
+            if (top + rect.height > viewportHeight - VIEWPORT_MARGIN) {
+                top = anchor.top - rect.height - ANCHOR_GAP;
+            }
+        }
+        else {
+            left = (viewportWidth - rect.width) / 2;
+            top = viewportHeight * 0.2;
+        }
+        left = Math.max(VIEWPORT_MARGIN, Math.min(left, viewportWidth - rect.width - VIEWPORT_MARGIN));
+        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.
+    React.useEffect(() => {
+        var _a, _b;
+        if (position !== null) {
+            (_b = ((_a = textareaRef.current) !== null && _a !== void 0 ? _a : popupRef.current)) === null || _b === void 0 ? void 0 : _b.focus();
+        }
+    }, [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).
+        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.
+    React.useEffect(() => {
+        const onPointerDown = (event) => {
+            const node = popupRef.current;
+            if (node &&
+                event.target instanceof Node &&
+                !node.contains(event.target)) {
+                dismiss(false);
+            }
+        };
+        document.addEventListener('pointerdown', onPointerDown, true);
+        return () => {
+            document.removeEventListener('pointerdown', onPointerDown, true);
+        };
+    }, [dismiss]);
+    const selectedAgent = agents.find(agent => agent.id === agentId);
+    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) {
+            return { kind: 'session', name: session.name };
+        }
+        const agent = agents.find(entry => entry.id === agentId);
+        if (agent !== undefined) {
+            return { kind: 'new', agentId: agent.id };
+        }
+        return null;
+    }, [agents, agentId, targets, targetName]);
+    const submit = React.useCallback(() => {
+        const trimmed = instruction.trim();
+        const target = resolveTarget();
+        if (trimmed.length === 0 || target === null) {
+            return;
+        }
+        // Defer so unmounting this React root never happens synchronously
+        // inside the event handler that triggered it.
+        window.setTimeout(() => {
+            onSubmit(target, trimmed);
+        }, 0);
+    }, [instruction, resolveTarget, onSubmit]);
+    const queueInstruction = React.useCallback(() => {
+        const trimmed = instruction.trim();
+        const target = resolveTarget();
+        if (trimmed.length === 0 || target === null || onQueue === undefined) {
+            return;
+        }
+        // Same deferred pattern as submit.
+        window.setTimeout(() => {
+            onQueue(target, trimmed);
+        }, 0);
+    }, [instruction, resolveTarget, onQueue]);
+    const onRootKeyDown = (event) => {
+        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);
+        }
+    };
+    const onTextareaKeyDown = (event) => {
+        if (event.key !== 'Enter' || event.nativeEvent.isComposing) {
+            return;
+        }
+        if ((event.metaKey || event.ctrlKey) && onQueue !== undefined) {
+            event.preventDefault();
+            event.stopPropagation();
+            queueInstruction();
+            return;
+        }
+        if (!event.shiftKey) {
+            event.preventDefault();
+            event.stopPropagation();
+            submit();
+        }
+    };
+    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.
+        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,
+            visibility: position ? 'visible' : 'hidden'
+        }, onKeyDown: onRootKeyDown },
+        React.createElement("div", { className: "jp-xtralab-AskAgent-context", title: context.path }, summary),
+        agents.length === 0 && targets.length === 0 ? (React.createElement("div", { className: "jp-xtralab-AskAgent-empty" }, trans.__('No agent accepts an initial prompt. Configure agents in the launcher settings.'))) : (React.createElement(React.Fragment, null,
+            React.createElement("textarea", { ref: textareaRef, className: "jp-xtralab-AskAgent-input", rows: 3, spellCheck: false, placeholder: placeholder, "aria-label": placeholder, value: instruction, onChange: event => setInstruction(event.target.value), onKeyDown: onTextareaKeyDown }),
+            React.createElement(TargetChips, { agents: agents, targets: targets, targetName: targetName, trans: trans, onSelect: setTargetName }),
+            React.createElement("div", { className: "jp-xtralab-AskAgent-footer" },
+                selectedSession === undefined && (React.createElement(AgentChoices, { agents: agents, agentId: agentId, trans: trans, onSelect: setAgentId })),
+                React.createElement("div", { className: "jp-xtralab-AskAgent-actions" },
+                    onQueue !== undefined && (React.createElement("button", { type: "button", className: "jp-xtralab-AskAgent-queueButton", disabled: !canSubmit, title: trans.__('Queue for this destination instead of sending now — review the queue and send everything later (%1)', CommandRegistry.formatKeystroke('Accel Enter')), onMouseDown: event => event.preventDefault(), onClick: queueInstruction }, queueCount !== undefined && queueCount > 0
+                        ? trans.__('Queue (%1)', queueCount)
+                        : trans.__('Queue'))),
+                    React.createElement("button", { type: "button", className: "jp-xtralab-AskAgent-submit", disabled: !canSubmit, title: trans.__('Enter to send, Esc to close'), onMouseDown: event => event.preventDefault(), onClick: submit }, selectedSession
+                        ? trans.__('Send to %1', selectedSession.label)
+                        : selectedAgent
+                            ? trans.__('Ask %1', selectedAgent.label)
+                            : 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).
+ */
+export class AskAgentPopup extends ReactWidget {
+    constructor(options) {
+        super();
+        this._options = options;
+        this.id = 'xtralab-ask-agent-popup';
+        this.addClass('jp-xtralab-AskAgent');
+        this.addClass('jp-ThemedContainer');
+    }
+    render() {
+        return React.createElement(AskAgentPopupComponent, { ...this._options });
+    }
+}

package/lib/askAgent/prompt.d.ts

@@ -0,0 +1,24 @@
+import type { IAskAgentContext } from './tokens';
+/**
+ * The path a context points at, resolved against the server root. Contexts
+ * from git diffs carry repository-relative paths plus the repository root in
+ * `cwd`; contexts from plain editors are already server-relative.
+ */
+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.
+ */
+export declare function buildPrompt(context: IAskAgentContext, instruction: string): string;
+/**
+ * Compose one prompt out of every queued comment, numbered and in queue
+ * order, so a whole review pass reaches the agent as a single task list. A
+ * queue of one degrades to the plain {@link buildPrompt} wording.
+ */
+export declare function buildBatchPrompt(items: ReadonlyArray<{
+    context: IAskAgentContext;
+    instruction: string;
+}>): string;

package/lib/askAgent/prompt.js

@@ -0,0 +1,116 @@
+import { PathExt } from '@jupyterlab/coreutils';
+/**
+ * The path a context points at, resolved against the server root. Contexts
+ * from git diffs carry repository-relative paths plus the repository root in
+ * `cwd`; contexts from plain editors are already server-relative.
+ */
+export function serverPath(context) {
+    return context.cwd !== undefined && context.cwd.length > 0
+        ? PathExt.join(context.cwd, context.path)
+        : context.path;
+}
+/**
+ * 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.
+ */
+const MAX_SNIPPET_CHARS = 2000;
+/**
+ * A backtick fence strictly longer than any backtick run inside `text`, so
+ * the embedded snippet can never terminate the fence early.
+ */
+function fenceFor(text) {
+    var _a;
+    let longest = 0;
+    for (const run of (_a = text.match(/`+/g)) !== null && _a !== void 0 ? _a : []) {
+        longest = Math.max(longest, run.length);
+    }
+    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) {
+    if (text.length <= MAX_SNIPPET_CHARS) {
+        return { snippet: text, truncated: false };
+    }
+    const head = text.slice(0, MAX_SNIPPET_CHARS);
+    const lastBreak = head.lastIndexOf('\n');
+    return {
+        snippet: lastBreak > 0 ? head.slice(0, lastBreak) : head,
+        truncated: true
+    };
+}
+/**
+ * Agent-facing description of where `context` points: path, notebook cell,
+ * line range and any extra locator, e.g.
+ * `` `src/app.ts`, lines 3-9, the old side (HEAD) of the current git diff ``.
+ */
+function locatorFor(context) {
+    var _a;
+    const where = [`\`${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.
+        where.push(`${context.cell.type} cell ${context.cell.index + 1} ` +
+            `(0-based index ${context.cell.index})`);
+    }
+    if (context.startLine !== undefined) {
+        const endLine = (_a = context.endLine) !== null && _a !== void 0 ? _a : context.startLine;
+        const lines = endLine > context.startLine
+            ? `lines ${context.startLine}-${endLine}`
+            : `line ${context.startLine}`;
+        where.push(context.cell !== undefined ? `${lines} of the cell` : lines);
+    }
+    if (context.location !== undefined && context.location.length > 0) {
+        where.push(context.location);
+    }
+    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, instruction, headline) {
+    const parts = [headline];
+    if (context.text.length > 0) {
+        const { snippet, truncated } = clampSnippet(context.text);
+        const fence = fenceFor(snippet);
+        parts.push(`${fence}\n${snippet}\n${fence}`);
+        if (truncated) {
+            parts.push('(snippet truncated — read the file for the full range)');
+        }
+    }
+    parts.push(instruction);
+    return parts;
+}
+/**
+ * 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.
+ */
+export function buildPrompt(context, instruction) {
+    return commentParts(context, instruction, `In ${locatorFor(context)}:`).join('\n\n');
+}
+/**
+ * Compose one prompt out of every queued comment, numbered and in queue
+ * order, so a whole review pass reaches the agent as a single task list. A
+ * queue of one degrades to the plain {@link buildPrompt} wording.
+ */
+export function buildBatchPrompt(items) {
+    if (items.length === 1) {
+        return buildPrompt(items[0].context, items[0].instruction);
+    }
+    const parts = [
+        `Please address the following ${items.length} comments.`
+    ];
+    items.forEach((item, index) => {
+        parts.push(...commentParts(item.context, item.instruction, `Comment ${index + 1} — in ${locatorFor(item.context)}:`));
+    });
+    return parts.join('\n\n');
+}

package/lib/askAgent/queue.d.ts

@@ -0,0 +1,93 @@
+import type { ReadonlyPartialJSONValue } from '@lumino/coreutils';
+import { ISignal } from '@lumino/signaling';
+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.
+ */
+export interface IQueuedPrompt {
+    /**
+     * Handle for edits and removal, unique within the page session.
+     */
+    id: string;
+    /**
+     * The code selection the instruction is about.
+     */
+    context: IAskAgentContext;
+    /**
+     * The user's typed comment.
+     */
+    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.
+     */
+    target: AskAgentTarget | null;
+}
+/**
+ * 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.
+ */
+export declare class PromptQueue {
+    constructor(items?: IQueuedPrompt[]);
+    /**
+     * The queued prompts, oldest first.
+     */
+    get items(): readonly IQueuedPrompt[];
+    /**
+     * Emitted whenever the queue contents change.
+     */
+    get changed(): ISignal<this, void>;
+    /**
+     * Append a prompt to the queue.
+     */
+    add(context: IAskAgentContext, instruction: string, target: AskAgentTarget): void;
+    /**
+     * Replace the instruction of the queued prompt `id`, if still present.
+     */
+    updateInstruction(id: string, instruction: string): void;
+    /**
+     * Repoint the queued prompt `id` at `target`, if still present.
+     */
+    updateTarget(id: string, target: AskAgentTarget): void;
+    /**
+     * Remove the queued prompt `id`, if still present.
+     */
+    remove(id: string): void;
+    /**
+     * Remove several queued prompts at once (one signal emission) — used when
+     * a batch send succeeds for one target while other targets' prompts stay.
+     */
+    removeMany(ids: readonly string[]): void;
+    /**
+     * Drop every queued prompt.
+     */
+    clear(): void;
+    /**
+     * Replace the whole queue (used to restore and to undo a clear).
+     */
+    reset(items: readonly IQueuedPrompt[]): void;
+    private _items;
+    private _changed;
+}
+/**
+ * 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.
+ */
+export declare 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.
+ */
+export declare function serializeQueuedPrompts(items: readonly IQueuedPrompt[]): ReadonlyPartialJSONValue;