xtralab 0.11.1 → 0.12.0

package/src/terminals/agentTerminals.ts

@@ -0,0 +1,238 @@
+import type { Terminal } from '@jupyterlab/services';
+import type { ITerminalTracker } from '@jupyterlab/terminal';
+import type { TranslationBundle } from '@jupyterlab/translation';
+import { ISignal, Signal } from '@lumino/signaling';
+
+import { fetchRunningAgents } from './detection';
+import type { SessionRegistry, TerminalWidget } from './model';
+import type { IAgentTerminalSession, IAgentTerminals } from './tokens';
+
+/**
+ * Pause between pasting the prompt and pressing Enter, so the two reach the
+ * agent as separate PTY reads — the same shape as a human pasting and then
+ * submitting. Sent back to back, the server can coalesce both websocket
+ * messages into one read and the TUI would have to split the paste from the
+ * trailing Enter inside a single chunk.
+ */
+const PASTE_SUBMIT_DELAY_MS = 150;
+
+/**
+ * Bracketed-paste markers (`CSI 200~` / `CSI 201~`). The prompt is wrapped
+ * in these so the agent's TUI treats it as one pasted block — newlines
+ * insert into its input box instead of submitting the message at each line
+ * break. Every send target is a terminal where detection just confirmed a
+ * running coding agent, and the agent TUIs keep bracketed-paste mode on.
+ */
+const PASTE_OPEN = '\x1b[200~';
+const PASTE_CLOSE = '\x1b[201~';
+
+/**
+ * How long to wait for the session's websocket to reach `connected` before
+ * failing the send, so a server hiccup surfaces as an error notification
+ * rather than a silent hang.
+ */
+const CONNECT_TIMEOUT_MS = 10_000;
+
+/**
+ * Resolve once `session` reports `connected`; reject with `timeoutMessage`
+ * after {@link CONNECT_TIMEOUT_MS}. Matches how the launcher waits before
+ * typing into a fresh terminal — writes sent while the websocket is still
+ * connecting disappear silently.
+ */
+function waitUntilConnected(
+  session: Terminal.ITerminalConnection,
+  timeoutMessage: string
+): Promise<void> {
+  if (session.connectionStatus === 'connected') {
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve, reject) => {
+    const cleanup = (): void => {
+      window.clearTimeout(timer);
+      session.connectionStatusChanged.disconnect(onStatus);
+    };
+    const onStatus = (): void => {
+      if (session.connectionStatus === 'connected') {
+        cleanup();
+        resolve();
+      }
+    };
+    const timer = window.setTimeout(() => {
+      cleanup();
+      reject(new Error(timeoutMessage));
+    }, CONNECT_TIMEOUT_MS);
+    session.connectionStatusChanged.connect(onStatus);
+  });
+}
+
+/**
+ * The {@link IAgentTerminals} implementation: a read-only view over the
+ * terminals panel's {@link SessionRegistry} narrowed to sessions with a
+ * detection-confirmed coding agent, plus the "send a prompt into one"
+ * action. Lives in the `xtralab:terminals` plugin so the ask-agent popup
+ * (and any future caller) can target running agents without duplicating the
+ * detection plumbing.
+ */
+export class AgentTerminals implements IAgentTerminals {
+  constructor(options: AgentTerminals.IOptions) {
+    this._registry = options.registry;
+    this._tracker = options.tracker;
+    this._terminals = options.terminals;
+    this._detectCommands = options.detectCommands;
+    this._isAgentCommand = options.isAgentCommand;
+    this._trans = options.trans;
+    this._registry.stateChanged.connect(this._onRegistryStateChanged, this);
+  }
+
+  sessions(): IAgentTerminalSession[] {
+    const result: IAgentTerminalSession[] = [];
+    for (const name of this._registry.sessionNames()) {
+      const command = this._registry.detectedCommandFor(name);
+      if (command === null || !this._isAgentCommand(command)) {
+        continue;
+      }
+      result.push({
+        name,
+        command,
+        label: this._registry.labelFor(name),
+        activity: this._registry.activityFor(name)
+      });
+    }
+    return result;
+  }
+
+  get changed(): ISignal<IAgentTerminals, void> {
+    return this._changed;
+  }
+
+  async sendPrompt(name: string, prompt: string): Promise<void> {
+    // Re-validate against the server rather than trusting the caller's
+    // (possibly seconds-old) snapshot: the prompt is prose, and prose pasted
+    // into the shell prompt left behind by an exited agent would be
+    // *executed* on the Enter below.
+    await this._terminals.refreshRunning();
+    const alive = Array.from(this._terminals.running()).some(
+      model => model.name === name
+    );
+    if (!alive) {
+      throw new Error(this._trans.__('The terminal is no longer running.'));
+    }
+    const detected = await fetchRunningAgents(this._detectCommands());
+    if (detected === null) {
+      // Detection being unavailable (older server, transient failure) is
+      // not proof the agent is gone; refuse the write with a message that
+      // invites the retry that would succeed.
+      throw new Error(
+        this._trans.__('Could not verify the terminal — try sending again.')
+      );
+    }
+    const command = detected[name];
+    if (typeof command !== 'string' || !this._isAgentCommand(command)) {
+      throw new Error(
+        this._trans.__('No agent is running in that terminal anymore.')
+      );
+    }
+
+    // Deliver in the background: write straight to the session over its
+    // websocket instead of revealing its tab, so focus stays wherever the
+    // user is asking from. An open tab's live connection is reused; a
+    // closed tab gets a short-lived client connection to the running server
+    // session, without creating any widget.
+    const widget = this._findWidget(name);
+    const session =
+      widget !== null
+        ? widget.content.session
+        : this._terminals.connectTo({ model: { name } });
+    try {
+      await waitUntilConnected(
+        session,
+        this._trans.__('Timed out connecting to the terminal.')
+      );
+      // Wrapped and newline-normalised exactly like xterm's own paste
+      // handling. Writing the markers directly (rather than through an open
+      // tab's `Terminal.paste`) also sidesteps the one case paste() gets
+      // wrong: a freshly reconnected xterm whose replayed scrollback no
+      // longer holds the agent's original mode-setting escape, which makes
+      // paste() skip the wrapping the application still expects.
+      session.send({
+        type: 'stdin',
+        content: [PASTE_OPEN + prompt.replace(/\r?\n/g, '\r') + PASTE_CLOSE]
+      });
+      await new Promise(resolve =>
+        window.setTimeout(resolve, PASTE_SUBMIT_DELAY_MS)
+      );
+      if (session.isDisposed) {
+        // The tab closed during the pause; the pasted text already reached
+        // the agent's input box but Enter can no longer be delivered here.
+        throw new Error(
+          this._trans.__('The terminal closed before the prompt was submitted.')
+        );
+      }
+      session.send({ type: 'stdin', content: ['\r'] });
+    } finally {
+      // Close a connection we opened just for this send. Disposing the
+      // client connection leaves the server session (and its agent) running.
+      if (widget === null && !session.isDisposed) {
+        session.dispose();
+      }
+    }
+  }
+
+  private _findWidget(name: string): TerminalWidget | null {
+    return (
+      this._tracker.find(widget => widget.content.session.name === name) ?? null
+    );
+  }
+
+  private _onRegistryStateChanged(): void {
+    this._changed.emit();
+  }
+
+  private _registry: SessionRegistry;
+  private _tracker: ITerminalTracker;
+  private _terminals: Terminal.IManager;
+  private _detectCommands: () => string[];
+  private _isAgentCommand: (command: string) => boolean;
+  private _trans: TranslationBundle;
+  private _changed = new Signal<IAgentTerminals, void>(this);
+}
+
+/**
+ * A namespace for `AgentTerminals` statics.
+ */
+export namespace AgentTerminals {
+  /**
+   * Construction options for {@link AgentTerminals}.
+   */
+  export interface IOptions {
+    /**
+     * The panel's session registry — the source of the session snapshot.
+     */
+    registry: SessionRegistry;
+
+    /**
+     * Tracker of open terminal widgets, to reuse an open tab's connection.
+     */
+    tracker: ITerminalTracker;
+
+    /**
+     * The terminal session manager, for validation and ad-hoc connections.
+     */
+    terminals: Terminal.IManager;
+
+    /**
+     * Names to detect — same list the registry polls with.
+     */
+    detectCommands: () => string[];
+
+    /**
+     * Whether a detected command belongs to a coding agent (not an editor).
+     */
+    isAgentCommand: (command: string) => boolean;
+
+    /**
+     * Translation bundle for the error messages thrown to callers.
+     */
+    trans: TranslationBundle;
+  }
+}

