npm - xtralab - Versions diffs - 0.9.0 → 0.10.0 - Mend

xtralab 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +17 -0
package/lib/index.js +2 -0
package/lib/terminalNotifications/index.d.ts +15 -0
package/lib/terminalNotifications/index.js +213 -0
package/package.json +1 -1
package/schema/terminal-notifications.json +21 -0
package/src/index.ts +2 -0
package/src/terminalNotifications/index.ts +295 -0

package/README.md CHANGED Viewed

@@ -34,6 +34,23 @@ from `main` are uploaded as workflow artifacts on the
 [CONTRIBUTING.md](./CONTRIBUTING.md) for the desktop app architecture and local
 build instructions.
+On macOS the build is not notarized yet (it has no Apple Developer ID), so
+Gatekeeper blocks it on first launch, and agent notifications fall back to
+`osascript`, appearing as "Script Editor". In the meantime you can self-sign it
+for free: this lets it launch and gives native notifications instead, branded as
+xtralab and clickable to jump to the terminal that fired them. Create a
+code-signing certificate once in Keychain Access (Certificate Assistant, Create
+a Certificate, with Identity Type "Self Signed Root" and Certificate Type "Code
+Signing") named `xtralab-selfsign`, then sign the app you copied out of the DMG:
+```bash
+codesign --force --deep --sign "xtralab-selfsign" --timestamp=none "/Applications/xtralab.app"
+xattr -dr com.apple.quarantine "/Applications/xtralab.app"
+```
+macOS prompts once to let `codesign` use the key; choose Always Allow. None of
+this will be needed once the app ships with a Developer ID signature.
 ## What's included
 xtralab builds on [`ajlab`](https://github.com/jtpio/ajlab), the agent-ready

package/lib/index.js CHANGED Viewed

@@ -7,6 +7,7 @@ import gitPlugins from './git';
 import launcherPlugins from './launcher';
 import menusPlugin from './menus';
 import sidebarPlugin from './sidebar';
+import terminalNotificationsPlugin from './terminalNotifications';
 import terminalsPlugin from './terminals';
 import topBarPlugin from './topBar';
 /**
@@ -28,6 +29,7 @@ const plugins = [
     ...launcherPlugins,
     menusPlugin,
     sidebarPlugin,
+    terminalNotificationsPlugin,
     terminalsPlugin,
     topBarPlugin
 ];

package/lib/terminalNotifications/index.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Turns the notifications coding agents already emit (OSC 9, OSC 777, the bell)
+ * into desktop notifications. JupyterLab's xterm renders these sequences but
+ * never forwards them to the OS, so this plugin hooks each terminal and bridges
+ * them through `window.xtralab.notify` (desktop) or the web Notifications API.
+ *
+ * A notification is suppressed while its terminal is the focused, active tab,
+ * and throttled per terminal. The desktop shell advertises
+ * `TERM_PROGRAM=iTerm.app` so agents emit OSC 9 in the first place, and the
+ * session name is forwarded so clicking a notification focuses the terminal
+ * that fired it.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/terminalNotifications/index.js ADDED Viewed

@@ -0,0 +1,213 @@
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ITerminalTracker } from '@jupyterlab/terminal';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+const PLUGIN_ID = 'xtralab:terminal-notifications';
+// Per-terminal gap between notifications, so the OSC-9-plus-bell agents emit
+// together collapses into one and a chatty program cannot flood the OS.
+const NOTIFY_THROTTLE_MS = 3000;
+// iTerm2 growl notification: `ESC ] 9 ; <message> BEL`. What Claude Code and
+// most agents emit on their default `auto` setting once TERM_PROGRAM is set.
+const OSC_ITERM2_GROWL = 9;
+// rxvt/Ghostty notification: `ESC ] 777 ; notify ; <title> ; <body> BEL`.
+const OSC_RXVT_NOTIFY = 777;
+const MAX_TEXT_LENGTH = 256;
+/**
+ * Turns the notifications coding agents already emit (OSC 9, OSC 777, the bell)
+ * into desktop notifications. JupyterLab's xterm renders these sequences but
+ * never forwards them to the OS, so this plugin hooks each terminal and bridges
+ * them through `window.xtralab.notify` (desktop) or the web Notifications API.
+ *
+ * A notification is suppressed while its terminal is the focused, active tab,
+ * and throttled per terminal. The desktop shell advertises
+ * `TERM_PROGRAM=iTerm.app` so agents emit OSC 9 in the first place, and the
+ * session name is forwarded so clicking a notification focuses the terminal
+ * that fired it.
+ */
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Forwards desktop notifications emitted by agents in xtralab terminals (OSC 9, OSC 777, bell) to the operating system.',
+    autoStart: true,
+    requires: [ITerminalTracker],
+    optional: [ISettingRegistry, ITranslator],
+    activate: async (app, tracker, settingRegistry, translator) => {
+        var _a;
+        const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
+        let enabled = true;
+        let notifyOnBell = true;
+        // Per-widget throttle timestamps and xterm hooks. WeakMaps let disposed
+        // widgets be collected; hooks are torn down when a tab closes.
+        const lastNotified = new WeakMap();
+        const hooks = new WeakMap();
+        // True when the user is already looking at this terminal, so a banner would
+        // just be noise.
+        const isActivelyViewing = (widget) => document.hasFocus() && app.shell.currentWidget === widget;
+        const deliver = (title, body, session) => {
+            const bridge = window.xtralab;
+            if (bridge && typeof bridge.notify === 'function') {
+                void Promise.resolve(bridge.notify(title, body, session)).catch(reason => {
+                    console.warn('xtralab: desktop notification failed', reason);
+                });
+                return;
+            }
+            // Plain-browser fallback (pip install): the Web Notifications API.
+            if (typeof Notification === 'undefined') {
+                return;
+            }
+            if (Notification.permission === 'granted') {
+                new Notification(title, { body });
+            }
+            else if (Notification.permission !== 'denied') {
+                void Notification.requestPermission().then(permission => {
+                    if (permission === 'granted') {
+                        new Notification(title, { body });
+                    }
+                });
+            }
+        };
+        const notify = (widget, title, body) => {
+            var _a;
+            if (!enabled || isActivelyViewing(widget)) {
+                return;
+            }
+            const now = Date.now();
+            const previous = lastNotified.get(widget);
+            if (previous !== undefined && now - previous < NOTIFY_THROTTLE_MS) {
+                return;
+            }
+            lastNotified.set(widget, now);
+            const session = (_a = widget.content.session) === null || _a === void 0 ? void 0 : _a.name;
+            deliver(sanitize(title) || 'xtralab', sanitize(body), session);
+        };
+        // The tab label is the agent's name once the launcher or an xterm title sets
+        // it, so it reads well as the title for body-only sequences (OSC 9, bell).
+        const labelOf = (widget) => widget.title.label || trans.__('Terminal');
+        const onOsc9 = (widget, data) => {
+            // OSC 9 is overloaded: ConEmu/Windows Terminal use `9 ; <n> ; …`
+            // subcommands (e.g. `9 ; 4` progress), so skip a numeric-subcommand
+            // payload and leave it unconsumed rather than treat it as a notification.
+            if (/^\d+(;|$)/.test(data)) {
+                return false;
+            }
+            const message = sanitize(data);
+            if (message) {
+                notify(widget, labelOf(widget), message);
+            }
+            return true;
+        };
+        const onOsc777 = (widget, data) => {
+            var _a;
+            // `notify ; <title> ; <body>`; a body may contain ';'. Other OSC 777
+            // subcommands are left unconsumed.
+            const parts = data.split(';');
+            if (parts.shift() !== 'notify') {
+                return false;
+            }
+            const title = sanitize((_a = parts.shift()) !== null && _a !== void 0 ? _a : '') || labelOf(widget);
+            const body = sanitize(parts.join(';'));
+            if (body || title) {
+                notify(widget, title, body);
+            }
+            return true;
+        };
+        const onBell = (widget) => {
+            if (notifyOnBell) {
+                notify(widget, labelOf(widget), trans.__('Activity in terminal'));
+            }
+        };
+        const hookWidget = (widget) => {
+            if (hooks.has(widget)) {
+                return;
+            }
+            const content = widget.content;
+            void content.ready
+                .then(() => {
+                const term = content._term;
+                if (widget.isDisposed) {
+                    return;
+                }
+                if (!term) {
+                    console.warn('xtralab: xterm internals not found; terminal notifications are disabled for this terminal');
+                    return;
+                }
+                // Handlers are wrapped so a parse slip cannot break xterm's parser; an
+                // OSC handler returns whether it consumed the sequence.
+                const disposables = [
+                    term.onBell(() => guard(() => onBell(widget))),
+                    term.parser.registerOscHandler(OSC_ITERM2_GROWL, data => guardOsc(() => onOsc9(widget, data))),
+                    term.parser.registerOscHandler(OSC_RXVT_NOTIFY, data => guardOsc(() => onOsc777(widget, data)))
+                ];
+                hooks.set(widget, disposables);
+                widget.disposed.connect(() => {
+                    for (const disposable of disposables) {
+                        disposable.dispose();
+                    }
+                    hooks.delete(widget);
+                });
+            })
+                .catch(reason => {
+                console.warn('xtralab: could not hook terminal notifications', reason);
+            });
+        };
+        tracker.forEach(hookWidget);
+        tracker.widgetAdded.connect((_, widget) => hookWidget(widget));
+        // Focus the terminal that fired a notification when the desktop shell
+        // reports a click. `terminal:open` activates its tab or reopens the session.
+        const desktopBridge = window
+            .xtralab;
+        (_a = desktopBridge === null || desktopBridge === void 0 ? void 0 : desktopBridge.onFocusTerminal) === null || _a === void 0 ? void 0 : _a.call(desktopBridge, session => {
+            if (session) {
+                void app.commands.execute('terminal:open', { name: session });
+            }
+        });
+        if (settingRegistry) {
+            try {
+                const settings = await settingRegistry.load(PLUGIN_ID);
+                const readSettings = () => {
+                    enabled = boolOption(settings.composite.enabled, true);
+                    notifyOnBell = boolOption(settings.composite.notifyOnBell, true);
+                };
+                readSettings();
+                settings.changed.connect(readSettings);
+            }
+            catch (reason) {
+                console.error('xtralab: failed to load terminal-notifications settings', reason);
+            }
+        }
+    }
+};
+// Run `fn`, swallowing errors so a malformed escape sequence cannot take the
+// terminal's parser or bell handler down with it.
+function guard(fn) {
+    try {
+        fn();
+    }
+    catch (reason) {
+        console.warn('xtralab: terminal notification handler failed', reason);
+    }
+}
+// `guard` for an OSC handler that reports whether it consumed the sequence.
+function guardOsc(fn) {
+    try {
+        return fn();
+    }
+    catch (reason) {
+        console.warn('xtralab: terminal notification handler failed', reason);
+        return false;
+    }
+}
+// Replace control characters with spaces (so a notification cannot carry escape
+// sequences), collapse whitespace, and clamp the length.
+function sanitize(value) {
+    var _a;
+    let result = '';
+    for (const char of value) {
+        const code = (_a = char.codePointAt(0)) !== null && _a !== void 0 ? _a : 0;
+        const isControl = code < 0x20 || (code >= 0x7f && code <= 0x9f);
+        result += isControl ? ' ' : char;
+    }
+    return result.replace(/\s+/g, ' ').trim().slice(0, MAX_TEXT_LENGTH);
+}
+function boolOption(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+export default plugin;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
     "name": "xtralab",
-    "version": "0.9.0",
+    "version": "0.10.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/terminal-notifications.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "title": "xtralab terminal notifications",
+  "description": "Desktop notifications from coding agents running in xtralab terminals.",
+  "jupyter.lab.shortcuts": [],
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "title": "Enable terminal notifications",
+      "description": "When true, a desktop notification is shown when a program in a terminal asks for one (the iTerm2/Ghostty OSC sequences or the bell) — for example when a coding agent finishes or needs input. Notifications are suppressed while you are looking at that terminal.",
+      "default": true
+    },
+    "notifyOnBell": {
+      "type": "boolean",
+      "title": "Notify on the terminal bell",
+      "description": "When true, a plain terminal bell also raises a notification. The richer OSC 9 / OSC 777 sequences are always handled; disable this if the bell alone proves too noisy.",
+      "default": true
+    }
+  },
+  "additionalProperties": false
+}

