xtralab 0.15.0 → 0.15.2

package/README.md

@@ -2,19 +2,18 @@
 
 An opinionated JupyterLab meta-package for coding agents.
 
-xtralab reshapes JupyterLab around terminal coding agents. It bundles a curated
-set of extensions, a path-first file browser, rich git diffs, an agent launcher,
-a Model Context Protocol server that lets agents drive the app, and a quieter
-set of defaults. It builds on [`ajlab`](https://github.com/jtpio/ajlab), the
-agent-ready JupyterLab base.
-
-![The xtralab workspace: path-first file browser, agent launcher, a side-by-side git diff, and a running Claude Code session](./images/hero.webp)
-
-The [documentation](https://jtpio.github.io/xtralab/) covers everything in
-detail: [installation](https://jtpio.github.io/xtralab/installation/), a
-[tour of the features](https://jtpio.github.io/xtralab/getting-started/),
-[connecting agents over MCP](https://jtpio.github.io/xtralab/agents/mcp/),
-[agent skills](https://jtpio.github.io/xtralab/agents/skills/), and the
+xtralab installs JupyterLab with a set of extensions and defaults for work
+with terminal coding agents: an agent launcher, side-by-side git diffs for
+text files and notebooks, prompts about selected code, and a Model Context
+Protocol server that lets agents drive the app. It builds on
+[`ajlab`](https://github.com/jtpio/ajlab), the agent-ready JupyterLab base.
+
+![The xtralab workspace: file browser, agent launcher, a side-by-side git diff, and a running Claude Code session](./images/hero.webp)
+
+See the [documentation](https://jtpio.github.io/xtralab/) for the
+[installation](https://jtpio.github.io/xtralab/installation/), a
+[getting started tutorial](https://jtpio.github.io/xtralab/getting-started/),
+the [features](https://jtpio.github.io/xtralab/features/launcher/), and the
 [desktop app](https://jtpio.github.io/xtralab/desktop/).
 
 ## Install
@@ -24,24 +23,60 @@ pip install xtralab
 jupyter lab
 ```
 
-A standalone desktop app (DMG on macOS, AppImage on Linux) ships with every
-tagged release on the
-[releases page](https://github.com/jtpio/xtralab/releases/latest). The macOS
-app is signed and notarized and keeps itself up to date; see the
-[desktop app docs](https://jtpio.github.io/xtralab/desktop/) for how it
-manages projects and kernels.
+To run xtralab in any folder without installing it, use uv:
+
+```bash
+uvx --from xtralab jupyter-lab
+```
+
+The [installation docs](https://jtpio.github.io/xtralab/installation/) also
+show how to install xtralab as a uv tool or add it to a project.
+
+The desktop app (DMG on macOS, AppImage on Linux) is on the
+[releases page](https://github.com/jtpio/xtralab/releases/latest). It
+includes its own Python runtime. See the
+[desktop app docs](https://jtpio.github.io/xtralab/desktop/).
 
 ## Highlights
 
-![The xtralab launcher](./images/launcher.webp)
+### Agent launcher
+
+Start any coding agent installed on your machine, with an optional first
+prompt. The **Changes** list opens the diff of each changed file.
+[Read more](https://jtpio.github.io/xtralab/features/launcher/).
+
+<img src="./images/launcher.webp" width="720" alt="The launcher: a prompt box, one button per installed agent, the Open section, and the list of changed files" />
+
+### Git diffs
+
+Review changes side by side, for text files and for notebooks, and edit the
+working copy in the diff.
+[Read more](https://jtpio.github.io/xtralab/features/git-diffs/).
+
+<img src="./images/diff.webp" width="1000" alt="A side-by-side diff of a Python file, with removed lines on the left and added lines on the right" />
+
+### Ask an agent
+
+Select code, type an instruction, and send it to a new or running agent. The
+prompt includes the file path, the line range, and the selected code.
+[Read more](https://jtpio.github.io/xtralab/features/ask-agent/).
+
+<img src="./images/ask-agent.webp" width="796" alt="The prompt box below a selected function, with an instruction and one button per agent" />
+
+### Omnibox
+
+Search files and commands, or send a prompt to an agent, from one search box
+(<kbd>Cmd/Ctrl</kbd>+<kbd>K</kbd>).
+[Read more](https://jtpio.github.io/xtralab/features/omnibox/).
+
+<img src="./images/omnibox.webp" width="642" alt="The omnibox with matching commands, a matching file, and one Ask row per agent" />
+
+### Terminals panel
+
+See the agent in each terminal and its latest line of output.
+[Read more](https://jtpio.github.io/xtralab/features/terminals/).
 
-The launcher starts any agent installed on your machine, with an optional
-prompt and a **Changes** list that jumps straight into a side-by-side git diff
-you can edit in place. Select code in an editor, a notebook, or a diff to send
-a prompt about it to a new or already-running agent, or queue prompts while
-you read. One omnibox searches files and commands, the Terminals panel shows
-which agent runs where, and quieter defaults keep the workspace calm. The
-[documentation](https://jtpio.github.io/xtralab/) walks through each of these.
+<img src="./images/terminals.webp" width="451" alt="The Terminals panel with three agent sessions and their latest output" />
 
 ## Connecting agents to JupyterLab (MCP)
 
@@ -54,9 +89,9 @@ xtralab:
 claude mcp add jupyter -- jupyter-server-mcp-proxy
 ```
 
-The launcher surfaces the matching command for every agent you have
-installed, and the [MCP docs page](https://jtpio.github.io/xtralab/agents/mcp/)
-covers the details.
+The launcher shows this command for each installed agent. See the
+[MCP docs](https://jtpio.github.io/xtralab/agents/mcp/) for Codex, GitHub
+Copilot, and other agents.
 
 [mcp]: https://github.com/jupyter-ai-contrib/jupyter-server-mcp
 [mcp-spec]: https://modelcontextprotocol.io

package/lib/about/icons.d.ts

@@ -1,7 +1,2 @@
 import { LabIcon } from '@jupyterlab/ui-components';
-/**
- * The project logo mark — `logo.svg` at the repository root, the same file
- * the README and the docs site use. The labextension build inlines it as a
- * raw string, so the dialog always shows the current artwork.
- */
 export declare const aboutLogoIcon: LabIcon;

package/lib/about/icons.js

@@ -1,10 +1,5 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 import logoSvgstr from '../../logo.svg';
-/**
- * The project logo mark — `logo.svg` at the repository root, the same file
- * the README and the docs site use. The labextension build inlines it as a
- * raw string, so the dialog always shows the current artwork.
- */
 export const aboutLogoIcon = new LabIcon({
     name: 'xtralab:about-logo',
     svgstr: logoSvgstr

package/lib/about/index.d.ts

@@ -1,13 +1,9 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * An "About xtralab" dialog replacing the stock "About JupyterLab" one.
- *
- * The upstream `@jupyterlab/help-extension:about` plugin is disabled via
- * `jupyterlab.disabledExtensions` (package.json), which removes both its
- * `help:about` command and its Help menu contribution; this plugin registers
- * the same command id and restores the menu entry through its own schema.
- * The dialog leads with the xtralab version and keeps the underlying
- * JupyterLab version visible underneath.
+ * An "About xtralab" dialog replacing the stock "About JupyterLab" one. The
+ * upstream plugin is disabled via `jupyterlab.disabledExtensions`, which also
+ * removes its Help menu entry; this plugin re-registers `help:about` and
+ * restores the menu entry through its own schema.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/about/index.js

@@ -4,24 +4,15 @@ import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import * as React from 'react';
 import { aboutLogoIcon } from './icons';
 const PLUGIN_ID = 'xtralab:about';
-/**
- * Upstream command id. Reusing it keeps the Help menu entry (contributed by
- * `schema/about.json` at the same rank as upstream), the command palette
- * muscle memory, and any external caller of `help:about` working.
- */
 const CommandIDs = {
     about: 'help:about'
 };
 const REPO_URL = 'https://github.com/jtpio/xtralab';
 /**
- * An "About xtralab" dialog replacing the stock "About JupyterLab" one.
- *
- * The upstream `@jupyterlab/help-extension:about` plugin is disabled via
- * `jupyterlab.disabledExtensions` (package.json), which removes both its
- * `help:about` command and its Help menu contribution; this plugin registers
- * the same command id and restores the menu entry through its own schema.
- * The dialog leads with the xtralab version and keeps the underlying
- * JupyterLab version visible underneath.
+ * An "About xtralab" dialog replacing the stock "About JupyterLab" one. The
+ * upstream plugin is disabled via `jupyterlab.disabledExtensions`, which also
+ * removes its Help menu entry; this plugin re-registers `help:about` and
+ * restores the menu entry through its own schema.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -41,10 +32,8 @@ const plugin = {
                 }
             },
             execute: async () => {
-                // The settings payload carries the version of the installed
-                // labextension (read server-side from its package.json), which is
-                // the release actually running — the page config only knows the
-                // JupyterLab version. 'N/A' is jupyterlab_server's not-found value.
+                // The settings payload carries the installed labextension's version
+                // (page config only knows JupyterLab's); 'N/A' is jupyterlab_server's not-found value.
                 const version = await settingRegistry
                     .load(PLUGIN_ID)
                     .then(settings => settings.version === 'N/A' ? '' : settings.version)

package/lib/agentSessions.d.ts

@@ -2,28 +2,14 @@ import type { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { Token } from '@lumino/coreutils';
 import { ISignal } 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;
     /**
@@ -31,24 +17,18 @@ 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 declare const IAgentSessions: Token<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.
  */
 declare const plugin: JupyterFrontEndPlugin<IAgentSessions>;
 export default plugin;

package/lib/agentSessions.js

@@ -1,9 +1,5 @@
 import { Token } from '@lumino/coreutils';
 import { Signal } from '@lumino/signaling';
-/**
- * DI token for {@link IAgentSessions}. Provided by `xtralab:agent-sessions`;
- * consumed (optionally) by both `xtralab:launcher` and `xtralab:terminals`.
- */
 export const IAgentSessions = new Token('xtralab:IAgentSessions', 'A shared map from terminal session name to the agent command it was launched with.');
 class AgentSessions {
     constructor() {
@@ -31,9 +27,8 @@ class AgentSessions {
     }
 }
 /**
- * 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 = {
     id: 'xtralab:agent-sessions',

package/lib/askAgent/editorSelection.d.ts

@@ -3,49 +3,43 @@ import type { EditorView } from '@codemirror/view';
 import type { Widget } from '@lumino/widgets';
 import type { 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;
     };
 }
 /**
- * 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 declare function resolveEditorTarget(widget: Widget | null): IEditorTarget | null;
 /**
- * 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 declare function domSelectionInView(view: EditorView, selection: Selection): boolean;
 /**
  * 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 declare function editorAskRequest(app: JupyterFrontEnd, options?: {
     allowEmpty?: boolean;

package/lib/askAgent/editorSelection.js

@@ -2,19 +2,10 @@ import { CodeMirrorEditor } from '@jupyterlab/codemirror';
 import { FileEditor } from '@jupyterlab/fileeditor';
 import { NotebookPanel } from '@jupyterlab/notebook';
 /**
- * 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) {
     if (widget instanceof NotebookPanel) {
@@ -36,10 +27,8 @@ export function resolveEditorTarget(widget) {
     return null;
 }
 /**
- * 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, selection) {
     var _a;
@@ -49,12 +38,9 @@ export function domSelectionInView(view, selection) {
 }
 /**
  * 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, options = {}) {
     const target = resolveEditorTarget(app.shell.currentWidget);
@@ -75,13 +61,12 @@ export function editorAskRequest(app, options = {}) {
         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/lib/askAgent/icons.d.ts

@@ -1,7 +1,6 @@
 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 declare const askAgentIcon: LabIcon;

package/lib/askAgent/icons.js

@@ -1,8 +1,7 @@
 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/lib/askAgent/index.d.ts

@@ -1,32 +1,10 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { IAskAgent } from './tokens';
 /**
- * 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.
  */
 declare const plugin: JupyterFrontEndPlugin<IAskAgent>;
 export default plugin;