xtralab 0.10.0 → 0.11.0

package/lib/walkthrough/panel.js

@@ -0,0 +1,98 @@
+import { fileIcon } from '@jupyterlab/ui-components';
+import { Panel, Widget } from '@lumino/widgets';
+/** Command the jump links dispatch; keeps the panel decoupled from the plugin. */
+const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
+/**
+ * A read-only, scrollable column of walkthrough steps for the side area.
+ *
+ * The agent appends steps as it narrates, so the explanation lives beside the
+ * code the user is looking at and persists for them to read at their own pace,
+ * rather than scrolling away in the chat. Each step renders Markdown (with code
+ * snippets, Mermaid, math), can embed a rich visual, and can offer a button
+ * that opens the referenced file and highlights its lines.
+ */
+export class WalkthroughPanel extends Panel {
+    constructor(options) {
+        super();
+        this._rendermime = options.rendermime;
+        this._commands = options.commands;
+        this._trans = options.trans;
+        this.addClass('jp-xtralab-Walkthrough');
+    }
+    /** Remove every step, leaving an empty panel. */
+    clear() {
+        while (this.widgets.length > 0) {
+            this.widgets[0].dispose();
+        }
+    }
+    /**
+     * 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
+     * next `xtralab:walkthrough` call recreates the panel in the side area.
+     */
+    onCloseRequest(msg) {
+        super.onCloseRequest(msg);
+        this.dispose();
+    }
+    /** Append a step and scroll it into view. */
+    async addStep(step) {
+        const card = new Panel();
+        card.addClass('jp-xtralab-Walkthrough-step');
+        this.addWidget(card);
+        if (step.title) {
+            const heading = new Widget({ node: document.createElement('h3') });
+            heading.addClass('jp-xtralab-Walkthrough-stepTitle');
+            heading.node.textContent = step.title;
+            card.addWidget(heading);
+        }
+        if (step.body) {
+            await this._render(card, 'text/markdown', step.body);
+        }
+        if (step.media && typeof step.media.mimeType === 'string') {
+            await this._render(card, step.media.mimeType, step.media.data);
+        }
+        if (step.path) {
+            card.addWidget(this._jumpButton(step.path, step.line, step.endLine));
+        }
+        // Bring the newest step into view.
+        this.node.scrollTop = this.node.scrollHeight;
+    }
+    async _render(parent, mimeType, data) {
+        const bundle = { [mimeType]: data };
+        const chosen = this._rendermime.preferredMimeType(bundle, 'any');
+        if (!chosen) {
+            return;
+        }
+        const renderer = this._rendermime.createRenderer(chosen);
+        renderer.addClass('jp-xtralab-Walkthrough-content');
+        parent.addWidget(renderer);
+        await renderer.renderModel(this._rendermime.createModel({ data: bundle, trusted: true }));
+    }
+    _jumpButton(path, line, endLine) {
+        const node = document.createElement('div');
+        node.className = 'jp-xtralab-Walkthrough-jumpRow';
+        const where = line ? `${path}:${line}` : path;
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'jp-xtralab-Walkthrough-jump';
+        button.title = this._trans.__('Open %1 in the editor', where);
+        const icon = fileIcon.element({
+            tag: 'span',
+            className: 'jp-xtralab-Walkthrough-jumpIcon'
+        });
+        const label = document.createElement('span');
+        label.className = 'jp-xtralab-Walkthrough-jumpLabel';
+        label.textContent = where;
+        button.appendChild(icon);
+        button.appendChild(label);
+        node.appendChild(button);
+        button.addEventListener('click', () => {
+            void this._commands.execute(HIGHLIGHT_LINES_COMMAND, {
+                path,
+                line,
+                endLine
+            });
+        });
+        return new Widget({ node });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xtralab",
-    "version": "0.10.0",
+    "version": "0.11.0",
     "description": "An opinionated JupyterLab meta-package that bundles a curated set of extensions, ships a path-first file browser, renders jupyterlab-git's text, notebook and image diffs with its own viewers, and applies a quieter default workspace configuration.",
     "keywords": [
         "jupyter",

package/schema/launcher.json

@@ -2,12 +2,13 @@
   "title": "xtralab launcher",
   "description": "Settings for the xtralab agent launcher.",
   "jupyter.lab.shortcuts": [],
+  "jupyter.lab.transform": true,
   "type": "object",
   "additionalProperties": false,
   "properties": {
     "agents": {
       "title": "Agents",
-      "description": "Override or extend the built-in list of agents shown on the launcher. Each entry must include an `id`. When the id matches a built-in (claude, codex, antigravity, copilot, goose, opencode, kiro, mistral-vibe), the fields you set override the corresponding defaults; leave a field out to keep the default. New ids define brand-new cards. Set `enabled: false` to hide a default. Set `requireAvailable: false` for shell aliases that should always show even though they aren't on PATH.",
+      "description": "Override or extend the built-in list of agents shown on the launcher. Each entry must include an `id`. When the id matches a built-in (claude, codex, antigravity, copilot, goose, opencode, kiro, mistral-vibe), the fields you set override the corresponding defaults; leave a field out to keep the default. New ids define brand-new cards. Set `enabled: false` to hide a default. Set `requireAvailable: false` for shell aliases that should always show even though they aren't on PATH. The full built-in list is shown as the default below, so you can copy an entry and tweak it in place.",
       "type": "array",
       "default": [],
       "items": {
@@ -68,7 +69,7 @@
     },
     "editors": {
       "title": "Editors",
-      "description": "Override or extend the terminal editors offered in the launcher's Open section (and recognized in the Terminals panel). Each entry must include an `id`. When the id matches a built-in (nvim, vim), the fields you set override the corresponding defaults; leave a field out to keep the default. New ids define additional editors. The launcher shows a single tile — the first editor, by `rank`, whose `command` is on PATH (Neovim before Vim by default). Set `enabled: false` to hide a built-in; disable both to remove the tile entirely. Set `requireAvailable: false` for a shell alias that should show even though it isn't on PATH.",
+      "description": "Override or extend the terminal editors offered in the launcher's Open section (and recognized in the Terminals panel). Each entry must include an `id`. When the id matches a built-in (nvim, vim), the fields you set override the corresponding defaults; leave a field out to keep the default. New ids define additional editors. The launcher shows a single tile — the first editor, by `rank`, whose `command` is on PATH (Neovim before Vim by default). Set `enabled: false` to hide a built-in; disable both to remove the tile entirely. Set `requireAvailable: false` for a shell alias that should show even though it isn't on PATH. The full built-in list is shown as the default below, so you can copy an entry and tweak it in place.",
       "type": "array",
       "default": [],
       "items": {

package/schema/terminals.json

@@ -0,0 +1,15 @@
+{
+  "title": "xtralab Terminals panel",
+  "description": "The left-sidebar panel that lists running terminal sessions.",
+  "jupyter.lab.shortcuts": [],
+  "type": "object",
+  "properties": {
+    "showAgentActivity": {
+      "type": "boolean",
+      "title": "Show agent activity under each terminal",
+      "description": "When true, every terminal running a coding agent shows a smaller line below its title with the agent's latest line of output, so you can see what a backgrounded agent is doing without switching to it. Turn this off to list terminals by title alone.",
+      "default": true
+    }
+  },
+  "additionalProperties": false
+}

package/src/commandBar/index.ts

@@ -0,0 +1,165 @@
+import {
+  ILabShell,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { searchIcon } from '@jupyterlab/ui-components';
+import { CommandRegistry } from '@lumino/commands';
+import { Widget } from '@lumino/widgets';
+
+import { IOmnibox, OMNIBOX_OPEN_COMMAND } from '../omnibox/tokens';
+
+const PLUGIN_ID = 'xtralab:command-bar';
+
+/**
+ * A search-bar-styled launcher for the `top` area. It holds no text input of
+ * its own: clicking the pill (or pressing Enter/Space while it is focused)
+ * runs `onActivate`, which opens the omnibox.
+ *
+ * The widget's root is a transparent, full-height wrapper centered as an
+ * overlay over the whole top panel (style/commandBar.css). The wrapper
+ * ignores pointer events so only the inner pill is clickable and the empty
+ * strips above and below it let clicks fall through to whatever sits beneath
+ * the overlay, such as the menu bar.
+ */
+class CommandBar extends Widget {
+  constructor(options: CommandBar.IOptions) {
+    super({
+      node: CommandBar.createNode(
+        options.label,
+        options.caption,
+        options.shortcut
+      )
+    });
+    this.addClass('jp-xtralab-CommandBar');
+    this._onActivate = options.onActivate;
+  }
+
+  handleEvent(event: Event): void {
+    if (event.type === 'click') {
+      this._onActivate();
+    }
+  }
+
+  protected onAfterAttach(): void {
+    // The pill restores `pointer-events: auto`, so the click bubbles from it
+    // up to the root node listened on here; keyboard Enter/Space on the
+    // focused button raises the same synthetic click.
+    this.node.addEventListener('click', this);
+  }
+
+  protected onBeforeDetach(): void {
+    this.node.removeEventListener('click', this);
+  }
+
+  private _onActivate: () => void;
+}
+
+namespace CommandBar {
+  export interface IOptions {
+    /** Placeholder-style text shown inside the pill. */
+    label: string;
+    /** Tooltip and accessible name for the button. */
+    caption: string;
+    /** Formatted keyboard shortcut shown as a trailing hint, if any. */
+    shortcut?: string;
+    /** Runs on click or keyboard activation. */
+    onActivate: () => void;
+  }
+
+  export function createNode(
+    label: string,
+    caption: string,
+    shortcut?: string
+  ): HTMLElement {
+    const wrapper = document.createElement('div');
+
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'jp-xtralab-CommandBar-button';
+    button.title = caption;
+    button.setAttribute('aria-label', caption);
+
+    const icon = searchIcon.element({
+      tag: 'span',
+      className: 'jp-xtralab-CommandBar-icon'
+    });
+
+    const text = document.createElement('span');
+    text.className = 'jp-xtralab-CommandBar-label';
+    text.textContent = label;
+
+    button.appendChild(icon);
+    button.appendChild(text);
+
+    if (shortcut) {
+      const hint = document.createElement('span');
+      hint.className = 'jp-xtralab-CommandBar-shortcut';
+      hint.textContent = shortcut;
+      // Decorative: the button's aria-label already names the action.
+      hint.setAttribute('aria-hidden', 'true');
+      button.appendChild(hint);
+    }
+
+    wrapper.appendChild(button);
+    return wrapper;
+  }
+}
+
+/**
+ * Add a centered, search-bar-styled command bar to the top area. Clicking it
+ * opens the omnibox — a launcher overlay that fuzzy-searches files and
+ * commands and routes a typed prompt to an agent (the leading sidebar toggle
+ * and the menu bar sit to its left, the trailing sidebar toggle to its right;
+ * the bar is centered over the whole panel as an overlay, so it stays put
+ * regardless of their widths).
+ *
+ * The bar is only added when the omnibox is available — the `IOmnibox` token
+ * is provided by `xtralab:omnibox` — so it never appears with nothing to open.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'Add a centered command bar to the top area that opens the omnibox.',
+  autoStart: true,
+  requires: [ILabShell],
+  optional: [IOmnibox, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    labShell: ILabShell,
+    omnibox: IOmnibox | null,
+    translator: ITranslator | null
+  ): void => {
+    if (!omnibox) {
+      return;
+    }
+
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+
+    // Show the omnibox's keyboard shortcut as a hint in the pill, derived from
+    // the live binding (registered by xtralab:omnibox, which activates first as
+    // the IOmnibox provider) so it stays correct and uses the platform's
+    // modifier symbols. Empty when no binding is registered.
+    const binding = app.commands.keyBindings.find(
+      keyBinding => keyBinding.command === OMNIBOX_OPEN_COMMAND
+    );
+    const shortcut = binding
+      ? CommandRegistry.formatKeystroke(binding.keys)
+      : '';
+
+    const widget = new CommandBar({
+      label: trans.__('Search…'),
+      caption: trans.__('Search files and commands, or ask an agent'),
+      shortcut,
+      onActivate: () => {
+        omnibox.open();
+      }
+    });
+    widget.id = 'xtralab-command-bar';
+
+    labShell.add(widget, 'top', { rank: 500 });
+  }
+};
+
+export default plugin;

package/src/fileBrowser/fileBrowser.tsx

@@ -93,6 +93,12 @@ const GIT_REPO_PATH = '';
  */
 const FILE_TREE_TAG = 'file-tree-container';
 
+const FILE_TREE_UNSAFE_CSS =
+  '[data-type="item"][data-item-selected="true"] ' +
+  '[data-item-section="spacing-item"] {' +
+  'border-left-color: transparent;' +
+  '}';
+
 export interface IFileBrowserProps {
   contentsManager: Contents.IManager;
   docManager: IDocumentManager;
@@ -123,7 +129,8 @@ export function FileBrowserComponent(
     initialExpansion: 'closed',
     search: true,
     icons: FILE_BROWSER_ICONS,
-    itemHeight: 24
+    itemHeight: 24,
+    unsafeCSS: FILE_TREE_UNSAFE_CSS
   });
 
   React.useEffect(() => {

package/src/highlight/index.ts

@@ -0,0 +1,251 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { CodeMirrorEditor } from '@jupyterlab/codemirror';
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { StateEffect, StateField } from '@codemirror/state';
+import { Decoration, DecorationSet, EditorView } from '@codemirror/view';
+import type { Widget } from '@lumino/widgets';
+
+const PLUGIN_ID = 'xtralab:highlight';
+
+/**
+ * Highlight a contiguous range of lines, or clear every highlight. These are
+ * the only two commands the plugin contributes; both are designed to be driven
+ * by a coding agent over the MCP command bridge to walk a user through code.
+ */
+const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
+const CLEAR_HIGHLIGHTS_COMMAND = 'xtralab:clear-highlights';
+
+/** CodeMirror line-decoration class; styled in style/highlight.css. */
+const HIGHLIGHT_LINE_CLASS = 'jp-xtralab-highlightLine';
+
+/**
+ * A CodeMirror effect carrying the 1-indexed, inclusive line range to
+ * highlight, or `null` to clear the editor's highlights.
+ */
+const setHighlight = StateEffect.define<{
+  start: number;
+  end: number;
+} | null>();
+
+/**
+ * Holds the highlight decorations for one editor. It is injected lazily (the
+ * first time an editor is highlighted) via `StateEffect.appendConfig`, so
+ * editors that are never highlighted pay nothing.
+ */
+const highlightField = StateField.define<DecorationSet>({
+  create: () => Decoration.none,
+  update(decorations, transaction) {
+    // Keep decorations anchored as the user edits around them.
+    decorations = decorations.map(transaction.changes);
+    for (const effect of transaction.effects) {
+      if (!effect.is(setHighlight)) {
+        continue;
+      }
+      if (effect.value === null) {
+        decorations = Decoration.none;
+        continue;
+      }
+      const { doc } = transaction.state;
+      const lineDecoration = Decoration.line({ class: HIGHLIGHT_LINE_CLASS });
+      const start = Math.max(1, Math.min(effect.value.start, doc.lines));
+      const end = Math.max(start, Math.min(effect.value.end, doc.lines));
+      const ranges = [];
+      for (let line = start; line <= end; line++) {
+        ranges.push(lineDecoration.range(doc.line(line).from));
+      }
+      decorations = Decoration.set(ranges);
+    }
+    return decorations;
+  },
+  provide: field => EditorView.decorations.from(field)
+});
+
+/**
+ * Return the CodeMirror view backing a widget's editor, or `null` when the
+ * widget is not a CodeMirror-based text editor (a notebook, a terminal, the
+ * settings editor, …). Duck-typed on `content.editor` so the plugin does not
+ * depend on `@jupyterlab/fileeditor`.
+ */
+function viewForWidget(widget: Widget | null): EditorView | null {
+  const editor = (widget as { content?: { editor?: unknown } } | null)?.content
+    ?.editor;
+  return editor instanceof CodeMirrorEditor ? editor.editor : null;
+}
+
+/**
+ * Coerce a JSON command argument to a positive integer line number, falling
+ * back to `fallback` when it is missing or not a finite number.
+ */
+function toLine(value: unknown, fallback: number): number {
+  const n = Math.trunc(Number(value));
+  return Number.isFinite(n) && n >= 1 ? n : fallback;
+}
+
+/**
+ * Contribute `xtralab:highlight-lines` and `xtralab:clear-highlights`.
+ *
+ * The built-in command surface can open a file (`docmanager:open`) and move
+ * the cursor to a line (`fileeditor:go-to-line`), but it cannot persistently
+ * highlight a span of lines — `documentsearch:start` only marks text matches
+ * and hijacks the find box. This plugin fills that gap with a CodeMirror line
+ * decoration, so an agent can point at "lines 31–43 of src/index.ts" while it
+ * narrates a walkthrough. `xtralab:highlight-lines` opens the file when needed,
+ * scrolls the range into view, and replaces any previous highlight in that
+ * editor; `xtralab:clear-highlights` removes every highlight.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description: 'Highlight line ranges in text editors to guide walkthroughs.',
+  autoStart: true,
+  requires: [IDocumentManager],
+  optional: [ICommandPalette, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    docManager: IDocumentManager,
+    palette: ICommandPalette | null,
+    translator: ITranslator | null
+  ): void => {
+    const { commands, shell } = app;
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+
+    // Editors that currently carry a highlight, so a single clear can reach
+    // them all. Disposed editors are dropped on the next clear.
+    const highlighted = new Set<EditorView>();
+
+    const ensureField = (view: EditorView): void => {
+      if (view.state.field(highlightField, false) === undefined) {
+        view.dispatch({ effects: StateEffect.appendConfig.of(highlightField) });
+      }
+    };
+
+    commands.addCommand(HIGHLIGHT_LINES_COMMAND, {
+      label: trans.__('Highlight Lines'),
+      caption: trans.__('Highlight a range of lines in a text editor'),
+      // Advertise the argument shape so agents listing commands over the MCP
+      // bridge can see how to call it, the same way core commands do.
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            path: {
+              type: 'string',
+              description:
+                'Path of the file to highlight in, relative to the server root. Opened if needed; defaults to the active editor when omitted.'
+            },
+            line: {
+              type: 'number',
+              description: 'First line to highlight (1-indexed). Defaults to 1.'
+            },
+            endLine: {
+              type: 'number',
+              description:
+                'Last line to highlight (1-indexed, inclusive). Defaults to `line` for a single line.'
+            },
+            reveal: {
+              type: 'boolean',
+              description:
+                'Whether to scroll the highlighted range into view. Defaults to true.'
+            }
+          }
+        }
+      },
+      execute: async args => {
+        const line = toLine(args['line'], 1);
+        const endLine = toLine(args['endLine'], line);
+        const path =
+          typeof args['path'] === 'string' ? args['path'] : undefined;
+        const reveal = args['reveal'] !== false;
+
+        // With a path, bind strictly to that document: never fall back to the
+        // active widget, or an explicit path could silently highlight an
+        // unrelated editor that happens to be focused.
+        let widget: Widget | null;
+        if (path) {
+          // Fail fast on a missing path instead of opening a phantom widget
+          // behind a blocking "file not found" dialog.
+          try {
+            await docManager.services.contents.get(path, { content: false });
+          } catch {
+            throw new Error(`xtralab: no file at "${path}"`);
+          }
+          const opened = docManager.openOrReveal(path);
+          if (!opened) {
+            throw new Error(`xtralab: could not open "${path}"`);
+          }
+          // Wait for the model and the editor view to be ready.
+          await opened.context.ready;
+          await opened.revealed;
+          widget = opened;
+        } else {
+          widget = shell.currentWidget;
+        }
+
+        const view = viewForWidget(widget);
+        if (!view) {
+          throw new Error(
+            path
+              ? `xtralab: "${path}" is not open in a text editor`
+              : 'xtralab: the active widget is not a text editor'
+          );
+        }
+
+        const start = Math.min(line, endLine);
+        const end = Math.max(line, endLine);
+        ensureField(view);
+
+        const lineCount = view.state.doc.lines;
+        const anchor = view.state.doc.line(
+          Math.max(1, Math.min(start, lineCount))
+        ).from;
+        const effects: StateEffect<unknown>[] = [
+          setHighlight.of({ start, end })
+        ];
+        if (reveal) {
+          effects.push(EditorView.scrollIntoView(anchor, { y: 'center' }));
+        }
+        view.dispatch({ effects });
+        // Forget editors that have since been closed before tracking this one.
+        for (const tracked of highlighted) {
+          if (!tracked.dom.isConnected) {
+            highlighted.delete(tracked);
+          }
+        }
+        highlighted.add(view);
+
+        return start === end
+          ? trans.__('Highlighted line %1', start)
+          : trans.__('Highlighted lines %1-%2', start, end);
+      }
+    });
+
+    commands.addCommand(CLEAR_HIGHLIGHTS_COMMAND, {
+      label: trans.__('Clear Highlights'),
+      caption: trans.__('Remove all xtralab line highlights'),
+      execute: () => {
+        for (const view of highlighted) {
+          try {
+            if (view.state.field(highlightField, false) !== undefined) {
+              view.dispatch({ effects: setHighlight.of(null) });
+            }
+          } catch {
+            // The editor was disposed; nothing to clear.
+          }
+        }
+        highlighted.clear();
+      }
+    });
+
+    if (palette) {
+      const category = trans.__('Other');
+      palette.addItem({ command: HIGHLIGHT_LINES_COMMAND, category });
+      palette.addItem({ command: CLEAR_HIGHLIGHTS_COMMAND, category });
+    }
+  }
+};
+
+export default plugin;

package/src/index.ts

@@ -1,17 +1,23 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 
 import agentSessionsPlugin from './agentSessions';
+import commandBarPlugin from './commandBar';
 import fileBrowserPlugin from './fileBrowser';
 import fileTypeIconsPlugin from './fileTypeIcons';
 import editorBreadcrumbsPlugin from './editorBreadcrumbs';
 import editorIndentPlugin from './editorIndent';
 import gitPlugins from './git';
+import highlightPlugin from './highlight';
 import launcherPlugins from './launcher';
 import menusPlugin from './menus';
+import omniboxPlugin from './omnibox';
+import searchReplacePlugin from './searchReplace';
+import showOutputPlugin from './showOutput';
 import sidebarPlugin from './sidebar';
 import terminalNotificationsPlugin from './terminalNotifications';
 import terminalsPlugin from './terminals';
 import topBarPlugin from './topBar';
+import walkthroughPlugin from './walkthrough';
 
 /**
  * Every plugin contributed by `xtralab`. The entry point of the
@@ -24,17 +30,23 @@ import topBarPlugin from './topBar';
  */
 const plugins: JupyterFrontEndPlugin<unknown>[] = [
   agentSessionsPlugin,
+  commandBarPlugin,
   editorBreadcrumbsPlugin,
   editorIndentPlugin,
   fileBrowserPlugin,
   fileTypeIconsPlugin,
   ...gitPlugins,
+  highlightPlugin,
   ...launcherPlugins,
   menusPlugin,
+  omniboxPlugin,
+  searchReplacePlugin,
+  showOutputPlugin,
   sidebarPlugin,
   terminalNotificationsPlugin,
   terminalsPlugin,
-  topBarPlugin
+  topBarPlugin,
+  walkthroughPlugin
 ];
 
 export default plugins;

package/src/launcher/agents.ts

@@ -178,6 +178,31 @@ const DEFAULTS: IAgent[] = [
   }
 ];
 
+/**
+ * The built-in agents projected into the JSON settings shape
+ * ({@link IAgentSettings}), dropping the runtime-only {@link LabIcon}.
+ * {@link registerLauncherSchemaDefaults} injects this as the `agents` setting's
+ * schema default so the Settings Editor shows the shipped list.
+ */
+export function defaultAgentSettings(): IAgentSettings[] {
+  return DEFAULTS.map(agent => {
+    const entry: IAgentSettings = {
+      id: agent.id,
+      label: agent.label,
+      caption: agent.caption,
+      command: agent.command,
+      rank: agent.rank,
+      requireAvailable: agent.requireAvailable
+    };
+    // Omit `promptArgs` for agents that don't take an inline prompt, so the
+    // default doesn't show a prompt form they lack.
+    if (agent.promptArgs !== undefined) {
+      entry.promptArgs = agent.promptArgs;
+    }
+    return entry;
+  });
+}
+
 function resolveIcon(id: string, iconSvg: string | undefined): LabIcon {
   if (iconSvg) {
     return new LabIcon({ name: `xtralab:agent-custom-${id}`, svgstr: iconSvg });