xtralab 0.10.0 → 0.11.1

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

@@ -63,7 +63,12 @@ export interface IAgentSettings {
    * palette. Defaults to true.
    */
   enabled?: boolean;
-  /** See `IAgent.requireAvailable`. */
+  /**
+   * See `IAgent.requireAvailable`. Defaults to true for a built-in agent that
+   * still uses its shipped command, and to false once you override the
+   * `command` (a user-chosen command — often a shell alias — is trusted and
+   * always shown). Set it explicitly to force the check on or off.
+   */
   requireAvailable?: boolean;
   /**
    * See `IAgent.promptArgs`. Pass an empty array to mark the agent as
@@ -178,6 +183,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 });
@@ -190,6 +220,11 @@ function resolveIcon(id: string, iconSvg: string | undefined): LabIcon {
  * their built-in fields unless explicitly overridden; user-only entries are
  * appended. `enabled: false` filters an entry out of the result entirely
  * (so callers don't need to check the flag again).
+ *
+ * Overriding a built-in agent's `command` also turns its `requireAvailable`
+ * off, so the card survives the launcher's `which`-based availability filter
+ * even when the new command is a shell alias the server can't resolve. See the
+ * built-in branch below for the rationale.
  */
 export function mergeAgents(overrides: IAgentSettings[]): IAgent[] {
   const overrideById = new Map(overrides.map(entry => [entry.id, entry]));
@@ -205,16 +240,31 @@ export function mergeAgents(overrides: IAgentSettings[]): IAgent[] {
     if (override.enabled === false) {
       continue;
     }
+    const command = override.command ?? base.command;
     merged.push({
       id: base.id,
       label: override.label ?? base.label,
       caption: override.caption ?? base.caption,
-      command: override.command ?? base.command,
+      command,
       icon: override.iconSvg
         ? resolveIcon(base.id, override.iconSvg)
         : base.icon,
       rank: override.rank ?? base.rank,
-      requireAvailable: override.requireAvailable ?? base.requireAvailable,
+      // The availability filter exists to prune xtralab's *built-in* command
+      // from the launcher when it isn't installed. Once the user points the
+      // agent at their own command — e.g. the `ccm` alias wrapping `claude
+      // --effort=max …` — the server's `shutil.which` probe can't see it
+      // (aliases and shell functions only exist inside an interactive shell),
+      // so keeping the check on would wrongly hide the card. We therefore only
+      // require availability while the command is still xtralab's default; a
+      // user-chosen command is trusted and always shown. An explicit
+      // `requireAvailable` still applies to the unchanged default command, so a
+      // user can alias `claude` itself and set `requireAvailable: false` (or
+      // force the check back on).
+      requireAvailable:
+        command === base.command
+          ? (override.requireAvailable ?? base.requireAvailable)
+          : false,
       // `null` is the explicit way to opt out of an agent's default prompt
       // support; an absent key keeps the default. `undefined` from `??` is
       // pruned below.

package/src/launcher/editorRegistry.ts

@@ -13,6 +13,10 @@ import {
   type IEditor,
   type IEditorSettings
 } from './editors';
+import {
+  LAUNCHER_PLUGIN_ID,
+  registerLauncherSchemaDefaults
+} from './schemaDefaults';
 
 /**
  * A read-only, observable view of the launcher's terminal editors: xtralab's
@@ -80,9 +84,6 @@ class EditorRegistry implements IEditorRegistry {
   private _changed = new Signal<IEditorRegistry, void>(this);
 }
 
-/** Schema id the `editors` setting lives under (shared with the launcher). */
-const LAUNCHER_SETTINGS_ID = 'xtralab:launcher';
-
 /**
  * Provides {@link IEditorRegistry}: merges xtralab's built-in editors with the
  * user's `editors` setting, probes the server's `$PATH` to resolve the launcher
@@ -124,8 +125,11 @@ export const editorRegistryPlugin: JupyterFrontEndPlugin<IEditorRegistry> = {
     };
 
     if (settingRegistry) {
+      // Must precede the first `load`: the schema defers loading until a
+      // transform is registered.
+      registerLauncherSchemaDefaults(settingRegistry);
       try {
-        const settings = await settingRegistry.load(LAUNCHER_SETTINGS_ID);
+        const settings = await settingRegistry.load(LAUNCHER_PLUGIN_ID);
         await apply(readOverrides(settings));
         settings.changed.connect(async () => {
           try {

package/src/launcher/editors.ts

@@ -57,7 +57,12 @@ export interface IEditorSettings {
    * the editor tile entirely. Defaults to true.
    */
   enabled?: boolean;
-  /** See {@link IEditor.requireAvailable}. */
+  /**
+   * See {@link IEditor.requireAvailable}. Defaults to true for a built-in
+   * editor that still uses its shipped command, and to false once you override
+   * the `command` (a user-chosen command — often a shell alias — is trusted and
+   * always shown). Set it explicitly to force the check on or off.
+   */
   requireAvailable?: boolean;
 }
 
@@ -88,6 +93,24 @@ const DEFAULTS: IEditor[] = [
   }
 ];
 
+/**
+ * The built-in editors projected into the JSON settings shape
+ * ({@link IEditorSettings}), dropping the runtime-only {@link LabIcon}. Mirrors
+ * {@link defaultAgentSettings}: {@link registerLauncherSchemaDefaults} injects
+ * this as the `editors` setting's schema default so the Settings Editor shows
+ * the shipped list.
+ */
+export function defaultEditorSettings(): IEditorSettings[] {
+  return DEFAULTS.map(editor => ({
+    id: editor.id,
+    label: editor.label,
+    caption: editor.caption,
+    command: editor.command,
+    rank: editor.rank,
+    requireAvailable: editor.requireAvailable
+  }));
+}
+
 function resolveEditorIcon(id: string, iconSvg: string | undefined): LabIcon {
   if (iconSvg) {
     return new LabIcon({
@@ -103,7 +126,9 @@ function resolveEditorIcon(id: string, iconSvg: string | undefined): LabIcon {
  * entries keep their fields unless explicitly overridden; user-only entries are
  * appended. `enabled: false` filters an entry out of the result entirely (so
  * callers don't need to re-check the flag). The result is sorted by rank, which
- * is also the launcher's tile-preference order. Mirrors `mergeAgents`.
+ * is also the launcher's tile-preference order. Mirrors `mergeAgents`, including
+ * turning `requireAvailable` off when the user overrides a built-in's `command`
+ * so an aliased editor still shows.
  */
 export function mergeEditors(overrides: IEditorSettings[]): IEditor[] {
   const overrideById = new Map(overrides.map(entry => [entry.id, entry]));
@@ -119,16 +144,24 @@ export function mergeEditors(overrides: IEditorSettings[]): IEditor[] {
     if (override.enabled === false) {
       continue;
     }
+    const command = override.command ?? base.command;
     merged.push({
       id: base.id,
       label: override.label ?? base.label,
       caption: override.caption ?? base.caption,
-      command: override.command ?? base.command,
+      command,
       icon: override.iconSvg
         ? resolveEditorIcon(base.id, override.iconSvg)
         : base.icon,
       rank: override.rank ?? base.rank,
-      requireAvailable: override.requireAvailable ?? base.requireAvailable
+      // See `mergeAgents`: once the user points a built-in editor at their own
+      // command (e.g. a shell alias `which` can't resolve), stop requiring
+      // availability so the tile still shows. The check stays on only while the
+      // command is xtralab's default.
+      requireAvailable:
+        command === base.command
+          ? (override.requireAvailable ?? base.requireAvailable)
+          : false
     });
   }
 

package/src/launcher/index.ts

@@ -19,6 +19,7 @@ import { CREATE_LAUNCHER_COMMAND, registerAgentCommands } from './commands';
 import { LauncherDashboard } from './dashboard';
 import { editorRegistryPlugin, IEditorRegistry } from './editorRegistry';
 import { AgentRegistry } from './registry';
+import { registerLauncherSchemaDefaults } from './schemaDefaults';
 import { IAgentRegistry } from './tokens';
 
 const PLUGIN_ID = 'xtralab:launcher';
@@ -36,7 +37,9 @@ const PLUGIN_ID = 'xtralab:launcher';
  * The agent list is the merge of xtralab's defaults with the user's
  * `xtralab:launcher` settings, then filtered by a server-side `which`
  * check so users only see agents that are actually installed. Agents with
- * `requireAvailable: false` (e.g. shell aliases) skip the filter.
+ * `requireAvailable: false` skip the filter, as does any built-in whose
+ * `command` the user has overridden (a user-chosen command — often a shell
+ * alias the server can't resolve — is trusted and always shown).
  *
  * The plugin deliberately does NOT provide the `ILauncher` token: other
  * extensions register notebook/console/terminal cards on it as a side
@@ -110,6 +113,9 @@ const plugin: JupyterFrontEndPlugin<IAgentRegistry> = {
     };
 
     if (settingRegistry) {
+      // Must precede the first `load`: the schema defers loading until a
+      // transform is registered.
+      registerLauncherSchemaDefaults(settingRegistry);
       try {
         const settings = await settingRegistry.load(PLUGIN_ID);
         await applyAgents(readOverrides(settings));

package/src/launcher/schemaDefaults.ts

@@ -0,0 +1,53 @@
+import type { PartialJSONValue } from '@lumino/coreutils';
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+
+import { defaultAgentSettings } from './agents';
+import { defaultEditorSettings } from './editors';
+
+/** Schema id the launcher's `agents`/`editors` settings live under. */
+export const LAUNCHER_PLUGIN_ID = 'xtralab:launcher';
+
+/**
+ * Setting registries that already have the transform, so both callers skip
+ * re-registering (the registry rejects a duplicate transformer).
+ */
+const registered = new WeakSet<ISettingRegistry>();
+
+/**
+ * Register a `fetch` transform that injects xtralab's built-in agent and
+ * editor lists as the schema defaults for the `xtralab:launcher` settings, so
+ * the Settings Editor shows the shipped list.
+ *
+ * The schema declares `jupyter.lab.transform: true`, so the registry defers
+ * loading the plugin until a transform is registered: callers must invoke this
+ * before their first `settingRegistry.load(LAUNCHER_PLUGIN_ID)`. Idempotent, so
+ * the two plugins that load these settings can both call it regardless of
+ * activation order.
+ */
+export function registerLauncherSchemaDefaults(
+  settingRegistry: ISettingRegistry
+): void {
+  if (registered.has(settingRegistry)) {
+    return;
+  }
+  registered.add(settingRegistry);
+
+  settingRegistry.transform(LAUNCHER_PLUGIN_ID, {
+    fetch: plugin => {
+      const properties = plugin.schema.properties;
+      if (properties) {
+        // The settings shapes are plain JSON by construction, but their named
+        // interfaces lack an index signature, so cast at this TS→JSON boundary.
+        if (properties.agents) {
+          properties.agents.default =
+            defaultAgentSettings() as unknown as PartialJSONValue;
+        }
+        if (properties.editors) {
+          properties.editors.default =
+            defaultEditorSettings() as unknown as PartialJSONValue;
+        }
+      }
+      return plugin;
+    }
+  });
+}

package/src/omnibox/files.ts

@@ -0,0 +1,68 @@
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+
+/**
+ * Shape of the `jupyterlab-quickopen` `api/files` response: a map from each
+ * directory (relative to the server root, `""` for the root itself) to the
+ * bare filenames it contains.
+ */
+interface IQuickOpenContents {
+  contents: { [dir: string]: string[] };
+}
+
+/**
+ * Fetch and flatten the workspace file list from `jupyterlab-quickopen`'s
+ * server endpoint (`GET {base}/jupyterlab-quickopen/api/files`).
+ *
+ * We reuse quickopen's endpoint rather than walking the contents API so the
+ * listing honors the same server-side `.gitignore` filtering quickopen does
+ * (xtralab ships `respectGitignore: true`) in a single request. The endpoint
+ * only exists when quickopen's server extension is installed and the server
+ * reads a local filesystem; callers treat a rejection as "no file results".
+ */
+async function fetchWorkspaceFiles(respectGitignore = true): Promise<string[]> {
+  const settings = ServerConnection.makeSettings();
+  const params = new URLSearchParams();
+  if (respectGitignore) {
+    params.append('respect_gitignore', '1');
+  }
+  // The handler requires a `path` argument; `""` scans from the root.
+  params.append('path', '');
+  const url =
+    URLExt.join(settings.baseUrl, 'jupyterlab-quickopen', 'api', 'files') +
+    `?${params.toString()}`;
+
+  const response = await ServerConnection.makeRequest(
+    url,
+    { method: 'GET' },
+    settings
+  );
+  if (response.status !== 200) {
+    throw new ServerConnection.ResponseError(response);
+  }
+  const data = (await response.json()) as IQuickOpenContents;
+  const paths: string[] = [];
+  for (const dir in data.contents) {
+    for (const name of data.contents[dir]) {
+      paths.push(dir ? `${dir}/${name}` : name);
+    }
+  }
+  return paths;
+}
+
+const CACHE_TTL_MS = 15_000;
+let cache: { at: number; files: Promise<string[]> } | null = null;
+
+/**
+ * The workspace file list, cached briefly so reopening the omnibox in quick
+ * succession reuses one scan. A failed fetch (e.g. quickopen's server
+ * extension is absent) resolves to an empty list so file search degrades to
+ * "no results" instead of surfacing an error.
+ */
+export function loadWorkspaceFiles(): Promise<string[]> {
+  const now = Date.now();
+  if (!cache || now - cache.at > CACHE_TTL_MS) {
+    cache = { at: now, files: fetchWorkspaceFiles().catch(() => []) };
+  }
+  return cache.files;
+}