package/src/terminals/index.ts

@@ -12,7 +12,9 @@ import { LabIcon, MenuSvg, terminalIcon } from '@jupyterlab/ui-components';
 import { IAgentSessions } from '../agentSessions';
 import { IEditorRegistry } from '../launcher/editorRegistry';
 import { agentCommandId, IAgentRegistry } from '../launcher/tokens';
+import { AgentTerminals } from './agentTerminals';
 import { SessionRegistry } from './model';
+import { IAgentTerminals } from './tokens';
 import { RunningTerminals } from './widget';
 
 const PLUGIN_ID = 'xtralab:terminals';
@@ -44,12 +46,18 @@ const PLUGIN_ID = 'xtralab:terminals';
  * consistent here as in the launcher and reuses the very same registered
  * commands and icons. When the launcher is disabled or no agents are
  * installed, the button falls back to opening a plain terminal directly.
+ *
+ * The plugin also provides {@link IAgentTerminals} — the sessions with a
+ * detection-confirmed running agent, plus a "paste a prompt into one"
+ * action — which the ask-agent popup uses to offer running agents as
+ * targets next to "new terminal".
  */
-const plugin: JupyterFrontEndPlugin<void> = {
+const plugin: JupyterFrontEndPlugin<IAgentTerminals> = {
   id: PLUGIN_ID,
   description:
     'A left-sidebar panel listing every running terminal session by its real (program-published) title, with activate/reopen, shutdown and new-terminal actions.',
   autoStart: true,
+  provides: IAgentTerminals,
   requires: [ITerminalTracker],
   optional: [
     ILayoutRestorer,
@@ -68,7 +76,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
     editorRegistry: IEditorRegistry | null,
     agentSessions: IAgentSessions | null,
     settingRegistry: ISettingRegistry | null
-  ): void => {
+  ): IAgentTerminals => {
     const trans = (translator ?? nullTranslator).load('jupyterlab');
 
     // Resolve a running agent/editor identifier to an icon: the matching
@@ -96,6 +104,35 @@ const plugin: JupyterFrontEndPlugin<void> = {
       return editor?.icon ?? terminalIcon;
     };
 
+    // The names the server should look for in each terminal's process tree:
+    // for every agent and editor, its configured `command` plus its canonical
+    // `id`. The id is the real CLI name (e.g. `claude`, `nvim`), so an agent
+    // whose command points at an alias — e.g. `ccm` running `claude` — is
+    // still recognised by the process it actually spawns. Read live so the
+    // list tracks settings changes; deduplicated since command and id usually
+    // coincide.
+    const detectCommands = (): string[] => {
+      const names = new Set<string>();
+      for (const agent of agentRegistry?.agents ?? []) {
+        names.add(agent.command);
+        names.add(agent.id);
+      }
+      for (const editor of editorRegistry?.editors ?? []) {
+        names.add(editor.command);
+        names.add(editor.id);
+      }
+      return Array.from(names);
+    };
+
+    // Whether a detected command/id belongs to a coding agent rather than an
+    // editor. Only agent sessions get a latest-activity line (editor
+    // terminals stay badge-only), and only they are offered as prompt
+    // targets through `IAgentTerminals`.
+    const isAgentCommand = (command: string): boolean =>
+      agentRegistry?.agents.some(
+        a => a.command === command || a.id === command
+      ) ?? false;
+
     const registry = new SessionRegistry({
       serviceManager: app.serviceManager,
       tracker,
@@ -104,32 +141,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
       // nothing while a notebook or other widget is current instead).
       shell: app.shell,
       agentSessions,
-      // The names the server should look for in each terminal's process tree:
-      // for every agent and editor, its configured `command` plus its canonical
-      // `id`. The id is the real CLI name (e.g. `claude`, `nvim`), so an agent
-      // whose command points at an alias — e.g. `ccm` running `claude` — is
-      // still recognised by the process it actually spawns. Read live so the
-      // list tracks settings changes; deduplicated since command and id usually
-      // coincide.
-      detectCommands: () => {
-        const names = new Set<string>();
-        for (const agent of agentRegistry?.agents ?? []) {
-          names.add(agent.command);
-          names.add(agent.id);
-        }
-        for (const editor of editorRegistry?.editors ?? []) {
-          names.add(editor.command);
-          names.add(editor.id);
-        }
-        return Array.from(names);
-      },
-      // Only coding agents (not editors) get a latest-activity line, so the
-      // registry asks this whether a detected command/id is an agent before
-      // reading its output buffer — editor terminals stay badge-only.
-      isAgentCommand: (command: string) =>
-        agentRegistry?.agents.some(
-          a => a.command === command || a.id === command
-        ) ?? false
+      detectCommands,
+      isAgentCommand
     });
 
     // Mirror the agent/editor detected in each open terminal onto its main-area
@@ -138,7 +151,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
     // the writes neither loop nor churn.
     const syncTabIcons = (): void => {
       tracker.forEach(widget => {
-        const session = widget.content?.session;
+        const session = widget.content.session;
         if (!session) {
           return;
         }
@@ -274,10 +287,21 @@ const plugin: JupyterFrontEndPlugin<void> = {
           );
         });
     }
+
+    return new AgentTerminals({
+      registry,
+      tracker,
+      terminals: app.serviceManager.terminals,
+      detectCommands,
+      isAgentCommand,
+      trans
+    });
   }
 };
 
-/** Read a boolean setting value, falling back when it is missing or invalid. */
+/**
+ * Read a boolean setting value, falling back when it is missing or invalid.
+ */
 function boolOption(value: unknown, fallback: boolean): boolean {
   return typeof value === 'boolean' ? value : fallback;
 }

package/src/terminals/model.ts

@@ -245,6 +245,20 @@ export class SessionRegistry implements IDisposable {
     return null;
   }
 
+  /**
+   * The agent command server-side detection currently reports for the
+   * session, or `null` when it has not confirmed one (the session is idle,
+   * not yet covered by a poll, or detection is unavailable). Unlike
+   * {@link agentCommandFor} this never falls back to the optimistic launch
+   * tags: callers about to *write into* a session use it, and text must only
+   * ever be sent to a confirmed running agent — pasted into a shell prompt it
+   * would be executed.
+   */
+  detectedCommandFor(name: string): string | null {
+    const detected = this._detected.get(name);
+    return typeof detected === 'string' ? detected : null;
+  }
+
   /**
    * The most recent meaningful line of output from the session's terminal, or
    * `null` when there is nothing to surface — no coding agent is running in the
@@ -542,7 +556,7 @@ export class SessionRegistry implements IDisposable {
 
   private _onTitleChanged(title: Title<Widget>): void {
     const owner = title.owner as TerminalWidget;
-    const session = owner.content?.session;
+    const session = owner.content.session;
     if (!session) {
       return;
     }
@@ -558,8 +572,7 @@ export class SessionRegistry implements IDisposable {
    * `_initialConnection` fires). Without the filter, briefly
    * reopening a tab while an agent has yet to re-emit its xterm
    * title escape sequence would clobber the cached agent name with
-   * `Terminal 1`, which is exactly the regression we are guarding
-   * against. Live widget titles still display whatever the widget
+   * `Terminal 1`. Live widget titles still display whatever the widget
    * currently holds because `labelFor` consults the widget first;
    * the filter only affects what survives a tab close.
    */
@@ -663,10 +676,14 @@ namespace Private {
     return true;
   }
 
-  /** Rows above the cursor to scan when looking for the latest output. */
+  /**
+   * Rows above the cursor to scan when looking for the latest output.
+   */
   const ACTIVITY_SCAN_ROWS = 64;
 
-  /** Clamp for the activity string so one runaway block can't bloat a row. */
+  /**
+   * Clamp for the activity string so one runaway block can't bloat a row.
+   */
   const ACTIVITY_MAX_LENGTH = 160;
 
   /**
@@ -715,7 +732,9 @@ namespace Private {
     return null;
   }
 
-  /** Sanitized text of one buffer row. */
+  /**
+   * Sanitized text of one buffer row.
+   */
   export function lineText(buffer: IXtermBuffer, row: number): string {
     return sanitizeActivity(buffer.getLine(row)?.translateToString(true) ?? '');
   }
@@ -746,7 +765,9 @@ namespace Private {
     return result;
   }
 
-  /** Truncate by code point (never splitting an emoji) with an ellipsis. */
+  /**
+   * Truncate by code point (never splitting an emoji) with an ellipsis.
+   */
   export function clampActivity(text: string): string {
     const points = Array.from(text);
     return points.length > ACTIVITY_MAX_LENGTH

package/src/terminals/tokens.ts

@@ -0,0 +1,77 @@
+import { Token } from '@lumino/coreutils';
+import type { ISignal } from '@lumino/signaling';
+
+/**
+ * One running terminal session with a confirmed coding agent inside — an
+ * entry of {@link IAgentTerminals.sessions}.
+ */
+export interface IAgentTerminalSession {
+  /**
+   * The terminal session name (terminado's, e.g. `1`).
+   */
+  name: string;
+
+  /**
+   * The agent identifier server-side detection reported for the session:
+   * the configured `command`, or the canonical agent `id` when the command
+   * is an alias (e.g. `ccm` spawning `claude`). Matches an `IAgent` by
+   * either field.
+   */
+  command: string;
+
+  /**
+   * Display label — the session's real title (the launcher's agent name, or
+   * whatever the running program published via an xterm escape sequence).
+   */
+  label: string;
+
+  /**
+   * The latest meaningful line of the agent's output, when its tab is open
+   * and the activity line is enabled; `null` otherwise.
+   */
+  activity: string | null;
+}
+
+/**
+ * Running agent terminals, and a way to send a prompt into one.
+ *
+ * `sessions` only lists sessions where server-side process detection has
+ * *confirmed* a running coding agent (editors and plain shells are excluded,
+ * as are optimistic just-launched tags): every listed session is one whose
+ * TUI can meaningfully receive pasted prompt text. `sendPrompt` re-validates
+ * against the server before writing, since pasting prose into a shell prompt
+ * would execute it.
+ */
+export interface IAgentTerminals {
+  /**
+   * Snapshot of the sessions with a detection-confirmed running agent.
+   */
+  sessions(): IAgentTerminalSession[];
+
+  /**
+   * Emitted whenever the {@link sessions} snapshot may have changed.
+   */
+  readonly changed: ISignal<IAgentTerminals, void>;
+
+  /**
+   * Paste `prompt` into the named session's terminal and press Enter.
+   *
+   * Delivery is deliberately background: the text is written straight to
+   * the session's websocket, bracketed-paste-wrapped so a multi-line prompt
+   * arrives as one block in the agent's input box, without revealing or
+   * focusing the terminal's tab — the user keeps working where they are,
+   * and the agent CLIs queue the prompt themselves when they are busy.
+   * Rejects when the session is gone or no agent is running in it anymore.
+   */
+  sendPrompt(name: string, prompt: string): Promise<void>;
+}
+
+/**
+ * DI token for {@link IAgentTerminals}. Provided by `xtralab:terminals`;
+ * consumed — optionally, so each side works without the other — by
+ * `xtralab:ask-agent` to offer running agent terminals as prompt targets.
+ */
+export const IAgentTerminals = new Token<IAgentTerminals>(
+  'xtralab:IAgentTerminals',
+  'The running terminal sessions with a detected coding agent, and a way to send a prompt into one.'
+);

package/src/terminals/widget.tsx

@@ -19,7 +19,7 @@ import { SessionRegistry } from './model';
  * Id of the panel widget. Used for layout restoration and as the handle
  * the sidebar visibility toggle would target.
  */
-export const RUNNING_TERMINALS_ID = 'xtralab-running-terminals';
+const RUNNING_TERMINALS_ID = 'xtralab-running-terminals';
 
 /**
  * Left-sidebar panel listing every running terminal session. It is the
@@ -108,7 +108,9 @@ export namespace RunningTerminals {
      * terminal widget if no tab is currently attached.
      */
     onActivate: (sessionName: string) => void;
-    /** Shut the named session down on the server. */
+    /**
+     * Shut the named session down on the server.
+     */
     onShutdown: (sessionName: string) => void;
     /**
      * Shut down every running terminal at once. The plugin is expected to

package/src/topBar/index.ts

@@ -21,9 +21,13 @@ const TOGGLE_LEFT_AREA = 'application:toggle-left-area';
 const TOGGLE_RIGHT_AREA = 'application:toggle-right-area';
 
 interface IButtonSpec {
-  /** Stable widget id (required by `LabShell.add`). */
+  /**
+   * Stable widget id (required by `LabShell.add`).
+   */
   id: string;
-  /** Command the button triggers and mirrors the state of. */
+  /**
+   * Command the button triggers and mirrors the state of.
+   */
   command: string;
   icon: LabIcon;
   caption: (trans: ReturnType<ITranslator['load']>) => string;
@@ -36,7 +40,9 @@ interface IButtonSpec {
    * leading edge is free.
    */
   rank: number;
-  /** Side-specific class, used by the stylesheet for placement. */
+  /**
+   * Side-specific class, used by the stylesheet for placement.
+   */
   sideClass: string;
 }
 
@@ -47,7 +53,7 @@ const BUTTONS: IButtonSpec[] = [
     icon: leftSidebarIcon,
     caption: trans => trans.__('Toggle left sidebar'),
     rank: -1,
-    sideClass: 'xtralab-TopBarButton-left'
+    sideClass: 'jp-xtralab-TopBarButton-left'
   },
   {
     id: 'xtralab-toggle-right-sidebar',
@@ -55,7 +61,7 @@ const BUTTONS: IButtonSpec[] = [
     icon: rightSidebarIcon,
     caption: trans => trans.__('Toggle right sidebar'),
     rank: 1000,
-    sideClass: 'xtralab-TopBarButton-right'
+    sideClass: 'jp-xtralab-TopBarButton-right'
   }
 ];
 
@@ -123,7 +129,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
           noFocusOnClick: true
         });
         button.id = spec.id;
