xtralab 0.10.0 → 0.11.0

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;

package/lib/walkthrough/index.js

@@ -0,0 +1,162 @@
+import { ILabShell } from '@jupyterlab/application';
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { tocIcon } from '@jupyterlab/ui-components';
+import { WalkthroughPanel } from './panel';
+const PLUGIN_ID = 'xtralab:walkthrough';
+/** 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. */
+function readMedia(value) {
+    if (value &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        typeof value.mimeType === 'string') {
+        const media = value;
+        return { mimeType: media.mimeType, data: media.data };
+    }
+    return undefined;
+}
+function toLine(value) {
+    const n = Math.trunc(Number(value));
+    return Number.isFinite(n) && n >= 1 ? n : undefined;
+}
+/**
+ * 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.
+ */
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Build a read-only guided walkthrough in the side panel.',
+    autoStart: true,
+    requires: [IRenderMimeRegistry, ILabShell],
+    optional: [ICommandPalette, ITranslator],
+    activate: (app, rendermime, labShell, palette, translator) => {
+        const { commands } = app;
+        const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
+        let panel = null;
+        const ensurePanel = () => {
+            if (!panel || panel.isDisposed) {
+                panel = new WalkthroughPanel({ rendermime, commands, trans });
+                panel.id = PANEL_ID;
+                panel.title.icon = tocIcon;
+                panel.title.label = trans.__('Walkthrough');
+                panel.title.caption = trans.__('Walkthrough');
+                // Closable so it gets a close button if the user drags it out of the
+                // side area into the main document area. Closing disposes it; the next
+                // xtralab:walkthrough call recreates it back in the side area.
+                panel.title.closable = true;
+                labShell.add(panel, 'right', { rank: 1000, type: 'Walkthrough' });
+                const created = panel;
+                created.disposed.connect(() => {
+                    if (panel === created) {
+                        panel = null;
+                    }
+                });
+            }
+            return panel;
+        };
+        commands.addCommand(WALKTHROUGH_COMMAND, {
+            label: trans.__('Add Walkthrough Step'),
+            caption: trans.__('Append a step to the read-only walkthrough panel'),
+            describedBy: {
+                args: {
+                    type: 'object',
+                    properties: {
+                        title: {
+                            type: 'string',
+                            description: 'Optional heading for the step.'
+                        },
+                        body: {
+                            type: 'string',
+                            description: 'Markdown for the step. Renders code snippets, lists, math, and Mermaid diagrams from a ```mermaid fenced block.'
+                        },
+                        path: {
+                            type: 'string',
+                            description: 'Optional file the step is about, relative to the server root. The editor opens it (full width, no split) and highlights the lines, and the step keeps a button to jump back.'
+                        },
+                        line: {
+                            type: 'number',
+                            description: 'First line to highlight (1-indexed).'
+                        },
+                        endLine: {
+                            type: 'number',
+                            description: 'Last line to highlight (1-indexed, inclusive).'
+                        },
+                        media: {
+                            type: 'object',
+                            description: 'Optional embedded visual, e.g. { "mimeType": "application/vnd.vegalite.v5+json", "data": <spec> }.',
+                            properties: {
+                                mimeType: { type: 'string' },
+                                data: {}
+                            },
+                            required: ['mimeType', 'data']
+                        },
+                        reveal: {
+                            type: 'boolean',
+                            description: 'Whether to navigate and highlight the code as the step is added. Defaults to true.'
+                        },
+                        reset: {
+                            type: 'boolean',
+                            description: 'Clear the existing walkthrough before adding this step (start a new tour).'
+                        }
+                    }
+                }
+            },
+            execute: async (args) => {
+                const current = ensurePanel();
+                if (args['reset'] === true) {
+                    current.clear();
+                }
+                const path = typeof args['path'] === 'string' ? args['path'] : undefined;
+                const line = toLine(args['line']);
+                const endLine = toLine(args['endLine']);
+                const media = readMedia(args['media']);
+                const step = {
+                    title: typeof args['title'] === 'string' ? args['title'] : undefined,
+                    body: typeof args['body'] === 'string' ? args['body'] : undefined,
+                    media,
+                    path,
+                    line,
+                    endLine
+                };
+                if (!step.title &&
+                    !step.body &&
+                    !step.media &&
+                    !step.path &&
+                    args['reset'] !== true) {
+                    throw new Error('xtralab:walkthrough needs at least one of: title, body, media, path');
+                }
+                // Reveal the panel, then render the step into it.
+                labShell.activateById(current.id);
+                await current.addStep(step);
+                // Let the editor follow the newest step.
+                if (path && args['reveal'] !== false) {
+                    await commands.execute(HIGHLIGHT_LINES_COMMAND, {
+                        path,
+                        line,
+                        endLine
+                    });
+                }
+                return trans.__('Added walkthrough step');
+            }
+        });
+        if (palette) {
+            palette.addItem({
+                command: WALKTHROUGH_COMMAND,
+                category: trans.__('Other')
+            });
+        }
+    }
+};
+export default plugin;

package/lib/walkthrough/panel.d.ts

@@ -0,0 +1,54 @@
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import type { TranslationBundle } from '@jupyterlab/translation';
+import type { CommandRegistry } from '@lumino/commands';
+import type { ReadonlyPartialJSONValue } from '@lumino/coreutils';
+import type { Message } from '@lumino/messaging';
+import { Panel } from '@lumino/widgets';
+/** A rich visual embedded in a step (rendered through the rendermime registry). */
+export interface IWalkthroughMedia {
+    mimeType: string;
+    data: ReadonlyPartialJSONValue;
+}
+/** One step of a walkthrough. Every field is optional, but a step needs at least one. */
+export interface IWalkthroughStep {
+    title?: string;
+    body?: string;
+    media?: IWalkthroughMedia;
+    path?: string;
+    line?: number;
+    endLine?: number;
+}
+export declare namespace WalkthroughPanel {
+    interface IOptions {
+        rendermime: IRenderMimeRegistry;
+        commands: CommandRegistry;
+        trans: TranslationBundle;
+    }
+}
+/**
+ * A read-only, scrollable column of walkthrough steps for the side area.
+ *
+ * The agent appends steps as it narrates, so the explanation lives beside the
+ * code the user is looking at and persists for them to read at their own pace,
+ * rather than scrolling away in the chat. Each step renders Markdown (with code
+ * snippets, Mermaid, math), can embed a rich visual, and can offer a button
+ * that opens the referenced file and highlights its lines.
+ */
+export declare class WalkthroughPanel extends Panel {
+    constructor(options: WalkthroughPanel.IOptions);
+    /** Remove every step, leaving an empty panel. */
+    clear(): void;
+    /**
+     * Dispose on close (e.g. the close button when the panel has been dragged to
+     * the main area) rather than leaving a detached, reusable widget behind. The
+     * next `xtralab:walkthrough` call recreates the panel in the side area.
+     */
+    protected onCloseRequest(msg: Message): void;
+    /** Append a step and scroll it into view. */
+    addStep(step: IWalkthroughStep): Promise<void>;
+    private _render;
+    private _jumpButton;
+    private _rendermime;
+    private _commands;
+    private _trans;
+}