@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/jupyter/serverExecution.js

@@ -0,0 +1,258 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { CodeCell } from '@jupyterlab/cells';
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+import { getServerExecutionMetadata, isClientOwnedExecution, setServerExecutionMetadata, } from '@datalayer/jupyter-server-nbmodel/lib/executionMetadata';
+import { NotebookCellServerExecutor, resumeCellServerExecution, } from '@datalayer/jupyter-server-nbmodel/lib/executor';
+/**
+ * The route `jupyter-server-nbmodel` answers on.
+ *
+ * It reports the executions the server holds for a kernel, and it answers
+ * for any identifier — the nil one included, so no kernel has to exist to
+ * learn whether the extension is installed. A server without it says 404.
+ */
+const NBMODEL_PROBE = 'api/kernels/00000000-0000-0000-0000-000000000000/execute';
+/** What a server said when asked, by the address it was asked at. */
+const installed = new Map();
+/**
+ * Whether the server at these settings runs cells on the server.
+ *
+ * Asked once per server and remembered, including the answer "no": the
+ * question is asked on the way to running a cell, and a cell must not wait
+ * on a round trip every time. A server that could not be reached is not
+ * remembered, so a sandbox still starting is asked again next time.
+ */
+export function hasServerExecution(settings) {
+    const key = settings.baseUrl;
+    const known = installed.get(key);
+    if (known) {
+        return known;
+    }
+    const asked = ServerConnection.makeRequest(URLExt.join(settings.baseUrl, NBMODEL_PROBE), { method: 'GET' }, settings)
+        .then(response => response.ok)
+        .catch(reason => {
+        installed.delete(key);
+        console.warn(`[agent-runtimes] Could not ask ${settings.baseUrl} whether it runs cells on the server.`, reason);
+        return false;
+    });
+    installed.set(key, asked);
+    return asked;
+}
+/** The executors built so far, one per server and credential. */
+const executors = new Map();
+/**
+ * The executor to run a cell of this session through, if its server has one.
+ *
+ * Bound to the server of the session's KERNEL — the sandbox pod — which is
+ * where the REST endpoint lives and where the request is then kept; the
+ * executor of the lab extension is bound to the application's own server,
+ * which is not that one and, on the SaaS, is not at all.
+ *
+ * `null` when the session has no kernel yet, or its server does not run
+ * cells: the caller then executes over the kernel connection as before.
+ */
+export async function serverExecutorFor(sessionContext) {
+    const settings = sessionContext?.session?.kernel?.serverSettings;
+    if (!settings?.baseUrl) {
+        return null;
+    }
+    if (!(await hasServerExecution(settings))) {
+        return null;
+    }
+    // The token is part of the key: a sandbox restarted with a new one must
+    // not be posted to with the old.
+    const key = `${settings.baseUrl}#${settings.token}`;
+    let executor = executors.get(key);
+    if (!executor) {
+        executor = new NotebookCellServerExecutor({ serverSettings: settings });
+        executors.set(key, executor);
+    }
+    return executor;
+}
+/** The requests already picked up, so two sweeps never poll one twice. */
+const resumed = new Set();
+/**
+ * The absolute address of a recorded request, on the server that holds it.
+ *
+ * The server names the request by a path relative to its own base, and that
+ * is what the cell remembers; joined here to the base of the server being
+ * asked. An address recorded in full is kept when it already names that
+ * server, and reduced to its path otherwise — a pod reached through an
+ * ingress, or the same pod under another hostname, still holds the request
+ * at the same path.
+ */
+function requestUrlOn(recorded, settings) {
+    if (recorded.startsWith(settings.baseUrl)) {
+        return recorded;
+    }
+    const path = recorded.startsWith('http')
+        ? new URL(recorded).pathname
+        : recorded;
+    return URLExt.join(settings.baseUrl, path);
+}
+/**
+ * Resume, into this cell, a request a previous page left running.
+ *
+ * @returns whether a request was taken up
+ */
+function resumeCell(cell, settings) {
+    // A request this page started is polled by the executor that started it;
+    // polling it here as well would race it for the same result.
+    if (isClientOwnedExecution(cell)) {
+        return false;
+    }
+    const execution = getServerExecutionMetadata(cell);
+    if (!execution || resumed.has(execution.requestId)) {
+        return false;
+    }
+    /*
+     * A cell that is still here when the answers arrive.
+     *
+     * The notebook rebuilds its cells when its sandbox binds — the services
+     * change under it and the model is made again — so a widget picked up a
+     * moment earlier is disposed by the time the first response lands, and
+     * writing to it throws on a model that is null.
+     */
+    if (cell.isDisposed || !cell.model) {
+        return false;
+    }
+    resumed.add(execution.requestId);
+    const requestUrl = requestUrlOn(execution.requestUrl, settings);
+    console.info('[agent-runtimes] Resuming a server execution', {
+        cellId: cell.model.sharedModel.getId(),
+        requestId: execution.requestId,
+        requestUrl,
+    });
+    void resumeCellServerExecution(cell, requestUrl, settings).catch(reason => {
+        if (cell.isDisposed) {
+            // The cell went away under the poll — the notebook was rebuilt. Let a
+            // later sweep pick the request up with the new widget.
+            resumed.delete(execution.requestId);
+            return;
+        }
+        /*
+         * Kept in `resumed`, not released.
+         *
+         * Releasing it on failure meant the next sweep tried again a second
+         * later, and the one after that: a request the server does not have
+         * produced a failing call every second for as long as the sweep ran. A
+         * request is attempted once.
+         */
+        console.warn(`[agent-runtimes] Failed to resume the execution ${execution.requestId}.`, reason);
+    });
+    return true;
+}
+/** The servers already asked for their active executions, by kernel. */
+const discovered = new Set();
+/**
+ * Ask the server which of this kernel's executions are still running, and
+ * give the cells that started them their request back.
+ *
+ * The metadata a cell carries is written once the server has accepted the
+ * request — a page refreshed in that instant, or whose persisted model
+ * missed the write, has a running cell with nothing to resume from. The
+ * server knows: it lists its active requests with the cell each was for.
+ */
+async function discoverActiveExecutions(cells, kernel, settings) {
+    const key = `${settings.baseUrl}#${kernel.id}`;
+    if (discovered.has(key)) {
+        return 0;
+    }
+    const response = await ServerConnection.makeRequest(URLExt.join(settings.baseUrl, `api/kernels/${kernel.id}/execute`), { method: 'GET' }, settings);
+    if (response.status === 404) {
+        // This server does not offer server-side execution at all — a JupyterLite
+        // kernel in the page, or a plain Jupyter server without the agent-runtimes
+        // extension. That is a permanent answer, not a hiccup, so it is recorded
+        // like a successful discovery: asking again on every sweep would fill the
+        // console with a failure that is really just a feature this server lacks.
+        discovered.add(key);
+        return 0;
+    }
+    if (!response.ok) {
+        // Not marked discovered: a server briefly unreachable, or one still
+        // starting, is asked again by the next sweep rather than never.
+        //
+        // `ResponseError.create` reads the body to build its message, and throws a
+        // `SyntaxError` of its own when there is no body — which replaces the
+        // status the caller needed with a parse error from the error path. The
+        // status is the useful part, so it survives either way.
+        throw await ServerConnection.ResponseError.create(response).catch(() => new Error(`Invalid response: ${response.status} ${response.statusText}`.trim()));
+    }
+    discovered.add(key);
+    const payload = (await response.json());
+    let restored = 0;
+    for (const execution of payload.requests ?? []) {
+        if (!execution.cell_id || resumed.has(execution.request_id)) {
+            continue;
+        }
+        const cell = cells.find(candidate => candidate.model?.sharedModel.getId() === execution.cell_id);
+        if (!cell || cell.isDisposed || getServerExecutionMetadata(cell)) {
+            continue;
+        }
+        setServerExecutionMetadata(cell, {
+            kernelId: execution.kernel_id,
+            requestId: execution.request_id,
+            requestUrl: execution.request_url,
+        });
+        restored += 1;
+    }
+    return restored;
+}
+/**
+ * Resume, once, the server executions of the cells of this notebook.
+ *
+ * @param panel The notebook panel of the editor
+ * @param settings The server the executions were posted to — the one of the
+ *   notebook's kernel
+ * @returns how many requests were taken up in this pass
+ */
+export async function resumeServerExecutions(panel) {
+    if (panel.isDisposed) {
+        return 0;
+    }
+    /*
+     * The kernel is the gate, and its server is the address.
+     *
+     * A request lives on the server of the kernel that runs it — the sandbox
+     * pod — and is read back from there. An editor that has not bound its
+     * sandbox yet stands on a placeholder service manager pointing at the
+     * application's own origin; a sweep that polled THAT would ask the wrong
+     * server, get a 404, and — because a request is attempted once — never
+     * ask the right one. So nothing is swept until the kernel is here, and
+     * everything is asked of the kernel's own server.
+     */
+    const kernel = panel.sessionContext?.session?.kernel;
+    const settings = kernel?.serverSettings;
+    if (!kernel || !settings) {
+        return 0;
+    }
+    const cells = panel.content.widgets.filter((widget) => widget instanceof CodeCell);
+    if (cells.length === 0) {
+        return 0;
+    }
+    try {
+        await discoverActiveExecutions(cells, kernel, settings);
+    }
+    catch (reason) {
+        console.warn('[agent-runtimes] Failed to discover the active executions of the kernel.', reason);
+    }
+    let taken = 0;
+    for (const cell of cells) {
+        if (resumeCell(cell, settings)) {
+            taken += 1;
+        }
+    }
+    return taken;
+}
+/**
+ * Forget what was asked and resumed — for tests, which build servers anew.
+ */
+export function resetServerExecutionState() {
+    installed.clear();
+    executors.clear();
+    resumed.clear();
+    discovered.clear();
+}

