xtralab 0.5.0 → 0.7.0

package/src/launcher/commands.ts

@@ -1,24 +1,19 @@
 import type { JupyterFrontEnd } from '@jupyterlab/application';
 import type { MainAreaWidget } from '@jupyterlab/apputils';
 import type { ITerminal } from '@jupyterlab/terminal';
+import type { CommandRegistry } from '@lumino/commands';
 import { DisposableSet, type IDisposable } from '@lumino/disposable';
 
+import type { IAgentSessions } from '../agentSessions';
 import type { IAgent } from './agents';
 import { buildAgentInvocation } from './invocation';
+import { agentCommandId } from './tokens';
 
 /**
  * The command id for opening the launcher.
  */
 export const CREATE_LAUNCHER_COMMAND = 'launcher:create';
 
-/**
- * Build a JupyterLab command id for a given agent. Centralised so the
- * plugin and the launcher both use the same names.
- */
-export function agentCommandId(agentId: string): string {
-  return `xtralab:start-agent:${agentId}`;
-}
-
 /**
  * Register a JupyterLab command per agent. Each command opens a new
  * terminal via `terminal:create-new` and feeds the agent's shell command
@@ -27,10 +22,16 @@ export function agentCommandId(agentId: string): string {
  * Returns a single disposable that tears down every registered command —
  * the launcher disposes the previous set before re-registering on settings
  * changes so the command palette stays in sync with the configured agents.
+ *
+ * When an `agentSessions` registry is supplied, each launch tags its terminal
+ * session with the agent's command, so the terminals panel can badge the row
+ * with the agent's logo immediately (before server-side detection confirms
+ * it).
  */
 export function registerAgentCommands(
   app: JupyterFrontEnd,
-  agents: IAgent[]
+  agents: IAgent[],
+  agentSessions: IAgentSessions | null = null
 ): IDisposable {
   const disposables = new DisposableSet();
   for (const agent of agents) {
@@ -43,61 +44,98 @@ export function registerAgentCommands(
         const promptArg = args['prompt'];
         const prompt = typeof promptArg === 'string' ? promptArg : '';
         const invocation = buildAgentInvocation(agent, prompt);
-        const main = (await app.commands.execute('terminal:create-new', {
-          cwd
-        })) as MainAreaWidget<ITerminal.ITerminal>;
-        // `MainAreaWidget.revealed` chains off the `reveal` promise the
-        // terminal extension passes in (the xterm.js widget's own `ready`
-        // promise), so awaiting it guarantees the Terminal widget has
-        // finished its constructor and connected its session listeners.
-        await main.revealed;
+        return launchInTerminal(app.commands, {
+          cwd,
+          invocation,
+          label: agent.label,
+          // Optimistically tag the session with this agent so the terminals
+          // panel can show its logo right away; server-side detection takes
+          // over as the source of truth on its next poll.
+          onSession: name => agentSessions?.set(name, agent.command)
+        });
+      }
+    });
+    disposables.add(disposable);
+  }
+  return disposables;
+}
 
