jupyterlab_ai_code_assistants_extension 0.6.15

package/src/core/types.ts

@@ -0,0 +1,305 @@
+// Shared vocabulary of the provider core. Nothing here names an assistant:
+// every divergence between the registered providers is expressed as a
+// capability flag on the descriptor, or as an optional hook the provider
+// module supplies. Adding an assistant adds a descriptor, never a branch in
+// core code.
+
+/** How a conversation is branched.
+ *
+ * - `native-flag` - the CLI forks in-process from a flag pair, and the new
+ *   conversation id is minted by the frontend, so the launch carries it and
+ *   the branch is watched for until its store entry materialises
+ * - `native-command` - the CLI owns the fork verb AND mints the id itself, so
+ *   the id has to be discovered by diffing the branch list after launch
+ * - `server-copy` - the CLI has no fork at all; the server copies the store
+ *   entry, answers with the new id, and the launch resumes that id
+ */
+export type ForkStrategy = 'native-flag' | 'native-command' | 'server-copy';
+
+/** Where a conversation's DEFAULT tab tint comes from. A user-set colour in
+ * the extension's own write-back store always wins over all three. */
+export type ColourSource = 'native' | 'derived' | 'none';
+
+/** Who owns a branched conversation's name.
+ *
+ * - `launch-flag` - the CLI is told the name at launch and stamps it itself
+ * - `server-side` - the server writes the name into the copied store entry
+ * - `none` - the assistant has no naming surface, so no name is asked for
+ */
+export type NamingStrategy = 'launch-flag' | 'server-side' | 'none';
+
+/** One launch-behaviour setting of an assistant, in that assistant's own
+ * terminology. `boolean` modes are the unsafe/skip-approval switches: they get
+ * a settings toggle (off by default) AND a context-menu launch variant.
+ * `enum` modes are settings-only choices passed through on every launch. */
+export interface ILaunchMode {
+  /** Settings key under `providers.<id>.` and launch-payload key. Uses the
+   * assistant's own terminology, never a normalised core name. */
+  id: string;
+  /** Settings title shown in the JupyterLab settings editor. */
+  title: string;
+  /** Settings description. */
+  description: string;
+  kind: 'boolean' | 'enum';
+  /** Allowed values, `enum` modes only. */
+  values?: string[];
+  /** Default value. Boolean modes default to `false` without exception. */
+  default: boolean | string;
+  /** Menu label for the launch variant this mode produces, e.g.
+   * `Skip Permissions`. Boolean modes only; absent means settings-only. */
+  menuLabel?: string;
+}
+
+/** Everything the core needs to know about one assistant. Pure data - no
+ * JupyterLab imports - so the settings-schema generator can read it under
+ * plain Node from the compiled barrel. */
+export interface IProviderDescriptor {
+  /** Stable id. Drives the route namespace, widget id, command namespace,
+   * settings keys and localStorage keys. */
+  id: string;
+  /** Display label, e.g. used in settings and dialogs. */
+  label: string;
+  /** Panel title and tab caption. */
+  panelTitle: string;
+  /** LabIcon name for the panel icon. Registered by the core registry. */
+  iconName: string;
+  /** SVG source for that icon. Kept as a string so the descriptor carries no
+   * JupyterLab dependency; the registry builds the LabIcon. */
+  iconSvg: string;
+  /** Binary probed on PATH server-side. Absence disables this provider only. */
+  cliBinary: string;
+  forkStrategy: ForkStrategy;
+  colourSource: ColourSource;
+  namingStrategy: NamingStrategy;
+  /** The CLI starts a brand-new conversation under an id we give it, so a
+   * fresh session is identifiable from its argv on the first poll instead of
+   * being an unknown terminal until it writes its store entry. Independent of
+   * `forkStrategy` - an assistant can accept an id for a new session and still
+   * have no fork verb at all. */
+  mintsNewSessionId: boolean;
+  launchModes: ILaunchMode[];
+  /** Sessions can be held under remote control - renders the indicator dot. */
+  hasRemoteControl: boolean;
+  /** Sessions can be owned by a live background agent - renders the chip and
+   * asks the branch endpoint for agent state. */
+  hasBgAgents: boolean;
+  /** Projects can show a live-process indicator. */
+  hasLiveProcess: boolean;
+  /** JupyterLab plugin id of the retired standalone extension this provider
+   * replaces, without the `:plugin` suffix. Present only for a provider that
+   * had one: if that plugin is still installed the core suppresses this
+   * provider's panel rather than docking a second one for the same assistant.
+   */
+  legacyPluginId?: string;
+}
+
+/** One project row. Fields past `extra_sessions` are capability-gated: a
+ * provider whose descriptor does not claim the capability simply omits them,
+ * and the panel renders nothing for them. */
+export interface ISession {
+  project_path: string;
+  /** The provider's own project key. Opaque to the core - it is only ever
+   * echoed back to that provider's routes. */
+  encoded_path: string;
+  session_id: string;
+  name: string;
+  name_source: 'session' | 'basename';
+  message_count: number;
+  /** Last activity, epoch milliseconds. */
+  file_mtime: number;
+  git_branch: string | null;
+  favourite: boolean;
+  /** Conversations of this project beyond the current one. */
+  extra_sessions: number;
+  summary?: string;
+  first_prompt?: string;
+  created?: string | number | null;
+  modified?: string | number | null;
+  /** The conversation's own colour, for `colourSource: 'native'` providers.
+   * One of the six colour ids, or null. */
+  colour?: string | null;
+  /** Remote control is active on this conversation (`hasRemoteControl`). */
+  remote_control?: boolean;
+  /** Short id of the live background agent holding this conversation
+   * (`hasBgAgents`), or null. Display only - the server picks the launch verb
+   * itself, where it cannot be stale. */
+  bg_id?: string | null;
+  /** A process of this assistant is running in this project
+   * (`hasLiveProcess`). */
+  live?: boolean;
+  /** Model the conversation last ran on, when the store records one. */
+  model?: string | null;
+  tokens_used?: number;
+}
+
+export interface ISessionsListResponse {
+  sessions: ISession[];
+}
+
+/** One registered provider as the server sees it. */
+export interface IProviderStatus {
+  id: string;
+  label: string;
+  /** The `providers.<id>.enabled` setting as the server last read it. */
+  enabled: boolean;
+  cli_path: string | null;
+  /** Enabled AND binary present - the only state that docks a panel. */
+  available: boolean;
+}
+
+export interface IStatusResponse {
+  root_dir: string;
+  providers: IProviderStatus[];
+  /** JupyterLab's own move-to-trash setting, read server-side, so dialogs say
+   * which of the two a click means rather than reciting both. */
+  delete_to_trash?: boolean;
+}
+
+export interface IFavouriteRequest {
+  project_path: string;
+  favourite: boolean;
+}
+
+export interface IFavouriteResponse {
+  favourites: string[];
+}
+
+/** Destructive endpoints answer with the count AND the ids that actually went,
+ * because a shortfall is not a failure: whatever was disposed of is gone, so
+ * the count has to reach the user - and only the ids named here may have their
+ * stored colour dropped, or a conversation whose deletion was refused loses its
+ * tint. */
+export interface IDisposalReport {
+  removed_count: number;
+  removed_ids: string[];
+}
+
+export type IRemoveResponse = IDisposalReport;
+
+export type ICleanupResponse = IDisposalReport;
+
+export type IDeleteSessionsResponse = IDisposalReport;
+
+export interface IBranch {
+  session_id: string;
+  file_mtime: number;
+  label: string;
+  /** Live background agent owning this branch (`hasBgAgents`), or null.
+   * Populated only when the fetch asked for it. */
+  bg_id?: string | null;
+}
+
+export interface IBranchesResponse {
+  current: string;
+  total: number;
+  branches: IBranch[];
+}
+
+export interface ISwitchResponse {
+  requested: string;
+  current: string | null;
+}
+
+export interface IForkRequest {
+  encoded_path: string;
+  session_id: string;
+  name?: string;
+}
+
+export interface IForkResponse {
+  session_id: string;
+}
+
+export interface ILaunchRequest {
+  project_path: string;
+  /** The project's store key. Carrying it arms the server's launch-time pin
+   * bookkeeping (a native-flag fork pins itself current, a new session clears
+   * a stale pin) and the session_not_found pre-flight - without it both are
+   * silently skipped. Send it whenever the session row is in hand. */
+  encoded_path?: string;
+  /** Conversation to open. Omit to start a brand-new one. */
+  session_id?: string;
+  /** Frontend-minted id for a brand-new conversation, when the CLI accepts
+   * one, so the terminal is identifiable from its argv on the first poll. */
+  new_session_id?: string;
+  /** Frontend-minted id for the fork (`forkStrategy: 'native-flag'`). */
+  fork_session_id?: string;
+  /** Parent conversation to fork from (`forkStrategy: 'native-command'`). */
+  fork_from?: string;
+  /** Name to stamp on the new conversation (`namingStrategy: 'launch-flag'`). */
+  name?: string;
+  /** The launch mode this action runs under, as one token in the assistant's
+   * own terminology: a boolean mode is its bare `ILaunchMode.id`, an enum mode
+   * is `<id>=<value>`. One token, not a set - the server maps a single mode to
+   * a single flag, and refuses any token the descriptor does not declare with
+   * 400 `mode_unsupported`. */
+  mode?: string;
+}
+
+export interface ILaunchResponse {
+  terminal_name: string;
+}
+
+/** What a terminal is running, as the server resolved it from `/proc`. */
+export interface ITerminalProbeResponse {
+  terminal_name: string;
+  /** The assistant's binary is the pty's process. */
+  running: boolean;
+  /** Conversation the running process holds, or null when unreadable. */
+  session_id?: string | null;
+  /** That conversation's own colour (`colourSource: 'native'`). */
+  colour?: string | null;
+  /** Working directories read from `/proc`, never from `PWD`. */
+  cwds?: string[];
+}
+
+/** What one provider carried over from its retired standalone extension.
+ * `keys` are settings this extension is to apply through the settings registry,
+ * which the server has no writable handle on. */
+export interface IMigratedProvider {
+  provider_id: string;
+  keys: Record<string, boolean | number | string>;
+  favourites: string[];
+}
+
+/** `POST migrate`. Idempotent - a second call reports an empty list. */
+export interface IMigrateResponse {
+  migrated: IMigratedProvider[];
+}
+
+/** The extension's own per-provider colour store: user-set tab colours keyed
+ * by conversation id. */
+export interface IColourStoreResponse {
+  colours: Record<string, string>;
+}
+
+// ------------------------------------------------------------------- hooks
+
+/** Everything a provider hook is handed about the row it is describing. */
+export interface IHookContext {
+  session: ISession;
+  descriptor: IProviderDescriptor;
+}
+
+/** Optional behaviour a provider module supplies on top of its descriptor.
+ * Every hook is optional - a provider that supplies none renders the plain
+ * shared panel. */
+export interface IProviderHooks {
+  /** Label for the primary open action, when the provider distinguishes verbs
+   * (joining a live worker is not the same as resuming a dormant store entry). */
+  resumeLabel?: (session: ISession | null) => string;
+  /** Extra lines for the row tooltip. */
+  tooltipLines?: (ctx: IHookContext) => string[];
+  /** Menu label for one branch. Defaults to `<label> (<short id>) - <time>`;
+   * a provider whose titles are written in wide scripts overrides it to bound
+   * the menu by display columns rather than by code units. */
+  branchLabel?: (branch: IBranch, shortId: string) => string;
+  /** Chip appended to a branch row in the menu and the popup. */
+  branchBadge?: (branch: IBranch) => HTMLElement | null;
+}
+
+/** What `providers/index.ts` registers: one descriptor, optionally with hooks. */
+export interface IProviderModule {
+  descriptor: IProviderDescriptor;
+  hooks?: IProviderHooks;
+}