package/lib/jupyter/useResumeServerExecutions.d.ts

@@ -0,0 +1,11 @@
+import type { ServiceManager } from '@jupyterlab/services';
+/**
+ * Resume the server executions of a notebook, once it has cells.
+ *
+ * @param notebookId The notebook, as the store of Jupyter React names it
+ * @param serviceManager The services of the notebook's sandbox — the server
+ *   its cells were posted to. Nothing is done without one: there is then no
+ *   kernel, and no server to ask.
+ */
+export declare function useResumeServerExecutions(notebookId: string | undefined, serviceManager?: ServiceManager.IManager): void;
+export default useResumeServerExecutions;

package/lib/jupyter/useResumeServerExecutions.js

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Pick up, in a React notebook, the executions a previous page left running.
+ *
+ * The sweep itself is {@link resumeServerExecutions}; this is when to run it.
+ * The cells arrive with the document — a room that has to sync, a model that
+ * has to be built, a sandbox that has to bind — so there is nothing to sweep
+ * at the moment the editor mounts, and no one signal that says "now". The
+ * notebook is looked at on a short timer for a short while; each pass is
+ * cheap, reading metadata off the cells that are there, and a request is
+ * only ever taken up once.
+ *
+ * @module jupyter/useResumeServerExecutions
+ */
+import { useEffect } from 'react';
+import { notebookStore } from '@datalayer/jupyter-react';
+import { resumeServerExecutions, } from './serverExecution';
+/** How often the cells are looked at, and for how long. */
+const LOOK_EVERY_MS = 1_000;
+const LOOK_FOR_MS = 30_000;
+/**
+ * Resume the server executions of a notebook, once it has cells.
+ *
+ * @param notebookId The notebook, as the store of Jupyter React names it
+ * @param serviceManager The services of the notebook's sandbox — the server
+ *   its cells were posted to. Nothing is done without one: there is then no
+ *   kernel, and no server to ask.
+ */
+export function useResumeServerExecutions(notebookId, serviceManager) {
+    useEffect(() => {
+        if (!notebookId || !serviceManager) {
+            return;
+        }
+        let elapsed = 0;
+        const sweep = () => {
+            const adapter = notebookStore.getState().selectNotebook(notebookId)
+                ?.adapter;
+            // `panel`, not `notebookPanel`: the adapter of Jupyter React names it
+            // that way, and asking for the other one found an empty list every time.
+            const panel = adapter?.panel;
+            if (!panel || panel.isDisposed) {
+                return;
+            }
+            // The sweep waits for the kernel and asks its server; nothing to pass.
+            void resumeServerExecutions(panel);
+        };
+        sweep();
+        const timer = window.setInterval(() => {
+            elapsed += LOOK_EVERY_MS;
+            if (elapsed >= LOOK_FOR_MS) {
+                window.clearInterval(timer);
+                return;
+            }
+            sweep();
+        }, LOOK_EVERY_MS);
+        return () => {
+            window.clearInterval(timer);
+        };
+    }, [notebookId, serviceManager]);
+}
+export default useResumeServerExecutions;