-        const session = main.content.session;
-        const sendCommand = (): void => {
-          session.send({
-            type: 'stdin',
-            content: [invocation + '\r']
-          });
-          // Give the tab and the status-bar list a meaningful default
-          // label. The XTerm widget's `_initialConnection` listener
-          // overwrites the title with `Terminal {N}` when the WebSocket
-          // first reports `connected`; we connect *after* that listener
-          // (and call `applyAgentLabel` after `sendCommand`), so by the
-          // time we run the upstream listener has already had its turn.
-          // Programs that publish a real xterm title escape sequence
-          // still win — `XTerm.onTitleChange` resets the label whenever
-          // it fires.
-          applyAgentLabel();
-        };
+/**
+ * Open a fresh terminal, type `invocation` into it as if the user had, and
+ * label the tab. Shared by the per-agent launch commands and the launcher's
+ * editor tile so the fiddly "wait for the websocket, then write stdin"
+ * sequence lives in one place.
+ *
+ * `onSession`, when given, is called once with the new session's name right
+ * after the terminal is revealed. Callers use it to optimistically tag the
+ * session so the terminals panel can badge it with the agent's (or editor's)
+ * logo before server-side detection confirms the running process.
+ *
+ * Resolves with the host `MainAreaWidget` so the caller can place it — the
+ * launcher swaps it into its own tab.
+ */
+export async function launchInTerminal(
+  commands: CommandRegistry,
+  options: {
+    cwd?: string;
+    /** The literal command line typed into the fresh terminal. */
+    invocation: string;
+    /** Tab/title label applied once the command is sent. */
+    label: string;
+    onSession?: (sessionName: string) => void;
+  }
+): Promise<MainAreaWidget<ITerminal.ITerminal>> {
+  const { cwd, invocation, label, onSession } = options;
+  const main = (await commands.execute('terminal:create-new', {
+    cwd
+  })) as MainAreaWidget<ITerminal.ITerminal>;
+  // `MainAreaWidget.revealed` chains off the `reveal` promise the terminal
+  // extension passes in (the xterm.js widget's own `ready` promise), so
+  // awaiting it guarantees the Terminal widget has finished its constructor
+  // and connected its session listeners.
+  await main.revealed;
 
-        const applyAgentLabel = (): void => {
-          if (main.isDisposed || main.content.isDisposed) {
-            return;
-          }
-          main.content.title.label = agent.label;
-        };
+  const session = main.content.session;
+  onSession?.(session.name);
 
-        // Match how the Terminal widget itself sends its `initialCommand`:
-        // either fire immediately if the session is already connected, or
-        // wait for the next `connectionStatusChanged` that flips it to
-        // `connected`. Without this the stdin write races the websocket
-        // handshake and the agent command silently disappears.
-        if (session.connectionStatus === 'connected') {
-          sendCommand();
-        } else {
-          const onStatus = (): void => {
-            if (session.connectionStatus === 'connected') {
-              session.connectionStatusChanged.disconnect(onStatus);
-              sendCommand();
-            }
-          };
-          session.connectionStatusChanged.connect(onStatus);
-        }
+  const applyLabel = (): void => {
+    if (main.isDisposed || main.content.isDisposed) {
+      return;
+    }
+    main.content.title.label = label;
+  };
 
-        return main;
-      }
+  const sendCommand = (): void => {
+    session.send({
+      type: 'stdin',
+      content: [invocation + '\r']
     });
-    disposables.add(disposable);
+    // Give the tab and the status-bar list a meaningful default label. The
+    // XTerm widget's `_initialConnection` listener overwrites the title with
+    // `Terminal {N}` when the WebSocket first reports `connected`; we connect
+    // *after* that listener (and call `applyLabel` after `sendCommand`), so by
+    // the time we run the upstream listener has already had its turn. Programs
+    // that publish a real xterm title escape sequence still win —
+    // `XTerm.onTitleChange` resets the label whenever it fires.
+    applyLabel();
+  };
+
+  // Match how the Terminal widget itself sends its `initialCommand`: either
+  // fire immediately if the session is already connected, or wait for the next
+  // `connectionStatusChanged` that flips it to `connected`. Without this the
+  // stdin write races the websocket handshake and the command silently
+  // disappears.
+  if (session.connectionStatus === 'connected') {
+    sendCommand();
+  } else {
+    const onStatus = (): void => {
+      if (session.connectionStatus === 'connected') {
+        session.connectionStatusChanged.disconnect(onStatus);
+        sendCommand();
+      }
+    };
+    session.connectionStatusChanged.connect(onStatus);
   }
-  return disposables;
+
+  return main;
 }

package/src/launcher/dashboard.tsx

@@ -3,6 +3,7 @@ import * as React from 'react';
 import type { CommandRegistry } from '@lumino/commands';
 import type { ReadonlyPartialJSONObject } from '@lumino/coreutils';
 import { Poll } from '@lumino/polling';
