jupyterlab_ai_code_assistants_extension 0.6.15

package/lib/core/terminals.d.ts

@@ -0,0 +1,129 @@
+import { JupyterFrontEnd } from '@jupyterlab/application';
+import { Dialog } from '@jupyterlab/apputils';
+import { ServerConnection } from '@jupyterlab/services';
+import { ITerminalTracker } from '@jupyterlab/terminal';
+import { IColourfulTabs } from 'jupyterlab_colourful_tab_extension';
+import { ColourStore } from './colour';
+import { ILaunchRequest, IProviderDescriptor, ISession, ITerminalProbeResponse } from './types';
+/** Show a modal spinner while a terminal is being launched. The caller
+ * dismisses it with `.dispose()` when the launch settles.
+ *
+ * Cancel does not abort the request - it only takes the app-wide scrim away, so
+ * a stalled launch cannot leave the user staring at a modal with no exit. If
+ * the launch later succeeds the terminal simply appears. */
+export declare function showLaunchSpinner(title: string): Dialog<unknown>;
+/**
+ * Terminals for one provider: the reuse ladder, the launch call and the tab
+ * tint pass.
+ *
+ * Split out of the panel because none of it is presentation - it is process
+ * identity. The panel asks for a conversation and gets a focused terminal
+ * running exactly that conversation, or a fresh one; nothing in here knows
+ * about sections, filters or menus.
+ */
+export declare class TerminalManager {
+    constructor(options: TerminalManager.IOptions);
+    dispose(): void;
+    /**
+     * Open a conversation, reusing an open terminal only when that terminal is
+     * POSITIVELY running it.
+     *
+     * Three steps, cheapest first: the per-project microcache, then a walk of
+     * every terminal JupyterLab knows about (each probed server-side for the
+     * conversation its process actually holds), then a fresh launch. A terminal
+     * whose conversation cannot be read is never reused - it may be running a
+     * different conversation of the same project, and a session id is globally
+     * unique, so an unreadable terminal can never be proven to be the wanted one.
+     *
+     * Concurrent clicks on the SAME conversation attach to the in-flight
+     * promise; a different conversation of the same project launches
+     * independently, so branches open side by side.
+     */
+    openSession(session: ISession, mode: string | undefined, sessionId?: string): Promise<void>;
+    private _doOpenSession;
+    /**
+     * Launch a terminal for one request and focus it. The returned widget is
+     * tagged with `tagSessionId` in the microcache, so a later click on the row
+     * that conversation now belongs to reuses this very terminal.
+     */
+    launch(request: ILaunchRequest, tagSessionId?: string): Promise<any>;
+    /**
+     * Bring a terminal tab to the front AND hand it keyboard focus, so typing
+     * starts without a second click. `activateById` only reveals the tab; the
+     * xterm inside does not reliably take DOM focus when the click came from the
+     * sidebar, so the focus call is deferred to the next frame - by then the
+     * widget is attached and visible.
+     */
+    focus(widget: any): void;
+    /** Find an open terminal running exactly this conversation, or null.
+     *
+     * Matches on the conversation id ALONE. The server reads the true id from
+     * the running process, so a session the user started by hand is recognised
+     * too, not only launches that carry an argv id. An id is globally unique to
+     * one conversation, so a terminal holding it IS the one to focus, whatever
+     * cwd it reports - a process that changed directory, or whose project dir
+     * was recreated, must still be reused rather than duplicated. */
+    findForSession(wantedSessionId: string | undefined): Promise<{
+        widget: any;
+        runningId: string | null;
+    } | null>;
+    /** Ask the server what a terminal is running. Null when the widget has no
+     * session name yet, or the probe fails - a terminal can vanish between
+     * enumeration and probe, which is a retry, not an error. */
+    probe(widget: any): Promise<ITerminalProbeResponse | null>;
+    /** Turn tinting on or off. Off drops the tint from this provider's terminals
+     * at once rather than at the next reload; on re-tints from current state. */
+    setColouredTabs(on: boolean): void;
+    /** Remember the sessions the last poll returned, so the colour loop can run
+     * on its own timer without asking the panel for state. */
+    setSessions(sessions: ISession[]): void;
+    /** Arm the colour loop. Independent of panel visibility: a terminal running
+     * the assistant is tinted whether or not the panel is on screen. */
+    startColourLoop(): void;
+    stopColourLoop(): void;
+    /**
+     * Re-tint every open terminal of this assistant from the freshest colours,
+     * whether this panel launched it or the user opened it themselves.
+     *
+     * Each terminal's conversation is re-resolved on every pass rather than
+     * taken from the launch cache, which pins the launch-time conversation and
+     * goes stale on an in-place switch. On the way through, a colour the user
+     * set by hand on the tab is written back into this provider's colour store,
+     * which is what makes "set the tab colour" mean "this conversation's colour"
+     * even for an assistant whose CLI has no colour concept.
+     */
+    reconcileColours(): Promise<void>;
+    /** Effective colour of one conversation right now, for branch inheritance
+     * at the fork sites. */
+    colourFor(session: ISession, sessionId?: string): string | null;
+    /** Drop the tint from this assistant's terminals. Only its own terminals are
+     * touched, so a tint the user set by hand on another tab survives. */
+    clearColours(): Promise<void>;
+    private _applyColour;
+    private _eachAssistantTerminal;
+    private _liveTerminals;
+    private _wireDisposal;
+    private _key;
+    private readonly _app;
+    private readonly _descriptor;
+    private readonly _colours;
+    private readonly _tracker;
+    private readonly _colourfulTabs;
+    private readonly _serverSettings;
+    private readonly _byProject;
+    private readonly _pending;
+    private _sessions;
+    private _colouredTabs;
+    private _colourHandle;
+    private _disposed;
+}
+export declare namespace TerminalManager {
+    interface IOptions {
+        app: JupyterFrontEnd;
+        descriptor: IProviderDescriptor;
+        colourStore: ColourStore;
+        terminalTracker: ITerminalTracker | null;
+        colourfulTabs: IColourfulTabs | null;
+        serverSettings: ServerConnection.ISettings;
+    }
+}