package/src/index.ts

@@ -0,0 +1,356 @@
+import {
+  ILabShell,
+  ILayoutRestorer,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { Notification } from '@jupyterlab/apputils';
+import { IDefaultFileBrowser } from '@jupyterlab/filebrowser';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ITerminalTracker } from '@jupyterlab/terminal';
+import { IColourfulTabs } from 'jupyterlab_colourful_tab_extension';
+import { IDisposable } from '@lumino/disposable';
+
+import {
+  AssistantSessionsPanel,
+  PresentationMode,
+  commandId,
+  panelWidgetId
+} from './core/panel';
+import { LOG_PREFIX, ProviderRegistry } from './core/registry';
+import { requestAPI } from './core/request';
+import {
+  IMigrateResponse,
+  IProviderStatus,
+  IStatusResponse
+} from './core/types';
+import { PROVIDERS } from './providers';
+
+const PLUGIN_ID = 'jupyterlab_ai_code_assistants_extension:plugin';
+/** Sidebar rank, shared by every panel so they dock together. */
+const PANEL_RANK = 600;
+/** How often the server is re-asked which assistants are available, so a CLI
+ * installed while JupyterLab runs surfaces without a reload. */
+const STATUS_INTERVAL_MS = 60_000;
+
+type Sidebar = 'left' | 'right';
+
+/** One live provider: its panel and the command that refreshes it. */
+interface ILivePanel {
+  panel: AssistantSessionsPanel;
+  command: IDisposable;
+}
+
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'One side panel per AI code assistant, over a shared provider registry: sessions, favourites, branching and one-click resume in a terminal.',
+  autoStart: true,
+  requires: [ILabShell],
+  optional: [
+    ILayoutRestorer,
+    ISettingRegistry,
+    ITerminalTracker,
+    IDefaultFileBrowser,
+    IColourfulTabs
+  ],
+  activate: async (
+    app: JupyterFrontEnd,
+    labShell: ILabShell,
+    restorer: ILayoutRestorer | null,
+    settingRegistry: ISettingRegistry | null,
+    terminalTracker: ITerminalTracker | null,
+    fileBrowser: IDefaultFileBrowser | null,
+    colourfulTabs: IColourfulTabs | null
+  ) => {
+    console.log(
+      'JupyterLab extension jupyterlab_ai_code_assistants_extension is activated!'
+    );
+
+    // A duplicate id throws here, at registration, rather than surfacing later
+    // as two panels quietly fighting over one widget id.
+    const registry = new ProviderRegistry(PROVIDERS);
+
+    const serverSettings = app.serviceManager.serverSettings;
+    const live = new Map<string, ILivePanel>();
+    const warnedUnknown = new Set<string>();
+    const warnedUnavailable = new Set<string>();
+
+    // Assistants whose retired standalone extension is STILL installed. This
+    // extension supersedes those three, and running both would give the user
+    // two panels and two command sets for one assistant - so the duplicate is
+    // resolved in favour of the standalone one already on screen and this
+    // provider stays dark: never started, so it never polls and never registers
+    // a command. Resolved once, at activation: a plugin cannot be installed
+    // into a running JupyterLab.
+    const suppressed = new Set<string>();
+    for (const descriptor of registry.descriptors) {
+      if (
+        descriptor.legacyPluginId &&
+        app.hasPlugin(`${descriptor.legacyPluginId}:plugin`)
+      ) {
+        suppressed.add(descriptor.id);
+      }
+    }
+    if (suppressed.size > 0) {
+      const packages = registry.descriptors
+        .filter(d => suppressed.has(d.id))
+        .map(d => d.legacyPluginId)
+        .join(', ');
+      console.warn(
+        `${LOG_PREFIX} superseded extension(s) still installed: ${packages}. Their assistants are suppressed here.`
+      );
+      // Once, not on every refresh: this runs a single time per page load.
+      Notification.warning(
+        `AI Code Assistants: uninstall ${packages} - it is superseded by this extension, and until it goes its assistant has no panel here.`,
+        { autoClose: false }
+      );
+    }
+
+    let status: IStatusResponse | null = null;
+    let settings: ISettingRegistry.ISettings | null = null;
+    let sidebar: Sidebar = 'right';
+
+    /** Ask the server which providers exist and which of their binaries are on
+     * PATH. A failure leaves the extension activated with no panels - never a
+     * dialog, and never a thrown activation. */
+    const probeStatus = async (): Promise<void> => {
+      try {
+        status = await requestAPI<IStatusResponse>('status', serverSettings, {
+          cache: 'no-store'
+        });
+      } catch (err) {
+        console.warn(
+          `${LOG_PREFIX} status probe failed; no assistant panels will be docked.`,
+          err
+        );
+        status = null;
+      }
+    };
+
+    const statusFor = (id: string): IProviderStatus | null =>
+      status?.providers?.find(p => p.id === id) ?? null;
+
+    /** Settings value, or the fallback when settings are unavailable or the
+     * key is absent. An absent enable key reads as enabled - only an explicit
+     * `false` turns a provider off. */
+    const setting = <T>(key: string, fallback: T): T => {
+      if (!settings) {
+        return fallback;
+      }
+      const value = settings.get(key).composite;
+      if (value === undefined || value === null) {
+        return fallback;
+      }
+      return value as unknown as T;
+    };
+
+    /** Launch-mode values for one provider, keyed by the mode ids the
+     * assistant itself uses. */
+    const modesFor = (id: string): Record<string, boolean | string> => {
+      const descriptor = registry.get(id)?.descriptor;
+      const modes: Record<string, boolean | string> = {};
+      for (const mode of descriptor?.launchModes ?? []) {
+        modes[mode.id] = setting(`providers.${id}.${mode.id}`, mode.default);
+      }
+      return modes;
+    };
+
+    /** Push the shared settings into one panel. */
+    const applySharedSettings = (panel: AssistantSessionsPanel): void => {
+      // Any value other than `path` is treated as `name`, so an older saved
+      // value still maps onto a live mode.
+      const mode: PresentationMode =
+        setting<string>('presentationMode', 'name') === 'path'
+          ? 'path'
+          : 'name';
+      panel.setPresentationMode(mode);
+      const limit = setting<number>('recentLimit', 10);
+      if (typeof limit === 'number') {
+        panel.setRecentLimit(limit);
+      }
+      // Defaults ON, so only an explicit `false` turns it off.
+      panel.setColouredTabs(setting<boolean>('colouredTabs', true) !== false);
+      panel.setModes(modesFor(panel.descriptor.id));
+    };
+
+    const dock = (panel: AssistantSessionsPanel): void => {
+      // Lumino re-parents cleanly when add() is called against a different
+      // area, so the same call both docks and moves.
+      labShell.add(panel, sidebar, { rank: PANEL_RANK });
+    };
+
+    const start = (id: string): void => {
+      const module = registry.get(id);
+      if (!module || live.has(id)) {
+        return;
+      }
+      try {
+        const panel = new AssistantSessionsPanel({
+          app,
+          descriptor: module.descriptor,
+          hooks: module.hooks,
+          rootDir: status?.root_dir ?? '',
+          deleteToTrash: status?.delete_to_trash !== false,
+          terminalTracker,
+          fileBrowser,
+          colourfulTabs
+        });
+        applySharedSettings(panel);
+        dock(panel);
+        // Each panel registers under its own name, so its open/closed state
+        // survives a reload independently of the others.
+        restorer?.add(panel, panelWidgetId(id));
+        const command = app.commands.addCommand(commandId(id, 'refresh'), {
+          label: `Refresh ${module.descriptor.panelTitle}`,
+          execute: () => panel.refresh()
+        });
+        live.set(id, { panel, command });
+      } catch (err) {
+        // One provider failing to start must leave the others working.
+        console.error(`${LOG_PREFIX} provider "${id}" failed to start.`, err);
+      }
+    };
+
+    const stop = (id: string): void => {
+      const entry = live.get(id);
+      if (!entry) {
+        return;
+      }
+      live.delete(id);
+      // Disposing stops the polling and clears this provider's tab tints; the
+      // terminals it launched keep running, untouched.
+      entry.command.dispose();
+      entry.panel.dispose();
+    };
+
+    /** Bring the docked panels in line with settings and CLI availability.
+     * Both must hold for a panel to be present. */
+    const reconcile = (): void => {
+      for (const descriptor of registry.descriptors) {
+        const id = descriptor.id;
+        if (suppressed.has(id)) {
+          continue;
+        }
+        const enabled =
+          setting<boolean>(`providers.${id}.enabled`, true) !== false;
+        const probe = statusFor(id);
+        const available = probe ? probe.available !== false : false;
+        // Enabled but binary absent must not be a silent state: the user sees
+        // a missing panel with no clue that PATH under the Jupyter server
+        // differs from their shell. Once per id, not per reconcile.
+        if (enabled && !available && !warnedUnavailable.has(id)) {
+          warnedUnavailable.add(id);
+          const binary = registry.get(id)?.descriptor.cliBinary ?? id;
+          console.info(
+            `${LOG_PREFIX} "${id}" is enabled but its \`${binary}\` binary was not found on the server's PATH; panel not shown.`
+          );
+        }
+        if (enabled && available) {
+          if (live.has(id)) {
+            applySharedSettings(live.get(id)!.panel);
+          } else {
+            start(id);
+          }
+        } else {
+          stop(id);
+        }
+      }
+      // A provider still named in saved settings but no longer registered is
+      // inert. Warned once per id, not once per reconcile - this runs on every
+      // status poll, and a warning that repeats forever is noise.
+      for (const key of settings ? Object.keys(settings.composite) : []) {
+        const match = /^providers\.([^.]+)\.enabled$/.exec(key);
+        if (match && !registry.has(match[1]) && !warnedUnknown.has(match[1])) {
+          warnedUnknown.add(match[1]);
+          console.warn(
+            `${LOG_PREFIX} settings name unknown assistant "${match[1]}" - ignored.`
+          );
+        }
+      }
+    };
+
+    /** Carry favourites and settings over from the retired standalone
+     * extensions, once, before the first panel is docked.
+     *
+     * The server writes the favourites itself and hands back the mapped
+     * settings keys, because it has no writable handle on the settings
+     * registry. It is idempotent - a provider is marked migrated and skipped
+     * forever after - so calling it on every activation costs one request and
+     * migrates nothing the second time. A failure is a warning and nothing
+     * more: losing a carried-over favourite must never cost the user a panel.
+     *
+     * Skipped entirely while the settings registry is unavailable: the server
+     * marks a provider migrated in the same call that HANDS BACK its settings
+     * keys, so migrating with nowhere to apply them would drop a carried-over
+     * value permanently - the marker blocks every retry.
+     */
+    const migrate = async (): Promise<void> => {
+      if (!settings) {
+        return;
+      }
+      try {
+        const result = await requestAPI<IMigrateResponse>(
+          'migrate',
+          serverSettings,
+          { method: 'POST', body: '{}' }
+        );
+        for (const entry of result.migrated ?? []) {
+          for (const [key, value] of Object.entries(entry.keys ?? {})) {
+            await settings?.set(key, value as any);
+          }
+        }
+      } catch (err) {
+        console.warn(
+          `${LOG_PREFIX} migration from the retired extensions failed; nothing was carried over.`,
+          err
+        );
+      }
+    };
+
+    const applySidebar = (): void => {
+      const next = setting<string>('sidebar', 'right');
+      if ((next === 'left' || next === 'right') && next !== sidebar) {
+        sidebar = next;
+        live.forEach(entry => dock(entry.panel));
+      }
+    };
+
+    await probeStatus();
+
+    if (settingRegistry) {
+      try {
+        settings = await settingRegistry.load(PLUGIN_ID);
+        sidebar =
+          setting<string>('sidebar', 'right') === 'left' ? 'left' : 'right';
+        settings.changed.connect(() => {
+          applySidebar();
+          reconcile();
+        });
+      } catch (err) {
+        // Defaults apply: every provider enabled, right sidebar.
+        console.warn(
+          `${LOG_PREFIX} failed to load settings; using defaults.`,
+          err
+        );
+        settings = null;
+      }
+    }
+
+    await migrate();
+
+    reconcile();
+
+    // Re-probe on a slow cadence so a binary installed (or removed) while
+    // JupyterLab runs takes effect on the next refresh, without a reload.
+    window.setInterval(() => {
+      void probeStatus().then(reconcile);
+    }, STATUS_INTERVAL_MS);
+
+    console.log(
+      `${LOG_PREFIX} ${live.size} of ${registry.ids.length} assistant panel(s) docked.`
+    );
+  }
+};
+
+export default plugin;