+import type { IDocumentWidget } from '@jupyterlab/docregistry';
 import {
   LabIcon,
   ReactWidget,
@@ -13,6 +14,7 @@ import {
 } from '@jupyterlab/ui-components';
 import type { Widget } from '@lumino/widgets';
 
+import type { IAgentSessions } from '../agentSessions';
 import { expandStatusFiles, status } from '../git/api';
 import {
   CommandIDs as GitCommandIDs,
@@ -25,7 +27,9 @@ import type {
 } from '../git/tokens';
 
 import type { IAgent } from './agents';
-import { agentCommandId } from './commands';
+import { launchInTerminal } from './commands';
+import type { IEditor } from './editors';
+import { agentCommandId } from './tokens';
 
 /**
  * Public construction options for the launcher dashboard widget. The
@@ -41,6 +45,19 @@ export interface ILauncherDashboardOptions {
    * rank; the widget renders them as-is.
    */
   agents: IAgent[];
+  /**
+   * The terminal editor to offer in the "Open" section (Neovim preferred over
+   * Vim), or `null` when neither is installed. Resolved by the plugin from the
+   * same availability probe that filters the agents.
+   */
+  editor: IEditor | null;
+  /**
+   * Shared launch-tag registry. When the editor tile launches, it records the
+   * session here so the terminals panel badges it with the editor's logo right
+   * away, the same as agent launches do. `null` when the provider plugin is
+   * unavailable.
+   */
+  agentSessions: IAgentSessions | null;
   /**
    * Called after an agent command has returned its top-level widget. The
    * plugin uses this to swap the new terminal into the launcher's tab.
@@ -101,7 +118,15 @@ const CHANGES_POLL_MAX_MS = 300_000;
 function LauncherDashboardComponent(
   props: ILauncherDashboardOptions
 ): React.ReactElement {
-  const { commands, agents, onAgentLaunch, repoPath, cwd } = props;
+  const {
+    commands,
+    agents,
+    editor,
+    agentSessions,
+    onAgentLaunch,
+    repoPath,
+    cwd
+  } = props;
   const [prompt, setPrompt] = React.useState('');
   const [git, setGit] = React.useState<IGitState>({
     loading: true,
@@ -169,13 +194,28 @@ function LauncherDashboardComponent(
   }, [commands, cwd, onAgentLaunch]);
 
   const launchNotebook = React.useCallback(async () => {
-    // No `kernelName` — let the notebook extension fall back to the default
-    // kernel or prompt the user, matching the stock launcher's notebook
-    // tile behavior.
-    const result = (await commands.execute('notebook:create-new', {
-      cwd
-    })) as Widget | undefined;
+    // Open a fresh notebook with no kernel attached — equivalent to clicking
+    // "No Kernel" in the Select Kernel dialog. `notebook:create-new` always
+    // routes through that dialog when no kernelName is given, so drive the
+    // underlying docmanager steps directly and pass `shouldStart: false` to
+    // suppress kernel selection. The user picks a kernel from the notebook
+    // toolbar when they're ready.
+    const file = (await commands.execute('docmanager:new-untitled', {
+      path: cwd,
+      type: 'notebook'
+    })) as { path: string } | undefined;
+    if (!file) {
+      return;
+    }
+    const result = (await commands.execute('docmanager:open', {
+      path: file.path,
+      factory: 'Notebook',
+      kernelPreference: { shouldStart: false, canStart: true }
+    })) as IDocumentWidget | undefined;
     if (result) {
+      // Match `notebook:create-new`'s post-open marker so the first manual
+      // save offers a rename instead of overwriting the auto-generated name.
+      result.isUntitled = true;
       onAgentLaunch(result);
     }
   }, [commands, cwd, onAgentLaunch]);
@@ -189,6 +229,23 @@ function LauncherDashboardComponent(
     }
   }, [commands, cwd, onAgentLaunch]);
 
+  const launchEditor = React.useCallback(async () => {
+    if (!editor) {
+      return;
+    }
+    // An editor is "open a terminal and type its command" — the agent launch
+    // minus the prompt — so it shares `launchInTerminal` rather than the native
+    // `terminal:create-new` call the tiles above use, and tags the session the
+    // same way so the terminals panel badges it with the editor's logo.
+    const result = await launchInTerminal(commands, {
+      cwd,
+      invocation: editor.command,
+      label: editor.label,
+      onSession: name => agentSessions?.set(name, editor.command)
+    });
+    onAgentLaunch(result);
+  }, [commands, cwd, editor, agentSessions, onAgentLaunch]);
+
   const openDiff = React.useCallback(
     (change: IFileChange) => {
       const args: GitCommandArguments.IOpenDiff = { repoPath, change };
@@ -208,10 +265,13 @@ function LauncherDashboardComponent(
         onPromptChange={setPrompt}
         onLaunch={launch}
       />
+      <McpSection agents={agents} />
       <OpenSection
+        editor={editor}
         onLaunchTerminal={launchTerminal}
         onLaunchNotebook={launchNotebook}
         onLaunchConsole={launchConsole}
+        onLaunchEditor={launchEditor}
       />
       <ChangesSection
         git={git}
@@ -410,19 +470,159 @@ function AgentSection(props: {
   );
 }
 
+/**
+ * Launcher agents whose CLI has a clean, non-interactive `mcp add` that takes
+ * `<name> -- <command>`. The other agents (Goose, OpenCode, Kiro, Mistral
+ * Vibe, Antigravity) register MCP through their own config files or UI, so
+ * there is no one-line command to surface for them.
+ */
+const MCP_ADD_AGENT_IDS = new Set(['claude', 'codex', 'copilot']);
+
+/** The stdio proxy console script that bridges an agent to the MCP server. */
+const MCP_PROXY_COMMAND = 'jupyter-server-mcp-proxy';
+
+/**
+ * Copy `text` to the clipboard via a hidden, selected `<textarea>` and the
+ * legacy `execCommand('copy')`. Deprecated, but still the most reliable path
+ * under a user gesture when the async Clipboard API is unavailable or blocked
+ * (the desktop app's Electron window can deny clipboard writes by policy).
+ * Returns whether the copy succeeded.
+ */
+function legacyCopy(text: string): boolean {
+  try {
+    const textarea = document.createElement('textarea');
+    textarea.value = text;
+    textarea.setAttribute('readonly', '');
+    textarea.style.position = 'fixed';
+    textarea.style.top = '-1000px';
+    textarea.style.opacity = '0';
+    document.body.appendChild(textarea);
+    textarea.select();
+    const ok = document.execCommand('copy');
+    document.body.removeChild(textarea);
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A collapsed-by-default hint listing the one-line command that registers
+ * xtralab's running Jupyter MCP server with each installed agent that
+ * supports `mcp add`. Copy-only: the user runs it in their own terminal,
+ * where the server is reachable with no port to configure — the desktop
+ * supervisor exports `JUPYTER_SERVER_MCP_URL`, and `pip` installs let the
+ * proxy discover the server from its runtime file. Renders nothing when none
+ * of those agents are on `$PATH`.
+ */
+function McpSection(props: { agents: IAgent[] }): React.ReactElement | null {
+  const [copiedId, setCopiedId] = React.useState<string | null>(null);
+  const registerable = props.agents.filter(agent =>
+    MCP_ADD_AGENT_IDS.has(agent.id)
+  );
+  if (registerable.length === 0) {
+    return null;
+  }
+
+  const flagCopied = (id: string): void => {
+    setCopiedId(id);
+    window.setTimeout(
+      () => setCopiedId(current => (current === id ? null : current)),
+      1500
+    );
+  };
+
+  const copy = (command: string, id: string): void => {
+    // Prefer the async Clipboard API; fall back to `legacyCopy` when it's
+    // missing or rejects (Electron can block it by policy). Flag "Copied" only
+    // once a copy actually succeeds.
+    const clipboard = navigator.clipboard;
+    if (clipboard) {
+      void clipboard.writeText(command).then(
+        () => flagCopied(id),
+        () => {
+          if (legacyCopy(command)) {
+            flagCopied(id);
+          }
+        }
+      );
+    } else if (legacyCopy(command)) {
+      flagCopied(id);
+    }
+  };
+
+  return (
+    <details className="jp-xtralab-Launcher-section jp-xtralab-Launcher-mcp-section">
+      <summary className="jp-xtralab-Launcher-section-summary">
+        <span className="jp-xtralab-Launcher-section-title">
+          Connect agents to JupyterLab (MCP)
+        </span>
+      </summary>
+      <div className="jp-xtralab-Launcher-section-body">
+        <p className="jp-xtralab-Launcher-agent-hint">
+          Run once per agent to let it drive this JupyterLab over MCP. No port
+          needed — the proxy finds this server on its own.
+        </p>
+        <ul className="jp-xtralab-Launcher-mcp-list">
+          {registerable.map(agent => {
+            const command = `${agent.command} mcp add jupyter -- ${MCP_PROXY_COMMAND}`;
+            return (
+              <li key={agent.id} className="jp-xtralab-Launcher-mcp-item">
+                <code className="jp-xtralab-Launcher-mcp-command">
+                  {command}
+                </code>
+                <button
+                  type="button"
+                  className={
+                    copiedId === agent.id
+                      ? 'jp-xtralab-Launcher-mcp-copy jp-mod-copied'
+                      : 'jp-xtralab-Launcher-mcp-copy'
+                  }
+                  aria-label={`Copy the ${agent.label} command`}
+                  onClick={() => copy(command, agent.id)}
+                >
+                  {copiedId === agent.id ? 'Copied!' : 'Copy'}
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+        <p className="jp-xtralab-Launcher-mcp-note">
+          Other agents (Goose, OpenCode, Kiro, Mistral Vibe, Antigravity)
+          register MCP through their own config — point them at the same{' '}
+          <code>{MCP_PROXY_COMMAND}</code> command.
+        </p>
+      </div>
+    </details>
+  );
+}
+
 /**
  * The non-agent launch tiles — a plain terminal, a new notebook, and a
  * new console. They sit in a separate section below the agent grid so
  * they don't compete with the AI agents visually, and they're always
  * available regardless of the agent prompt textarea (which doesn't
  * apply to them).
+ *
+ * A terminal editor (Neovim, else Vim) joins the row when one is installed —
+ * it opens in a terminal like the agents do, so it lives here rather than in
+ * the agent grid. When neither is on `$PATH`, `editor` is `null` and no tile
+ * renders.
  */
 function OpenSection(props: {
+  editor: IEditor | null;
   onLaunchTerminal: () => void;
   onLaunchNotebook: () => void;
   onLaunchConsole: () => void;
+  onLaunchEditor: () => void;
 }): React.ReactElement {
-  const { onLaunchTerminal, onLaunchNotebook, onLaunchConsole } = props;
+  const {
+    editor,
+    onLaunchTerminal,
+    onLaunchNotebook,
+    onLaunchConsole,
+    onLaunchEditor
+  } = props;
   return (
     <section className="jp-xtralab-Launcher-section">
       <h2 className="jp-xtralab-Launcher-section-title">Open</h2>
@@ -469,6 +669,24 @@ function OpenSection(props: {
           />
           <span className="jp-xtralab-Launcher-agent-label">Console</span>
         </button>
+        {editor && (
+          <button
+            type="button"
+            className="jp-xtralab-Launcher-agent"
+            title={editor.caption}
+            aria-label={editor.caption}
+            onClick={onLaunchEditor}
+          >
+            <LabIcon.resolveReact
+              icon={editor.icon}
+              tag="span"
+              className="jp-xtralab-Launcher-agent-icon"
+            />
+            <span className="jp-xtralab-Launcher-agent-label">
+              {editor.label}
+            </span>
+          </button>
+        )}
       </div>
     </section>
   );

package/src/launcher/editorRegistry.ts

@@ -0,0 +1,149 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { Token } from '@lumino/coreutils';
+import { ISignal, Signal } from '@lumino/signaling';
+
+import { fetchAvailableCommands } from './availability';
+import {
+  mergeEditors,
+  resolveEditor,
+  type IEditor,
+  type IEditorSettings
+} from './editors';
+
+/**
+ * A read-only, observable view of the launcher's terminal editors: xtralab's
+ * built-ins (Neovim, Vim) merged with the user's `editors` setting, sorted by
+ * rank, with disabled entries removed.
+ */
+export interface IEditorRegistry {
+  /**
+   * The full merged editor list (disabled entries already removed). The
+   * terminals panel uses it to badge a row for any configured editor that is
+   * running, and to tell the server which editor commands to detect.
+   */
+  readonly editors: IEditor[];
+
+  /**
+   * The single editor tile the launcher shows: the first editor, by rank, whose
+   * command is on `$PATH` (Neovim before Vim by default), or `null` when none
+   * qualifies.
+   */
+  readonly current: IEditor | null;
+
+  /**
+   * Emitted whenever {@link editors} or {@link current} changes (the user
+   * edited the `editors` setting). Consumers that read on demand can ignore it.
+   */
+  readonly changed: ISignal<IEditorRegistry, void>;
+}
+
+/**
+ * DI token for {@link IEditorRegistry}. Provided by `xtralab:editor-registry`
+ * and consumed — optionally — by `xtralab:launcher` (for its tile) and
+ * `xtralab:terminals` (to badge running editors with their logo).
+ */
+export const IEditorRegistry = new Token<IEditorRegistry>(
+  'xtralab:IEditorRegistry',
+  'A read-only, observable view of the launcher terminal editors, shared so the launcher tile and the terminals panel agree on the list and icons.'
+);
+
+/**
+ * Concrete {@link IEditorRegistry}. The provider plugin is the only writer, so
+ * the write side ({@link set}) is kept off the shared token.
+ */
+class EditorRegistry implements IEditorRegistry {
+  get editors(): IEditor[] {
+    return this._editors;
+  }
+
+  get current(): IEditor | null {
+    return this._current;
+  }
+
+  get changed(): ISignal<IEditorRegistry, void> {
+    return this._changed;
+  }
+
+  /** Replace both lists (recomputed together) and notify observers. */
+  set(editors: IEditor[], current: IEditor | null): void {
+    this._editors = editors;
+    this._current = current;
+    this._changed.emit();
+  }
+
+  private _editors: IEditor[] = [];
+  private _current: IEditor | null = null;
+  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
+ * tile, and re-runs both on a settings change.
+ *
+ * `activate` awaits the first probe before returning, so a consumer reading
+ * {@link IEditorRegistry.current} on activation sees a resolved tile.
+ */
+export const editorRegistryPlugin: JupyterFrontEndPlugin<IEditorRegistry> = {
+  id: 'xtralab:editor-registry',
+  description:
+    "Provides the launcher's terminal-editor list (Neovim, Vim, or user-configured), resolved against the server PATH.",
+  autoStart: true,
+  provides: IEditorRegistry,
+  optional: [ISettingRegistry],
+  activate: async (
+    app: JupyterFrontEnd,
+    settingRegistry: ISettingRegistry | null
+  ): Promise<IEditorRegistry> => {
+    const registry = new EditorRegistry();
+
+    const apply = async (overrides: IEditorSettings[]): Promise<void> => {
+      const editors = mergeEditors(overrides);
+      // Probe only the editors that opt into the availability check; entries
+      // with `requireAvailable: false` (e.g. a shell alias) are shown
+      // regardless and don't need a `which` lookup.
+      const probe = editors
+        .filter(editor => editor.requireAvailable)
+        .map(editor => editor.command);
+      const available = await fetchAvailableCommands(probe);
+      registry.set(editors, resolveEditor(editors, available));
+    };
+
+    const readOverrides = (
+      settings: ISettingRegistry.ISettings
+    ): IEditorSettings[] => {
+      const raw = settings.composite.editors;
+      return Array.isArray(raw) ? (raw as IEditorSettings[]) : [];
+    };
+
+    if (settingRegistry) {
+      try {
+        const settings = await settingRegistry.load(LAUNCHER_SETTINGS_ID);
+        await apply(readOverrides(settings));
+        settings.changed.connect(async () => {
+          try {
+            await apply(readOverrides(settings));
+          } catch (reason) {
+            console.error('xtralab: failed to reapply editor settings', reason);
+          }
+        });
+      } catch (reason) {
+        console.error('xtralab: failed to load editor settings', reason);
+        // Settings load failed — fall back to the built-in editors so the
+        // launcher tile still resolves instead of going silent.
+        await apply([]);
+      }
+    } else {
+      await apply([]);
+    }
+
+    return registry;
+  }
+};