-        button.addClass('xtralab-TopBarButton');
+        button.addClass('jp-xtralab-TopBarButton');
         button.addClass(spec.sideClass);
         labShell.add(button, 'top', { rank: spec.rank });
       }

package/src/walkthrough/index.ts

@@ -7,19 +7,25 @@ import { ICommandPalette } from '@jupyterlab/apputils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { tocIcon } from '@jupyterlab/ui-components';
+import type { ReadonlyPartialJSONValue } from '@lumino/coreutils';
 
+import { coerceData } from '../mimeData';
 import { IWalkthroughMedia, IWalkthroughStep, WalkthroughPanel } from './panel';
 
 const PLUGIN_ID = 'xtralab:walkthrough';
 
-/** Append a step to the read-only walkthrough panel. */
+/**
+ * Append a step to the read-only walkthrough panel.
+ */
 const WALKTHROUGH_COMMAND = 'xtralab:walkthrough';
 
 const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
 
 const PANEL_ID = 'xtralab-walkthrough';
 
-/** Pull a `{ mimeType, data }` media object out of a JSON command argument. */
+/**
+ * Pull a `{ mimeType, data }` media object out of a JSON command argument.
+ */
 function readMedia(value: unknown): IWalkthroughMedia | undefined {
   if (
     value &&
@@ -27,8 +33,17 @@ function readMedia(value: unknown): IWalkthroughMedia | undefined {
     !Array.isArray(value) &&
     typeof (value as { mimeType?: unknown }).mimeType === 'string'
   ) {
-    const media = value as { mimeType: string; data?: unknown };
-    return { mimeType: media.mimeType, data: media.data as never };
+    const media = value as {
+      mimeType: string;
+      data?: ReadonlyPartialJSONValue;
+    };
+    if (media.data === undefined) {
+      return undefined;
+    }
+    return {
+      mimeType: media.mimeType,
+      data: coerceData(media.mimeType, media.data)
+    };
   }
   return undefined;
 }