package/lib/lexical/ChatInlinePlugin.d.ts

@@ -1,3 +1,36 @@
+/**
+ * ChatInlinePlugin - Lexical plugin for inline AI chat.
+ *
+ * This plugin displays a floating AI chat interface when the user triggers
+ * an AI action (via the toolbar's AI dropdown or sparkle button). It provides
+ * AI-powered text manipulation features like improve, summarize, translate, etc.
+ *
+ * IMPORTANT: This plugin no longer renders its own formatting toolbar.
+ * Instead, AI actions are registered as `extraItems` in the
+ * `FloatingTextFormatToolbarPlugin` via the `useChatInlineToolbarItems` hook.
+ *
+ * Usage:
+ * ```tsx
+ * const { toolbarItems, isAiOpen, pendingPrompt, clearPendingPrompt, closeAi } =
+ *   useChatInlineToolbarItems();
+ *
+ * <FloatingTextFormatToolbarPlugin
+ *   anchorElem={floatingAnchorElem}
+ *   setIsLinkEditMode={setIsLinkEditMode}
+ *   extraItems={toolbarItems}
+ * />
+ * <ChatInlinePlugin
+ *   protocol={protocol}
+ *   isOpen={isAiOpen}
+ *   onClose={closeAi}
+ *   pendingPrompt={pendingPrompt}
+ *   onPendingPromptConsumed={clearPendingPrompt}
+ * />
+ * ```
+ *
+ * @module lexical/ChatInlinePlugin
+ */
+import type { JSX } from 'react';
 import { type LexicalCommand } from 'lexical';
 import { type ChatInlineProtocolConfig } from '../chat/ChatInline';
 /**

package/lib/lexical/ChatInlinePlugin.js

@@ -1,40 +1,4 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-/*
- * Copyright (c) 2025-2026 Datalayer, Inc.
- * Distributed under the terms of the Modified BSD License.
- */
-/**
- * ChatInlinePlugin - Lexical plugin for inline AI chat.
- *
- * This plugin displays a floating AI chat interface when the user triggers
- * an AI action (via the toolbar's AI dropdown or sparkle button). It provides
- * AI-powered text manipulation features like improve, summarize, translate, etc.
- *
- * IMPORTANT: This plugin no longer renders its own formatting toolbar.
- * Instead, AI actions are registered as `extraItems` in the
- * `FloatingTextFormatToolbarPlugin` via the `useChatInlineToolbarItems` hook.
- *
- * Usage:
- * ```tsx
- * const { toolbarItems, isAiOpen, pendingPrompt, clearPendingPrompt, closeAi } =
- *   useChatInlineToolbarItems();
- *
- * <FloatingTextFormatToolbarPlugin
- *   anchorElem={floatingAnchorElem}
- *   setIsLinkEditMode={setIsLinkEditMode}
- *   extraItems={toolbarItems}
- * />
- * <ChatInlinePlugin
- *   protocol={protocol}
- *   isOpen={isAiOpen}
- *   onClose={closeAi}
- *   pendingPrompt={pendingPrompt}
- *   onPendingPromptConsumed={clearPendingPrompt}
- * />
- * ```
- *
- * @module lexical/ChatInlinePlugin
- */
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { createPortal } from 'react-dom';
 import { $getSelection, $isRangeSelection, $createParagraphNode, $createTextNode, TextNode, COMMAND_PRIORITY_LOW, createCommand, } from 'lexical';