package/src/index.ts CHANGED Viewed

@@ -9,6 +9,7 @@ import gitPlugins from './git';
 import launcherPlugins from './launcher';
 import menusPlugin from './menus';
 import sidebarPlugin from './sidebar';
+import terminalNotificationsPlugin from './terminalNotifications';
 import terminalsPlugin from './terminals';
 import topBarPlugin from './topBar';
@@ -31,6 +32,7 @@ const plugins: JupyterFrontEndPlugin<unknown>[] = [
   ...launcherPlugins,
   menusPlugin,
   sidebarPlugin,
+  terminalNotificationsPlugin,
   terminalsPlugin,
   topBarPlugin
 ];

package/src/terminalNotifications/index.ts ADDED Viewed

@@ -0,0 +1,295 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import type { MainAreaWidget } from '@jupyterlab/apputils';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ITerminal, ITerminalTracker } from '@jupyterlab/terminal';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+const PLUGIN_ID = 'xtralab:terminal-notifications';
+// Per-terminal gap between notifications, so the OSC-9-plus-bell agents emit
+// together collapses into one and a chatty program cannot flood the OS.
+const NOTIFY_THROTTLE_MS = 3000;
+// iTerm2 growl notification: `ESC ] 9 ; <message> BEL`. What Claude Code and
+// most agents emit on their default `auto` setting once TERM_PROGRAM is set.
+const OSC_ITERM2_GROWL = 9;
+// rxvt/Ghostty notification: `ESC ] 777 ; notify ; <title> ; <body> BEL`.
+const OSC_RXVT_NOTIFY = 777;
+const MAX_TEXT_LENGTH = 256;
+// The bits of an xterm.js `Terminal` we reach into. JupyterLab's terminal
+// widget keeps its xterm in a private `_term` field and does not expose these
+// hooks, so a structural type uses them without depending on `@xterm/xterm`. If
+// the field is ever renamed, `_term` is `undefined` and notifications stop, with
+// a console warning per terminal.
+interface IXtermDisposable {
+  dispose(): void;
+}
+interface IXtermTerminal {
+  onBell(handler: () => void): IXtermDisposable;
+  parser: {
+    registerOscHandler(
+      ident: number,
+      callback: (data: string) => boolean
+    ): IXtermDisposable;
+  };
+}
+interface ITerminalContentInternals extends ITerminal.ITerminal {
+  ready: Promise<void>;
+  _term?: IXtermTerminal;
+}
+type TerminalWidget = MainAreaWidget<ITerminal.ITerminal>;
+// The renderer→main bridge the desktop shell injects on the lab window. Absent
+// for pip-install users in a browser, who fall back to web Notifications.
+interface IDesktopBridge {
+  notify?: (
+    title: string,
+    body: string,
+    session?: string
+  ) => Promise<void> | void;
+  onFocusTerminal?: (callback: (session: string) => void) => void;
+}
+/**
+ * Turns the notifications coding agents already emit (OSC 9, OSC 777, the bell)
+ * into desktop notifications. JupyterLab's xterm renders these sequences but
+ * never forwards them to the OS, so this plugin hooks each terminal and bridges
+ * them through `window.xtralab.notify` (desktop) or the web Notifications API.
+ *
+ * A notification is suppressed while its terminal is the focused, active tab,
+ * and throttled per terminal. The desktop shell advertises
+ * `TERM_PROGRAM=iTerm.app` so agents emit OSC 9 in the first place, and the
+ * session name is forwarded so clicking a notification focuses the terminal
+ * that fired it.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'Forwards desktop notifications emitted by agents in xtralab terminals (OSC 9, OSC 777, bell) to the operating system.',
+  autoStart: true,
+  requires: [ITerminalTracker],
+  optional: [ISettingRegistry, ITranslator],
+  activate: async (
+    app: JupyterFrontEnd,
+    tracker: ITerminalTracker,
+    settingRegistry: ISettingRegistry | null,
+    translator: ITranslator | null
+  ): Promise<void> => {
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+    let enabled = true;
+    let notifyOnBell = true;
+    // Per-widget throttle timestamps and xterm hooks. WeakMaps let disposed
+    // widgets be collected; hooks are torn down when a tab closes.
+    const lastNotified = new WeakMap<TerminalWidget, number>();
+    const hooks = new WeakMap<TerminalWidget, IXtermDisposable[]>();
+    // True when the user is already looking at this terminal, so a banner would
+    // just be noise.
+    const isActivelyViewing = (widget: TerminalWidget): boolean =>
+      document.hasFocus() && app.shell.currentWidget === widget;
+    const deliver = (title: string, body: string, session?: string): void => {
+      const bridge = (window as Window & { xtralab?: IDesktopBridge }).xtralab;
+      if (bridge && typeof bridge.notify === 'function') {
+        void Promise.resolve(bridge.notify(title, body, session)).catch(
+          reason => {
+            console.warn('xtralab: desktop notification failed', reason);
+          }
+        );
+        return;
+      }
+      // Plain-browser fallback (pip install): the Web Notifications API.
+      if (typeof Notification === 'undefined') {
+        return;
+      }
+      if (Notification.permission === 'granted') {
+        new Notification(title, { body });
+      } else if (Notification.permission !== 'denied') {
+        void Notification.requestPermission().then(permission => {
+          if (permission === 'granted') {
+            new Notification(title, { body });
+          }
+        });
+      }
+    };
+    const notify = (
+      widget: TerminalWidget,
+      title: string,
+      body: string
+    ): void => {
+      if (!enabled || isActivelyViewing(widget)) {
+        return;
+      }
+      const now = Date.now();
+      const previous = lastNotified.get(widget);
+      if (previous !== undefined && now - previous < NOTIFY_THROTTLE_MS) {
+        return;
+      }
+      lastNotified.set(widget, now);
+      const session = widget.content.session?.name;
+      deliver(sanitize(title) || 'xtralab', sanitize(body), session);
+    };
+    // The tab label is the agent's name once the launcher or an xterm title sets
+    // it, so it reads well as the title for body-only sequences (OSC 9, bell).
+    const labelOf = (widget: TerminalWidget): string =>
+      widget.title.label || trans.__('Terminal');
+    const onOsc9 = (widget: TerminalWidget, data: string): boolean => {
+      // OSC 9 is overloaded: ConEmu/Windows Terminal use `9 ; <n> ; …`
+      // subcommands (e.g. `9 ; 4` progress), so skip a numeric-subcommand
+      // payload and leave it unconsumed rather than treat it as a notification.
+      if (/^\d+(;|$)/.test(data)) {
+        return false;
+      }
+      const message = sanitize(data);
+      if (message) {
+        notify(widget, labelOf(widget), message);
+      }
+      return true;
+    };
+    const onOsc777 = (widget: TerminalWidget, data: string): boolean => {
+      // `notify ; <title> ; <body>`; a body may contain ';'. Other OSC 777
+      // subcommands are left unconsumed.
+      const parts = data.split(';');
+      if (parts.shift() !== 'notify') {
+        return false;
+      }
+      const title = sanitize(parts.shift() ?? '') || labelOf(widget);
+      const body = sanitize(parts.join(';'));
+      if (body || title) {
+        notify(widget, title, body);
+      }
+      return true;
+    };
+    const onBell = (widget: TerminalWidget): void => {
+      if (notifyOnBell) {
+        notify(widget, labelOf(widget), trans.__('Activity in terminal'));
+      }
+    };
+    const hookWidget = (widget: TerminalWidget): void => {
+      if (hooks.has(widget)) {
+        return;
+      }
+      const content = widget.content as ITerminalContentInternals;
+      void content.ready
+        .then(() => {
+          const term = content._term;
+          if (widget.isDisposed) {
+            return;
+          }
+          if (!term) {
+            console.warn(
+              'xtralab: xterm internals not found; terminal notifications are disabled for this terminal'
+            );
+            return;
+          }
+          // Handlers are wrapped so a parse slip cannot break xterm's parser; an
+          // OSC handler returns whether it consumed the sequence.
+          const disposables: IXtermDisposable[] = [
+            term.onBell(() => guard(() => onBell(widget))),
+            term.parser.registerOscHandler(OSC_ITERM2_GROWL, data =>
+              guardOsc(() => onOsc9(widget, data))
+            ),
+            term.parser.registerOscHandler(OSC_RXVT_NOTIFY, data =>
+              guardOsc(() => onOsc777(widget, data))
+            )
+          ];
+          hooks.set(widget, disposables);
+          widget.disposed.connect(() => {
+            for (const disposable of disposables) {
+              disposable.dispose();
+            }
+            hooks.delete(widget);
+          });
+        })
+        .catch(reason => {
+          console.warn(
+            'xtralab: could not hook terminal notifications',
+            reason
+          );
+        });
+    };
+    tracker.forEach(hookWidget);
+    tracker.widgetAdded.connect((_, widget) => hookWidget(widget));
+    // Focus the terminal that fired a notification when the desktop shell
+    // reports a click. `terminal:open` activates its tab or reopens the session.
+    const desktopBridge = (window as Window & { xtralab?: IDesktopBridge })
+      .xtralab;
+    desktopBridge?.onFocusTerminal?.(session => {
+      if (session) {
+        void app.commands.execute('terminal:open', { name: session });
+      }
+    });
+    if (settingRegistry) {
+      try {
+        const settings = await settingRegistry.load(PLUGIN_ID);
+        const readSettings = (): void => {
+          enabled = boolOption(settings.composite.enabled, true);
+          notifyOnBell = boolOption(settings.composite.notifyOnBell, true);
+        };
+        readSettings();
+        settings.changed.connect(readSettings);
+      } catch (reason) {
+        console.error(
+          'xtralab: failed to load terminal-notifications settings',
+          reason
+        );
+      }
+    }
+  }
+};
+// Run `fn`, swallowing errors so a malformed escape sequence cannot take the
+// terminal's parser or bell handler down with it.
+function guard(fn: () => void): void {
+  try {
+    fn();
+  } catch (reason) {
+    console.warn('xtralab: terminal notification handler failed', reason);
+  }
+}
+// `guard` for an OSC handler that reports whether it consumed the sequence.
+function guardOsc(fn: () => boolean): boolean {
+  try {
+    return fn();
+  } catch (reason) {
+    console.warn('xtralab: terminal notification handler failed', reason);
+    return false;
+  }
+}
+// Replace control characters with spaces (so a notification cannot carry escape
+// sequences), collapse whitespace, and clamp the length.
+function sanitize(value: string): string {
+  let result = '';
+  for (const char of value) {
+    const code = char.codePointAt(0) ?? 0;
+    const isControl = code < 0x20 || (code >= 0x7f && code <= 0x9f);
+    result += isControl ? ' ' : char;
+  }
+  return result.replace(/\s+/g, ' ').trim().slice(0, MAX_TEXT_LENGTH);
+}
+function boolOption(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback;
+}
+export default plugin;