xtralab 0.10.0 → 0.11.1

package/lib/terminals/model.d.ts

@@ -17,6 +17,11 @@ export type TerminalWidget = MainAreaWidget<ITerminal.ITerminal>;
  * xterm-published title) survives the user closing the tab while the
  * session continues running on the backend.
  *
+ * For sessions running a coding agent it also surfaces a *latest activity*
+ * line — the freshest meaningful line of the terminal's output, read from the
+ * open tab's xterm buffer on a poll (see {@link activityFor}) — so each row
+ * shows what its agent is doing, not just its name.
+ *
  * It also resolves *which agent is running* in each session, so the panel can
  * badge rows with the agent's logo. Two inputs feed that, reconciled by
  * {@link agentCommandFor}:
@@ -69,7 +74,10 @@ export declare class SessionRegistry implements IDisposable {
      */
     labelFor(name: string): string;
     /**
-     * The command of the agent running in the session, or `null` if none.
+     * An identifier for the agent running in the session — its configured
+     * command, or its canonical id when detection matched the spawned process by
+     * id rather than by an aliased command — or `null` if none. Callers resolve
+     * it to a logo through the plugin's `iconForCommand`, which accepts either.
      *
      * Server-side detection is authoritative whenever it reports a running
      * agent. A launch tag fills two gaps: the startup grace window right after
@@ -80,6 +88,24 @@ export declare class SessionRegistry implements IDisposable {
      * exits.
      */
     agentCommandFor(name: string): string | 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
+     * session, its tab is closed (so there is no live buffer to read), or the
+     * buffer holds only the agent's input box and chrome. Refreshed on a poll by
+     * {@link _refreshActivity}; shown as a smaller line under the row's title.
+     * Always `null` while the activity line is disabled (see
+     * {@link setActivityEnabled}).
+     */
+    activityFor(name: string): string | null;
+    /**
+     * Turn the per-row latest-activity line on or off, driven by the
+     * `xtralab:terminals` `showAgentActivity` setting. When turned off the
+     * activity poll stops reading terminal buffers and any cached lines are
+     * dropped, so rows fall back to their title alone; when turned back on the
+     * lines are repopulated on the spot. A no-op when the value is unchanged.
+     */
+    setActivityEnabled(enabled: boolean): void;
     /**
      * Return the open widget for a session, if any. The panel uses this to
      * switch behavior between "activate existing tab" and "open a new tab
@@ -118,6 +144,18 @@ export declare class SessionRegistry implements IDisposable {
      * clearing them, so a transient error doesn't strip every badge.
      */
     private _refreshDetection;
+    /**
+     * Poll body: re-read the buffer of each open coding-agent terminal and cache
+     * its latest meaningful line of output. Only sessions that have a running
+     * *agent* (not an editor) and an open tab qualify — a closed tab has no live
+     * buffer, editors run full-screen UIs that are not "activity", and plain
+     * shells would only echo their prompt. While a tab is reopening (its xterm
+     * is not ready yet) any existing line is kept; once the buffer is readable
+     * but has nothing worth showing the line is dropped, so a screen the agent
+     * has cleared doesn't leave a frozen line behind. Cached lines for sessions
+     * that no longer qualify are pruned. Emits only when something changed.
+     */
+    private _refreshActivity;
     private _onTagChanged;
     private _onWidgetAdded;
     private _onShellCurrentChanged;
@@ -150,12 +188,16 @@ export declare class SessionRegistry implements IDisposable {
     private _tracker;
     private _agentSessions;
     private _detectCommands;
+    private _isAgentCommand;
     private _shell;
     private _poll;
+    private _activityPoll;
     private _labels;
     private _ranks;
     private _firstSeen;
     private _detected;
+    private _activity;
+    private _activityEnabled;
     private _live;
     private _currentName;
     private _nextRank;
@@ -183,9 +225,20 @@ export declare namespace SessionRegistry {
          */
         agentSessions?: IAgentSessions | null;
         /**
-         * Returns the agent commands the server should look for when detecting
-         * running agents. Read on every poll so it tracks the live agent list.
+         * Returns the names the server should look for when detecting running
+         * agents — each agent's command together with its canonical id, so a
+         * command pointed at an alias (e.g. `ccm` running `claude`) is still
+         * matched by the process it spawns. Read on every poll so it tracks the
+         * live agent list.
          */
         detectCommands?: () => string[];
+        /**
+         * Whether a detected command (or id) belongs to a coding agent rather than
+         * an editor. Only agent sessions get a latest-activity line — editors
+         * (Neovim/Vim) are badged too, but run full-screen UIs whose buffer is not
+         * meaningfully "activity". Defaults to treating every detected command as an
+         * agent.
+         */
+        isAgentCommand?: (command: string) => boolean;
     }
 }

package/lib/terminals/model.js

@@ -23,6 +23,13 @@ const DETECT_POLL_MAX_MS = 300000;
  * for an agent that never really started clears quickly.
  */
 const LAUNCH_GRACE_MS = 4000;
+/**
+ * How often to re-read each open coding-agent terminal's output buffer to
+ * refresh the "latest activity" line shown under its row. Brisk enough to feel
+ * live while an agent works, cheap because it only walks the last screenful of
+ * a handful of terminals and emits only when a line actually changes.
+ */
+const ACTIVITY_POLL_INTERVAL_MS = 1500;
 /**
  * Source-of-truth model for the running-terminals panel. Each running
  * terminal session known to the server is one entry; the registry caches
@@ -30,6 +37,11 @@ const LAUNCH_GRACE_MS = 4000;
  * xterm-published title) survives the user closing the tab while the
  * session continues running on the backend.
  *
+ * For sessions running a coding agent it also surfaces a *latest activity*
+ * line — the freshest meaningful line of the terminal's output, read from the
+ * open tab's xterm buffer on a poll (see {@link activityFor}) — so each row
+ * shows what its agent is doing, not just its name.
+ *
  * It also resolves *which agent is running* in each session, so the panel can
  * badge rows with the agent's logo. Two inputs feed that, reconciled by
  * {@link agentCommandFor}:
@@ -52,11 +64,13 @@ const LAUNCH_GRACE_MS = 4000;
  */
 export class SessionRegistry {
     constructor(options) {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e, _f, _g;
         this._labels = new Map();
         this._ranks = new Map();
         this._firstSeen = new Map();
         this._detected = new Map();
+        this._activity = new Map();
+        this._activityEnabled = true;
         this._live = new Set();
         this._currentName = null;
         this._nextRank = 100;
@@ -66,7 +80,8 @@ export class SessionRegistry {
         this._tracker = options.tracker;
         this._agentSessions = (_a = options.agentSessions) !== null && _a !== void 0 ? _a : null;
         this._detectCommands = (_b = options.detectCommands) !== null && _b !== void 0 ? _b : (() => []);
-        this._shell = (_c = options.shell) !== null && _c !== void 0 ? _c : null;
+        this._isAgentCommand = (_c = options.isAgentCommand) !== null && _c !== void 0 ? _c : (() => true);
+        this._shell = (_d = options.shell) !== null && _d !== void 0 ? _d : null;
         this._terminals.runningChanged.connect(this._onRunningChanged, this);
         this._tracker.widgetAdded.connect(this._onWidgetAdded, this);
         this._tracker.forEach(widget => this._trackWidget(widget));
@@ -76,13 +91,13 @@ export class SessionRegistry {
         // other non-terminal tab is current instead. `currentChanged` is optional
         // on the shell interface (not every shell can switch focus), so guard it;
         // when it is absent the highlight stays off.
-        (_e = (_d = this._shell) === null || _d === void 0 ? void 0 : _d.currentChanged) === null || _e === void 0 ? void 0 : _e.connect(this._onShellCurrentChanged, this);
+        (_f = (_e = this._shell) === null || _e === void 0 ? void 0 : _e.currentChanged) === null || _f === void 0 ? void 0 : _f.connect(this._onShellCurrentChanged, this);
         this._updateCurrent();
         // A freshly written launch tag should re-render the panel immediately
         // (show the logo) and again once the grace window closes (so a tag for
         // an agent that never started, or that detection later contradicts,
         // doesn't linger).
-        (_f = this._agentSessions) === null || _f === void 0 ? void 0 : _f.changed.connect(this._onTagChanged, this);
+        (_g = this._agentSessions) === null || _g === void 0 ? void 0 : _g.changed.connect(this._onTagChanged, this);
         this._poll = new Poll({
             name: '@xtralab/terminals:runningAgents',
             factory: () => this._refreshDetection(),
@@ -93,6 +108,16 @@ export class SessionRegistry {
             },
             standby: 'when-hidden'
         });
+        // A second, faster poll reads the live output buffer of each open
+        // coding-agent terminal to keep its "latest activity" line current. Kept
+        // separate from the detection poll so reading xterm buffers neither delays
+        // nor is delayed by the server round-trip that drives the agent badges.
+        this._activityPoll = new Poll({
+            name: '@xtralab/terminals:activity',
+            factory: () => this._refreshActivity(),
+            frequency: { interval: ACTIVITY_POLL_INTERVAL_MS, backoff: false },
+            standby: 'when-hidden'
+        });
     }
     /**
      * Emitted whenever the live session list, a cached label, or the detected
@@ -144,7 +169,10 @@ export class SessionRegistry {
         return `Terminal ${name}`;
     }
     /**
-     * The command of the agent running in the session, or `null` if none.
+     * An identifier for the agent running in the session — its configured
+     * command, or its canonical id when detection matched the spawned process by
+     * id rather than by an aliased command — or `null` if none. Callers resolve
+     * it to a logo through the plugin's `iconForCommand`, which accepts either.
      *
      * Server-side detection is authoritative whenever it reports a running
      * agent. A launch tag fills two gaps: the startup grace window right after
@@ -174,6 +202,44 @@ export class SessionRegistry {
         }
         return 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
+     * session, its tab is closed (so there is no live buffer to read), or the
+     * buffer holds only the agent's input box and chrome. Refreshed on a poll by
+     * {@link _refreshActivity}; shown as a smaller line under the row's title.
+     * Always `null` while the activity line is disabled (see
+     * {@link setActivityEnabled}).
+     */
+    activityFor(name) {
+        var _a;
+        if (!this._activityEnabled) {
+            return null;
+        }
+        return (_a = this._activity.get(name)) !== null && _a !== void 0 ? _a : null;
+    }
+    /**
+     * Turn the per-row latest-activity line on or off, driven by the
+     * `xtralab:terminals` `showAgentActivity` setting. When turned off the
+     * activity poll stops reading terminal buffers and any cached lines are
+     * dropped, so rows fall back to their title alone; when turned back on the
+     * lines are repopulated on the spot. A no-op when the value is unchanged.
+     */
+    setActivityEnabled(enabled) {
+        if (enabled === this._activityEnabled) {
+            return;
+        }
+        this._activityEnabled = enabled;
+        if (enabled) {
+            // Repopulate immediately rather than waiting for the next poll tick;
+            // `_refreshActivity` emits `stateChanged` if it finds anything to show.
+            void this._refreshActivity();
+        }
+        else {
+            this._activity.clear();
+            this._stateChanged.emit();
+        }
+    }
     /**
      * Return the open widget for a session, if any. The panel uses this to
      * switch behavior between "activate existing tab" and "open a new tab
@@ -215,6 +281,7 @@ export class SessionRegistry {
         }
         this._isDisposed = true;
         this._poll.dispose();
+        this._activityPoll.dispose();
         this._terminals.runningChanged.disconnect(this._onRunningChanged, this);
         this._tracker.widgetAdded.disconnect(this._onWidgetAdded, this);
         (_a = this._agentSessions) === null || _a === void 0 ? void 0 : _a.changed.disconnect(this._onTagChanged, this);
@@ -272,6 +339,11 @@ export class SessionRegistry {
                 this._detected.delete(name);
             }
         }
+        for (const name of Array.from(this._activity.keys())) {
+            if (!next.has(name)) {
+                this._activity.delete(name);
+            }
+        }
         // Forget launch tags for sessions that have gone away. This matters for
         // correctness as well as bookkeeping: terminado reuses session names, so
         // a stale tag could otherwise mislabel a brand-new terminal that happens
@@ -311,6 +383,62 @@ export class SessionRegistry {
             this._stateChanged.emit();
         }
     }
+    /**
+     * Poll body: re-read the buffer of each open coding-agent terminal and cache
+     * its latest meaningful line of output. Only sessions that have a running
+     * *agent* (not an editor) and an open tab qualify — a closed tab has no live
+     * buffer, editors run full-screen UIs that are not "activity", and plain
+     * shells would only echo their prompt. While a tab is reopening (its xterm
+     * is not ready yet) any existing line is kept; once the buffer is readable
+     * but has nothing worth showing the line is dropped, so a screen the agent
+     * has cleared doesn't leave a frozen line behind. Cached lines for sessions
+     * that no longer qualify are pruned. Emits only when something changed.
+     */
+    async _refreshActivity() {
+        if (!this._activityEnabled) {
+            return;
+        }
+        let changed = false;
+        const qualifying = new Set();
+        for (const name of this._live) {
+            const command = this.agentCommandFor(name);
+            if (command === null || !this._isAgentCommand(command)) {
+                continue;
+            }
+            const widget = this.widgetFor(name);
+            if (!widget) {
+                continue;
+            }
+            qualifying.add(name);
+            const term = widget.content._term;
+            if (!term) {
+                // The tab is reopening and its xterm is not ready; keep any existing
+                // line until the buffer can be read again.
+                continue;
+            }
+            const line = Private.readActivity(term);
+            if (line) {
+                if (this._activity.get(name) !== line) {
+                    this._activity.set(name, line);
+                    changed = true;
+                }
+            }
+            else if (this._activity.delete(name)) {
+                // Readable buffer with nothing to surface (e.g. the agent cleared its
+                // screen) — drop the now-stale line instead of freezing it.
+                changed = true;
+            }
+        }
+        for (const name of Array.from(this._activity.keys())) {
+            if (!qualifying.has(name)) {
+                this._activity.delete(name);
+                changed = true;
+            }
+        }
+        if (changed) {
+            this._stateChanged.emit();
+        }
+    }
     _onTagChanged() {
         this._stateChanged.emit();
         // Re-render once the grace window closes so a tag that detection never
@@ -415,4 +543,132 @@ var Private;
         return true;
     }
     Private.detectedEqual = detectedEqual;
+    /** 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. */
+    const ACTIVITY_MAX_LENGTH = 160;
+    /**
+     * Horizontal box-drawing / rule characters, treated as blanks when
+     * sanitizing. Agents pad a status line or draw a separator with these (e.g.
+     * `Worked for 1m 06s ────`), which is chrome, not text. Vertical bars are
+     * deliberately excluded — {@link isMeaningfulActivity} relies on them to
+     * recognise (and skip) the contents of an input/quote box.
+     */
+    const RULE_CHARS = new Set([
+        0x2500, 0x2501, 0x2504, 0x2505, 0x2508, 0x2509, 0x254c, 0x254d, 0x2550
+    ]);
+    /**
+     * The most recent meaningful line of agent output, or `null` if none is
+     * found. Agents park the cursor in an input box at the bottom of the screen,
+     * so the scan starts there and walks *up*, skipping that box, any hint or
+     * footer beneath it, blank lines and separators, until it reaches the block
+     * of real output nearest the input. It then rewinds to that block's first row
+     * and stitches the block back together (see {@link joinBlock}), so a reply
+     * the agent hard-wrapped across several rows reads as its opening sentence
+     * rather than the trailing fragment left next to the cursor.
+     */
+    function readActivity(term) {
+        var _a;
+        const buffer = (_a = term.buffer) === null || _a === void 0 ? void 0 : _a.active;
+        if (!buffer) {
+            return null;
+        }
+        const cursorRow = buffer.baseY + buffer.cursorY;
+        const limit = Math.max(0, cursorRow - ACTIVITY_SCAN_ROWS);
+        for (let row = cursorRow; row >= limit; row--) {
+            if (!isMeaningfulActivity(lineText(buffer, row))) {
+                continue;
+            }
+            // `row` is the bottom of the output block nearest the input; walk up
+            // while rows stay meaningful to find the block's first row.
+            let topRow = row;
+            while (topRow > limit &&
+                isMeaningfulActivity(lineText(buffer, topRow - 1))) {
+                topRow--;
+            }
+            return clampActivity(joinBlock(buffer, topRow, row));
+        }
+        return null;
+    }
+    Private.readActivity = readActivity;
+    /** Sanitized text of one buffer row. */
+    function lineText(buffer, row) {
+        var _a, _b;
+        return sanitizeActivity((_b = (_a = buffer.getLine(row)) === null || _a === void 0 ? void 0 : _a.translateToString(true)) !== null && _b !== void 0 ? _b : '');
+    }
+    Private.lineText = lineText;
+    /**
+     * Stitch rows `[topRow, lastRow]` of one output block into a single string,
+     * stopping once it is long enough to fill the row. A soft-wrapped row
+     * continues the previous one mid-word, so it is appended directly; a hard
+     * newline is a word boundary, so it is joined with a space.
+     */
+    function joinBlock(buffer, topRow, lastRow) {
+        var _a;
+        let result = lineText(buffer, topRow);
+        for (let row = topRow + 1; row <= lastRow; row++) {
+            if (Array.from(result).length >= ACTIVITY_MAX_LENGTH) {
+                break;
+            }
+            const bufferLine = buffer.getLine(row);
+            const text = sanitizeActivity((_a = bufferLine === null || bufferLine === void 0 ? void 0 : bufferLine.translateToString(true)) !== null && _a !== void 0 ? _a : '');
+            if (!text) {
+                continue;
+            }
+            result += (bufferLine === null || bufferLine === void 0 ? void 0 : bufferLine.isWrapped) ? text : ` ${text}`;
+        }
+        return result;
+    }
+    Private.joinBlock = joinBlock;
+    /** Truncate by code point (never splitting an emoji) with an ellipsis. */
+    function clampActivity(text) {
+        const points = Array.from(text);
+        return points.length > ACTIVITY_MAX_LENGTH
+            ? `${points.slice(0, ACTIVITY_MAX_LENGTH - 1).join('')}…`
+            : text;
+    }
+    Private.clampActivity = clampActivity;
+    /**
+     * Collapse a raw buffer row into displayable text: replace control characters
+     * and horizontal rule characters with spaces (so no escape sequence or drawn
+     * separator rides along), squeeze runs of whitespace, and trim.
+     */
+    function sanitizeActivity(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 || RULE_CHARS.has(code) ? ' ' : char;
+        }
+        return result.replace(/\s+/g, ' ').trim();
+    }
+    Private.sanitizeActivity = sanitizeActivity;
+    /**
+     * Whether a sanitized row is worth showing as activity, i.e. real output
+     * rather than chrome. Doubles as the block-boundary test for
+     * {@link readActivity}'s walk up. A row is skipped when it:
+     *   - is blank or pure box-drawing (carries no letter or digit);
+     *   - begins with a vertical box-drawing bar (the contents of an input or
+     *     quote box), a prompt chevron (the input row and its ghost suggestion),
+     *     or Claude's tool-result / tip marker `⎿`; or
+     *   - is a transient status footer — one carrying a `for <time>` / `(<time>`
+     *     elapsed-time stamp, as agents print while and after they work
+     *     ("✻ Churned for 17s", "Working… (8s · …)", "— Worked for 1m 06s"). This
+     *     carries no real content, so skipping it lets the scan reach the reply
+     *     the agent wrote just above it.
+     */
+    function isMeaningfulActivity(text) {
+        if (!text) {
+            return false;
+        }
+        if (/^[│┃║❯❮›‹⎿]/u.test(text)) {
+            return false;
+        }
+        if (/(?:for |\()\d+(?:\s?m\s?\d+)?s\b/u.test(text)) {
+            return false;
+        }
+        return /[\p{L}\p{N}]/u.test(text);
+    }
+    Private.isMeaningfulActivity = isMeaningfulActivity;
 })(Private || (Private = {}));

package/lib/terminals/widget.d.ts

@@ -13,7 +13,9 @@ export declare const RUNNING_TERMINALS_ID = "xtralab-running-terminals";
  * launcher *starts* sessions, this panel surfaces the ones already
  * running so the user can jump back to a backgrounded agent — including
  * sessions whose tab has been closed but which are still alive on the
- * server.
+ * server. Each row is labelled with the session's title and, for a session
+ * running a coding agent, a smaller line below it showing the agent's latest
+ * line of output (from {@link SessionRegistry.activityFor}).
  *
  * Backed by {@link SessionRegistry}: a `UseSignal` re-renders the list
  * whenever the registry emits `stateChanged`, so it tracks

package/lib/terminals/widget.js

@@ -12,7 +12,9 @@ export const RUNNING_TERMINALS_ID = 'xtralab-running-terminals';
  * launcher *starts* sessions, this panel surfaces the ones already
  * running so the user can jump back to a backgrounded agent — including
  * sessions whose tab has been closed but which are still alive on the
- * server.
+ * server. Each row is labelled with the session's title and, for a session
+ * running a coding agent, a smaller line below it showing the agent's latest
+ * line of output (from {@link SessionRegistry.activityFor}).
  *
  * Backed by {@link SessionRegistry}: a `UseSignal` re-renders the list
  * whenever the registry emits `stateChanged`, so it tracks
@@ -81,12 +83,18 @@ function RunningTerminalsComponent(props) {
             // icon when nothing recognised is running in the session.
             const RowIcon = iconForCommand(registry.agentCommandFor(name)).react;
             const isCurrent = name === currentName;
+            // The latest line of output from the session's agent, shown as a
+            // smaller line under the title; `null` for rows with nothing to
+            // surface (no agent running, or no open tab to read a live buffer).
+            const activity = registry.activityFor(name);
             return (React.createElement("li", { key: name, className: isCurrent
                     ? 'jp-xtralab-Terminals-item jp-mod-current'
                     : 'jp-xtralab-Terminals-item' },
                 React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-item-activate", onClick: () => onActivate(name), title: tooltip, "aria-label": tooltip, "aria-current": isCurrent || undefined },
-                    React.createElement(RowIcon, { tag: "span", verticalAlign: "middle" }),
-                    React.createElement("span", { className: "jp-xtralab-Terminals-item-label" }, label)),
+                    React.createElement(RowIcon, { tag: "span", className: "jp-xtralab-Terminals-item-icon", verticalAlign: "middle" }),
+                    React.createElement("span", { className: "jp-xtralab-Terminals-item-text" },
+                        React.createElement("span", { className: "jp-xtralab-Terminals-item-label" }, label),
+                        activity ? (React.createElement("span", { className: "jp-xtralab-Terminals-item-detail" }, activity)) : null)),
                 React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-item-close", onClick: () => onShutdown(name), title: trans.__('Shut down %1', label), "aria-label": trans.__('Shut down %1', label) },
                     React.createElement(closeIcon.react, { tag: "span", verticalAlign: "middle" }))));
         })))));

package/lib/walkthrough/index.d.ts

@@ -0,0 +1,14 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Contribute `xtralab:walkthrough`: build a persistent, read-only walkthrough
+ * in the right side area instead of narrating only in the agent's chat.
+ *
+ * Each call appends a step (Markdown prose, an optional embedded visual, and an
+ * optional code reference). When a step names a file, the editor follows along
+ * (opening it full-width in the main area, no split) and its lines are
+ * highlighted; the step also keeps a button so the user can jump back to it
+ * later. The panel accumulates the whole tour beside the code, so the user can
+ * read at their own pace rather than chasing the chat.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;