package/lib/loop/core/focusRequests.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Ask the prompt to focus.
+ *
+ * @returns whether anything was listening — `false` means nothing rendering
+ *   a prompt is mounted, and the caller should say so rather than assume it
+ *   worked.
+ */
+export declare function focusPrompt(): boolean;
+/** Listen for those requests. Returns the unsubscribe. */
+export declare function onPromptFocusRequest(listener: () => void): () => void;

package/lib/loop/core/focusRequests.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Asking the prompt to take focus, from outside React.
+ *
+ * The prompt's focus lives in a DOM node the chat owns, and a command runs
+ * outside the component tree — the same gap `surfaceRequests` bridges for the
+ * editors, bridged the same way: a command asks, whatever renders the prompt
+ * answers, and nobody gains a handle on the input itself. `focusPrompt`
+ * reports whether anything was listening, so the command can say "no prompt
+ * is on screen" rather than appearing to work.
+ *
+ * In core rather than in the prompt plugin, because the listener is the chat:
+ * it renders the composer in every placement — docked, in-column, floating —
+ * and the command should reach it wherever it is.
+ *
+ * @module loop/core/focusRequests
+ */
+const listeners = new Set();
+/**
+ * Ask the prompt to focus.
+ *
+ * @returns whether anything was listening — `false` means nothing rendering
+ *   a prompt is mounted, and the caller should say so rather than assume it
+ *   worked.
+ */
+export function focusPrompt() {
+    if (listeners.size === 0) {
+        return false;
+    }
+    // Copied: a listener that unsubscribes while being told must not shorten
+    // the set being iterated.
+    for (const listener of [...listeners]) {
+        listener();
+    }
+    return true;
+}
+/** Listen for those requests. Returns the unsubscribe. */
+export function onPromptFocusRequest(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}