package/lib/core/terminals.js

@@ -0,0 +1,344 @@
+import { Dialog } from '@jupyterlab/apputils';
+import { Widget } from '@lumino/widgets';
+import { effectiveColour, readUserSetTabColour, sessionForCwds } from './colour';
+import { requestProvider } from './request';
+/** Colour reconciliation cadence. Matches the row poll so the two collapse
+ * into one rhythm while the panel is visible, but it is a separate timer: a
+ * terminal running the assistant is tinted whether or not the panel is open. */
+const COLOUR_INTERVAL_MS = 30000;
+/** Show a modal spinner while a terminal is being launched. The caller
+ * dismisses it with `.dispose()` when the launch settles.
+ *
+ * Cancel does not abort the request - it only takes the app-wide scrim away, so
+ * a stalled launch cannot leave the user staring at a modal with no exit. If
+ * the launch later succeeds the terminal simply appears. */
+export function showLaunchSpinner(title) {
+    const body = new Widget();
+    body.node.className = 'jp-AiAssistantsPanel-launchOverlay';
+    const spinner = document.createElement('div');
+    spinner.className =
+        'jp-aiAssistants-spinner jp-AiAssistantsPanel-launchSpinner';
+    body.node.appendChild(spinner);
+    const dialog = new Dialog({
+        title,
+        body,
+        buttons: [Dialog.cancelButton()]
+    });
+    // `launch()` returns a promise nobody awaits - disposing an open Lumino
+    // dialog rejects it with `undefined`, so swallow that here and keep a benign
+    // teardown from surfacing as an unhandled rejection.
+    dialog.launch().catch(() => undefined);
+    return dialog;
+}
+/**
+ * Terminals for one provider: the reuse ladder, the launch call and the tab
+ * tint pass.
+ *
+ * Split out of the panel because none of it is presentation - it is process
+ * identity. The panel asks for a conversation and gets a focused terminal
+ * running exactly that conversation, or a fresh one; nothing in here knows
+ * about sections, filters or menus.
+ */
+export class TerminalManager {
+    constructor(options) {
+        // Most recent terminal per project, tagged with the conversation it runs so
+        // reuse can tell a project's branches apart.
+        this._byProject = new Map();
+        // In-flight launches keyed per CONVERSATION, so two branches of one project
+        // open independently and concurrently.
+        this._pending = new Map();
+        this._sessions = [];
+        this._colouredTabs = true;
+        this._colourHandle = null;
+        this._disposed = false;
+        this._app = options.app;
+        this._descriptor = options.descriptor;
+        this._colours = options.colourStore;
+        this._tracker = options.terminalTracker;
+        this._colourfulTabs = options.colourfulTabs;
+        this._serverSettings = options.serverSettings;
+    }
+    dispose() {
+        this._disposed = true;
+        this.stopColourLoop();
+    }
+    /**
+     * Open a conversation, reusing an open terminal only when that terminal is
+     * POSITIVELY running it.
+     *
+     * Three steps, cheapest first: the per-project microcache, then a walk of
+     * every terminal JupyterLab knows about (each probed server-side for the
+     * conversation its process actually holds), then a fresh launch. A terminal
+     * whose conversation cannot be read is never reused - it may be running a
+     * different conversation of the same project, and a session id is globally
+     * unique, so an unreadable terminal can never be proven to be the wanted one.
+     *
+     * Concurrent clicks on the SAME conversation attach to the in-flight
+     * promise; a different conversation of the same project launches
+     * independently, so branches open side by side.
+     */
+    async openSession(session, mode, sessionId) {
+        const wanted = sessionId !== null && sessionId !== void 0 ? sessionId : session.session_id;
+        const key = this._key(session.project_path, wanted);
+        const inFlight = this._pending.get(key);
+        if (inFlight) {
+            return inFlight;
+        }
+        const promise = this._doOpenSession(session, mode, wanted).finally(() => {
+            this._pending.delete(key);
+        });
+        this._pending.set(key, promise);
+        return promise;
+    }
+    async _doOpenSession(session, mode, wanted) {
+        var _a;
+        // 1. Microcache - the most recent terminal of this project, reused only
+        // when it carries the wanted conversation.
+        const cached = this._byProject.get(session.project_path);
+        if (cached && !cached.widget.isDisposed && cached.sessionId === wanted) {
+            this.focus(cached.widget);
+            return;
+        }
+        // 2. Walk every live terminal, asking the server what each is running.
+        const found = await this.findForSession(wanted);
+        if (found) {
+            // Tag with the OBSERVED conversation, so a later reuse trusts a
+            // confirmed identity rather than a wish.
+            this._byProject.set(session.project_path, {
+                widget: found.widget,
+                sessionId: (_a = found.runningId) !== null && _a !== void 0 ? _a : undefined
+            });
+            this._wireDisposal(session.project_path, found.widget);
+            this.focus(found.widget);
+            return;
+        }
+        // 3. Fresh launch. The server picks the verb (resume, attach, bare) at
+        // launch time, because ownership of a conversation can change inside the
+        // poll window and only the server can be authoritative about it.
+        await this.launch({
+            project_path: session.project_path,
+            encoded_path: session.encoded_path,
+            session_id: wanted,
+            mode
+        }, wanted);
+    }
+    /**
+     * Launch a terminal for one request and focus it. The returned widget is
+     * tagged with `tagSessionId` in the microcache, so a later click on the row
+     * that conversation now belongs to reuses this very terminal.
+     */
+    async launch(request, tagSessionId) {
+        const spinner = showLaunchSpinner(`Opening ${this._descriptor.label}`);
+        try {
+            const launched = await requestProvider(this._descriptor.id, 'launch', this._serverSettings, { method: 'POST', body: JSON.stringify(request) });
+            const widget = await this._app.commands.execute('terminal:open', {
+                name: launched.terminal_name
+            });
+            if (widget === null || widget === void 0 ? void 0 : widget.id) {
+                this._byProject.set(request.project_path, {
+                    widget,
+                    sessionId: tagSessionId
+                });
+                this._wireDisposal(request.project_path, widget);
+                this.focus(widget);
+            }
+            return widget !== null && widget !== void 0 ? widget : null;
+        }
+        finally {
+            spinner.dispose();
+        }
+    }
+    /**
+     * Bring a terminal tab to the front AND hand it keyboard focus, so typing
+     * starts without a second click. `activateById` only reveals the tab; the
+     * xterm inside does not reliably take DOM focus when the click came from the
+     * sidebar, so the focus call is deferred to the next frame - by then the
+     * widget is attached and visible.
+     */
+    focus(widget) {
+        if (!widget || widget.isDisposed) {
+            return;
+        }
+        this._app.shell.activateById(widget.id);
+        requestAnimationFrame(() => {
+            var _a, _b, _c;
+            try {
+                (_c = (_b = (_a = widget.content) === null || _a === void 0 ? void 0 : _a.term) === null || _b === void 0 ? void 0 : _b.focus) === null || _c === void 0 ? void 0 : _c.call(_b);
+            }
+            catch (_err) {
+                // Disposed in the meantime - nothing to focus.
+            }
+        });
+    }
+    /** Find an open terminal running exactly this conversation, or null.
+     *
+     * Matches on the conversation id ALONE. The server reads the true id from
+     * the running process, so a session the user started by hand is recognised
+     * too, not only launches that carry an argv id. An id is globally unique to
+     * one conversation, so a terminal holding it IS the one to focus, whatever
+     * cwd it reports - a process that changed directory, or whose project dir
+     * was recreated, must still be reused rather than duplicated. */
+    async findForSession(wantedSessionId) {
+        if (!this._tracker || !wantedSessionId) {
+            return null;
+        }
+        for (const widget of this._liveTerminals()) {
+            const info = await this.probe(widget);
+            if (info && info.session_id && info.session_id === wantedSessionId) {
+                return { widget, runningId: info.session_id };
+            }
+        }
+        return null;
+    }
+    /** Ask the server what a terminal is running. Null when the widget has no
+     * session name yet, or the probe fails - a terminal can vanish between
+     * enumeration and probe, which is a retry, not an error. */
+    async probe(widget) {
+        var _a, _b;
+        const name = (_b = (_a = widget === null || widget === void 0 ? void 0 : widget.content) === null || _a === void 0 ? void 0 : _a.session) === null || _b === void 0 ? void 0 : _b.name;
+        if (typeof name !== 'string' || !name) {
+            return null;
+        }
+        try {
+            return await requestProvider(this._descriptor.id, `terminal/${encodeURIComponent(name)}`, this._serverSettings);
+        }
+        catch (_err) {
+            return null;
+        }
+    }
+    // --------------------------------------------------------------- colours
+    /** Turn tinting on or off. Off drops the tint from this provider's terminals
+     * at once rather than at the next reload; on re-tints from current state. */
+    setColouredTabs(on) {
+        const enabled = !!on;
+        if (this._colouredTabs === enabled) {
+            return;
+        }
+        this._colouredTabs = enabled;
+        void (enabled ? this.reconcileColours() : this.clearColours());
+    }
+    /** Remember the sessions the last poll returned, so the colour loop can run
+     * on its own timer without asking the panel for state. */
+    setSessions(sessions) {
+        this._sessions = sessions;
+    }
+    /** Arm the colour loop. Independent of panel visibility: a terminal running
+     * the assistant is tinted whether or not the panel is on screen. */
+    startColourLoop() {
+        if (this._disposed || this._colourHandle !== null) {
+            return;
+        }
+        this._colourHandle = window.setTimeout(() => {
+            this._colourHandle = null;
+            void this.reconcileColours();
+        }, COLOUR_INTERVAL_MS);
+    }
+    stopColourLoop() {
+        if (this._colourHandle !== null) {
+            window.clearTimeout(this._colourHandle);
+            this._colourHandle = null;
+        }
+    }
+    /**
+     * Re-tint every open terminal of this assistant from the freshest colours,
+     * whether this panel launched it or the user opened it themselves.
+     *
+     * Each terminal's conversation is re-resolved on every pass rather than
+     * taken from the launch cache, which pins the launch-time conversation and
+     * goes stale on an in-place switch. On the way through, a colour the user
+     * set by hand on the tab is written back into this provider's colour store,
+     * which is what makes "set the tab colour" mean "this conversation's colour"
+     * even for an assistant whose CLI has no colour concept.
+     */
+    async reconcileColours() {
+        if (!this._colouredTabs) {
+            // No rearm: `setColouredTabs(true)` calls straight back in here.
+            return;
+        }
+        try {
+            await this._eachAssistantTerminal(async (widget, info) => {
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+                const sessionId = (_d = (_a = info.session_id) !== null && _a !== void 0 ? _a : (_c = sessionForCwds((_b = info.cwds) !== null && _b !== void 0 ? _b : [], this._sessions)) === null || _c === void 0 ? void 0 : _c.session_id) !== null && _d !== void 0 ? _d : null;
+                const terminalName = (_g = (_f = (_e = widget === null || widget === void 0 ? void 0 : widget.content) === null || _e === void 0 ? void 0 : _e.session) === null || _f === void 0 ? void 0 : _f.name) !== null && _g !== void 0 ? _g : '';
+                // Write-back. Native-colour assistants own their colour, so their
+                // tabs are read-only here; for the others the tab IS the control
+                // surface.
+                if (sessionId &&
+                    terminalName &&
+                    this._descriptor.colourSource !== 'native') {
+                    const userSet = readUserSetTabColour(terminalName);
+                    if (userSet && userSet !== this._colours.get(sessionId)) {
+                        await this._colours.set(sessionId, userSet);
+                    }
+                }
+                const native = (_h = info.colour) !== null && _h !== void 0 ? _h : (sessionId
+                    ? ((_k = (_j = this._sessions.find(s => s.session_id === sessionId)) === null || _j === void 0 ? void 0 : _j.colour) !== null && _k !== void 0 ? _k : null)
+                    : null);
+                this._applyColour(widget, effectiveColour(sessionId, this._descriptor.colourSource, this._colours.get(sessionId), native));
+            });
+        }
+        finally {
+            // Always rearm, even after a failed pass - one bad probe must not end
+            // tinting for the rest of the session.
+            this.startColourLoop();
+        }
+    }
+    /** Effective colour of one conversation right now, for branch inheritance
+     * at the fork sites. */
+    colourFor(session, sessionId) {
+        var _a;
+        const id = sessionId !== null && sessionId !== void 0 ? sessionId : session.session_id;
+        return effectiveColour(id, this._descriptor.colourSource, this._colours.get(id), (_a = session.colour) !== null && _a !== void 0 ? _a : null);
+    }
+    /** Drop the tint from this assistant's terminals. Only its own terminals are
+     * touched, so a tint the user set by hand on another tab survives. */
+    async clearColours() {
+        await this._eachAssistantTerminal(async (widget) => {
+            this._applyColour(widget, null);
+        });
+    }
+    _applyColour(widget, colourId) {
+        if (!this._colourfulTabs || !widget || widget.isDisposed) {
+            return;
+        }
+        this._colourfulTabs.setColour(widget, colourId);
+    }
+    async _eachAssistantTerminal(apply) {
+        if (!this._colourfulTabs || !this._tracker) {
+            return;
+        }
+        const widgets = this._liveTerminals();
+        await Promise.all(widgets.map(async (widget) => {
+            const info = await this.probe(widget);
+            if (!info || !info.running || widget.isDisposed) {
+                return;
+            }
+            await apply(widget, info);
+        }));
+    }
+    _liveTerminals() {
+        var _a;
+        const widgets = [];
+        (_a = this._tracker) === null || _a === void 0 ? void 0 : _a.forEach((widget) => {
+            if (widget && !widget.isDisposed) {
+                widgets.push(widget);
+            }
+        });
+        return widgets;
+    }
+    _wireDisposal(projectPath, widget) {
+        var _a;
+        if (!((_a = widget === null || widget === void 0 ? void 0 : widget.disposed) === null || _a === void 0 ? void 0 : _a.connect)) {
+            return;
+        }
+        widget.disposed.connect(() => {
+            var _a;
+            if (((_a = this._byProject.get(projectPath)) === null || _a === void 0 ? void 0 : _a.widget) === widget) {
+                this._byProject.delete(projectPath);
+            }
+        });
+    }
+    _key(projectPath, sessionId) {
+        return `${projectPath}\n${sessionId !== null && sessionId !== void 0 ? sessionId : ''}`;
+    }
+}