@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/loop/plugins/document-view/index.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `@datalayer/loop-plugin-document-view` — the document, one click away.
+ *
+ * The footer icon that opens the document beside the conversation. It shows
+ * only while a document is actually contributed, and requires the
+ * input-prompt plugin, whose footer the icon sits in.
+ *
+ * @module loop/plugins/document-view
+ */
+import { FileIcon } from '@primer/octicons-react';
+import { defineViewPlugin } from '../view-switch';
+export const DOCUMENT_VIEW_PLUGIN_NAME = '@datalayer/loop-plugin-document-view';
+export const DocumentViewPlugin = defineViewPlugin({
+    key: 'document',
+    viewId: 'document',
+    displayName: 'Document view',
+    description: 'The document beside the chat, from the composer footer.',
+    icon: FileIcon,
+    tooltip: 'Show the document',
+    octicon: 'file',
+    emoji: '\u{1F4C4}',
+    order: 12,
+});
+export default DocumentViewPlugin;

package/lib/loop/plugins/graph/GraphToggle.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The button that opens the plugin graph, and closes it again.
+ *
+ * It belongs to the graph plugin rather than to the sidebar that renders it.
+ * The sidebar used to draw it and had to ask, by name, whether a graph view
+ * was mounted before showing it — which is a panel knowing about a plugin.
+ * Contributed here, the button simply goes when the plugin does.
+ *
+ * @module loop/plugins/graph/GraphToggle
+ */
+import type { JSX } from 'react';
+import type { LoopWorkspaceContext } from '../../core';
+export type GraphToggleProps = {
+    /** The workspace, so the button can move it to the graph and back. */
+    workspace?: LoopWorkspaceContext;
+};
+export default function GraphToggle({ workspace, }: GraphToggleProps): JSX.Element | null;

package/lib/loop/plugins/graph/GraphToggle.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { Button } from '@primer/react';
+import { GRAPH_VIEW_TYPE } from './viewType';
+export default function GraphToggle({ workspace, }) {
+    // Where to go back to. Remembered rather than assumed: "back" should return
+    // to what the person was looking at, not to whichever view happens to be
+    // first.
+    const previous = useRef('');
+    if (!workspace) {
+        return null;
+    }
+    const onGraph = workspace.activeViewType === GRAPH_VIEW_TYPE;
+    return (_jsx(Button, { sx: { width: '100%' }, onClick: () => {
+            if (onGraph) {
+                workspace.setActiveViewType(previous.current);
+                return;
+            }
+            previous.current = workspace.activeViewType;
+            workspace.setActiveViewType(GRAPH_VIEW_TYPE);
+        }, children: onGraph ? 'Back to the workspace' : 'View plugin graph' }));
+}

package/lib/loop/plugins/graph/GraphView.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The plugin graph, as a workspace view.
+ *
+ * `@datalayer/reactor-graph` is generic and knows nothing about a workspace: it
+ * fills a `graph` slot and reads the platform it is rendered inside. This is
+ * the twenty lines that put that slot where the workspace shows things — a
+ * view — so the graph arrives through the same door as every other surface.
+ *
+ * The backend props are left out on purpose. They are what a host knows and the
+ * graph cannot; a workspace whose server plugins are not tracked here is better
+ * drawn as the frontend platform alone than as a frontend plus a guess.
+ *
+ * @module loop/plugins/graph/GraphView
+ */
+import type { JSX } from 'react';
+export default function GraphView(): JSX.Element;

package/lib/loop/plugins/graph/GraphView.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from '@primer/react';
+import { ReactorSlot } from '@datalayer/reactor/react';
+export default function GraphView() {
+    return (_jsx(Box, { sx: { height: '100%', overflowY: 'auto', px: 4, py: 3 }, children: _jsx(ReactorSlot, { slot: "graph" }) }));
+}

package/lib/loop/plugins/graph/index.d.ts

@@ -0,0 +1,5 @@
+import type { ReactorReactOutput } from '@datalayer/reactor/react';
+export { GRAPH_VIEW_TYPE } from './viewType';
+export declare const GRAPH_PLUGIN_NAME = "@datalayer/loop-plugin-graph";
+export declare const GraphViewPlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, ReactorReactOutput>;
+export default GraphViewPlugin;

package/lib/loop/plugins/graph/index.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `@datalayer/loop-plugin-graph` — the plugin graph, as a view.
+ *
+ * A thin adapter over the reusable `@datalayer/reactor-graph`: that plugin
+ * draws the graph into a `graph` slot, and this one gives the slot a place in
+ * the workspace. Keeping them apart is what lets the graph stay generic — it
+ * is drawn the same way in a music store and in an agent workspace.
+ *
+ * @module loop/plugins/graph
+ */
+import { WorkflowIcon } from '@primer/octicons-react';
+import { configurePlugin, contribution, definePlugin, } from '@datalayer/reactor';
+import { GraphPlugin } from '@datalayer/reactor-graph';
+import { MANAGER_ACTIONS_SLOT } from '@datalayer/reactor-manager';
+import { LoopCommand, LoopViewType, } from '../../core';
+import GraphToggle from './GraphToggle';
+import { GRAPH_VIEW_TYPE } from './viewType';
+export { GRAPH_VIEW_TYPE } from './viewType';
+export const GRAPH_PLUGIN_NAME = '@datalayer/loop-plugin-graph';
+export const GraphViewPlugin = definePlugin({
+    name: GRAPH_PLUGIN_NAME,
+    displayName: 'Plugin graph',
+    description: 'Draws the plugins, their dependencies and their extension points.',
+    octicon: 'workflow',
+    emoji: '\u{1F578}',
+    /*
+     * The generic graph plugin is pulled in rather than assumed: mounting this
+     * one is enough, whether or not the host remembered the other.
+     *
+     * Its own "View the plugin graph" command is turned off, because this plugin
+     * already contributes one that works here. The generic command asks the host
+     * to route by dispatching an event; this workspace answers by setting the
+     * active view directly, and two palette entries for one action — one of them
+     * a hopeful event dispatch nothing in the loop listened for — is how the
+     * palette came to have an entry that did nothing.
+     */
+    dependencies: [configurePlugin(GraphPlugin, { registerCommand: false })],
+    /*
+     * The way in, contributed beside the view it opens.
+     *
+     * It used to be drawn by the plugins panel, which had to ask whether a graph
+     * view existed before showing it — a panel checking for a plugin it knows by
+     * name. Owning the button here means switching this plugin off takes the
+     * button with it, and the manager needs to know nothing about graphs.
+     */
+    build: () => ({
+        components: [
+            {
+                id: 'graph-toggle',
+                slot: MANAGER_ACTIONS_SLOT,
+                Component: ({ workspace }) => (_jsx(GraphToggle, { workspace: workspace })),
+            },
+        ],
+    }),
+    contributes: [
+        contribution(LoopViewType, {
+            viewType: GRAPH_VIEW_TYPE,
+            title: 'Plugin graph',
+            icon: WorkflowIcon,
+            // Last: it is about the workspace rather than part of the work.
+            order: 900,
+            load: () => import('./GraphView'),
+        }, { id: 'graph', order: 900 }),
+        contribution(LoopCommand, {
+            name: 'graph',
+            description: 'Show the plugin graph',
+            group: 'Session',
+            keybinding: 'Mod+Alt+G',
+            run: async ({ workspace }) => {
+                workspace.setActiveViewType(GRAPH_VIEW_TYPE);
+            },
+        }, { id: 'graph' }),
+    ],
+});
+export default GraphViewPlugin;

package/lib/loop/plugins/graph/viewType.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The graph view's id, on its own.
+ *
+ * Split out so the button can name the view without importing the plugin that
+ * declares it — which would be a cycle, since the plugin imports the button.
+ *
+ * @module loop/plugins/graph/viewType
+ */
+/** The view the graph plugin contributes. */
+export declare const GRAPH_VIEW_TYPE = "graph";

package/lib/loop/plugins/graph/viewType.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The graph view's id, on its own.
+ *
+ * Split out so the button can name the view without importing the plugin that
+ * declares it — which would be a cycle, since the plugin imports the button.
+ *
+ * @module loop/plugins/graph/viewType
+ */
+/** The view the graph plugin contributes. */
+export const GRAPH_VIEW_TYPE = 'graph';

package/lib/loop/plugins/input-prompt/ComposerView.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The composer, rendered from the props the chat view assembled.
+ *
+ * Plus whatever was hung on it: the `LoopPromptPanel` point takes panels for
+ * above and below the composer, and this view stacks them inside the prompt's
+ * own card — so a floating composer carries its panels with it. The page
+ * layout's current-turn panel is the first of these; the point is open to any
+ * plugin.
+ *
+ * @module loop/plugins/input-prompt/ComposerView
+ */
+import type { JSX } from 'react';
+import { type LoopChatComposerProps } from '../../core';
+export declare function ComposerView({ workspace, composer, }: LoopChatComposerProps): JSX.Element;
+export default ComposerView;

package/lib/loop/plugins/input-prompt/ComposerView.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { Box } from '@datalayer/primer-addons';
+import { useContributions } from '@datalayer/reactor/react';
+import { InputPrompt } from '../../../chat/prompt/InputPrompt';
+import { LoopPromptPanel, } from '../../core';
+function byOrder(left, right) {
+    return (left.value.order ?? 100) - (right.value.order ?? 100);
+}
+export function ComposerView({ workspace, composer, }) {
+    const panels = useContributions(LoopPromptPanel);
+    const { above, below } = useMemo(() => {
+        const sorted = [...panels].sort(byOrder);
+        return {
+            above: sorted.filter(entry => entry.value.placement === 'above'),
+            below: sorted.filter(entry => entry.value.placement !== 'above'),
+        };
+    }, [panels]);
+    const stack = (entries) => entries.length > 0 ? (_jsx(_Fragment, { children: entries.map(entry => {
+            const Panel = entry.value.Component;
+            return _jsx(Panel, { workspace: workspace }, entry.value.id);
+        }) })) : undefined;
+    return (_jsx(Box, { sx: { flex: '0 0 auto' }, children: _jsx(InputPrompt, { ...composer, leadingPanel: stack(above), trailingPanel: stack(below) }) }));
+}
+export default ComposerView;

package/lib/loop/plugins/input-prompt/index.d.ts

@@ -0,0 +1,25 @@
+export declare const INPUT_PROMPT_PLUGIN_NAME = "@datalayer/loop-plugin-input-prompt";
+/**
+ * What a host may set on the composer.
+ */
+export type InputPromptPluginConfig = {
+    /**
+     * Called once — the first time a person actually sends a message through
+     * this composer — and never again after, for the life of the mounted
+     * workspace.
+     *
+     * Typing does not count, and neither does a suggestion merely landing in
+     * the box: only a real send. This is the one place that sees every send
+     * regardless of which surface is open beside the chat, which is what
+     * makes it the right point for a host to notice "the conversation has
+     * started" rather than each editor plugin guessing at it independently.
+     *
+     * The usual reason to want it: a page that shows something *around* the
+     * workspace before the first message — an empty-state layout, a column
+     * beside it — and wants to react (give the editor the room that layout
+     * was holding, say) exactly once, when the workspace stops being empty.
+     */
+    firstPromptHook?: () => void;
+};
+export declare const InputPromptPlugin: import("@datalayer/reactor").ReactorPlugin<InputPromptPluginConfig, unknown, unknown>;
+export default InputPromptPlugin;

package/lib/loop/plugins/input-prompt/index.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense, lazy } from 'react';
+import { contribution, definePlugin } from '@datalayer/reactor';
+import { LoopChatComposer, LoopPromptPanel, } from '../../core';
+export const INPUT_PROMPT_PLUGIN_NAME = '@datalayer/loop-plugin-input-prompt';
+const LazyComposerView = lazy(() => import('./ComposerView'));
+/** The lazy boundary, so the point's consumers need no Suspense of theirs. */
+function ComposerView(props) {
+    return (_jsx(Suspense, { fallback: null, children: _jsx(LazyComposerView, { ...props }) }));
+}
+export const InputPromptPlugin = definePlugin({
+    name: INPUT_PROMPT_PLUGIN_NAME,
+    config: {},
+    displayName: 'Input Prompt',
+    description: 'The composer under (or over) the conversation.',
+    octicon: 'pencil',
+    emoji: '\u{270F}\u{FE0F}',
+    // The composer's own opening: panels hung above or below it, inside its
+    // card. Declared here so the graph shows the point before anything fills
+    // it; the page layout's current-turn panel is what normally does.
+    contributionPoints: [LoopPromptPanel],
+    contributes: [
+        contribution(LoopChatComposer, { id: 'input-prompt', Component: ComposerView }, { id: 'input-prompt' }),
+    ],
+});
+export default InputPromptPlugin;

package/lib/loop/plugins/models/index.d.ts

@@ -0,0 +1,3 @@
+export declare const MODELS_PLUGIN_NAME = "@datalayer/loop-plugin-models";
+export declare const ModelsPlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;
+export default ModelsPlugin;

package/lib/loop/plugins/models/index.js

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `@datalayer/loop-plugin-models` — which model is answering.
+ *
+ * @module loop/plugins/models
+ */
+import { contribution, definePlugin } from '@datalayer/reactor';
+import { LoopCommand } from '../../core';
+export const MODELS_PLUGIN_NAME = '@datalayer/loop-plugin-models';
+/*
+ * No header chip any more.
+ *
+ * The plugin used to put a model dropdown in the workspace header, and the
+ * prompt's footer grew one of its own — two controls choosing one model,
+ * which would eventually disagree. The footer's is the one that survives: it
+ * sits with the tools and skills that decide what the next message does, and
+ * it is on screen in every placement of the prompt, floating included.
+ */
+export const ModelsPlugin = definePlugin({
+    name: MODELS_PLUGIN_NAME,
+    displayName: 'Models',
+    description: 'Which model answers, from the agentspecs catalog.',
+    octicon: 'cpu',
+    emoji: '\u{1F9E0}',
+    contributes: [
+        contribution(LoopCommand, {
+            name: 'models',
+            aliases: ['model'],
+            description: 'Show the models available to this session',
+            group: 'Agents',
+            keybinding: 'Mod+Alt+M',
+            run: async ({ workspace }) => {
+                const response = await fetch(`${workspace.serverUrl}/api/v1/configure/models`);
+                if (!response.ok) {
+                    return { content: 'The model catalogue is unavailable.' };
+                }
+                const payload = await response.json();
+                const reachable = (payload.models ?? []).filter((model) => model.available !== false).length;
+                return {
+                    content: `${reachable} of ${(payload.models ?? []).length} models are ready. Pick one under the prompt.`,
+                };
+            },
+        }, { id: 'models' }),
+    ],
+});
+export default ModelsPlugin;

package/lib/loop/plugins/notebook/NotebookView.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The notebook view: the ephemeral notebook, bound to the sandbox the base
+ * plugin owns.
+ *
+ * @module loop/plugins/notebook/NotebookView
+ */
+import type { JSX } from 'react';
+import { type ChatSurfaceProps } from '../../core';
+export default function NotebookView({ workspace, }: ChatSurfaceProps): JSX.Element;

package/lib/loop/plugins/notebook/NotebookView.js

@@ -0,0 +1,189 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from 'react';
+import { useContributions, useSignalValue } from '@datalayer/reactor/react';
+import { Box, Text } from '@primer/react';
+import { EphemeralNotebook } from '../../../chat/notebook/EphemeralNotebook';
+import { LoopNotebookToolbar, LoopNotebookToolbarItem, LoopOpeningNotebook, } from '../../core';
+import { useEditorToolbar } from '../../core/toolbar';
+import { openingCode, openingNotebook } from './openingNotebook';
+import { useSandboxService } from '../agents';
+export default function NotebookView({ workspace, }) {
+    const service = useSandboxService();
+    const snapshot = useSignalValue(service.snapshot);
+    // Named once: it identifies the notebook to its store, and it is what a
+    // toolbar item is handed so it can report on *this* notebook.
+    const notebookId = workspace.surfaceId;
+    // The toolbar is not this view's to draw. It offers the point, and a plugin
+    // provides the bar; with that plugin switched off there is no toolbar here
+    // at all, not an empty one. Items come from whoever adds to it — the toolbar
+    // plugin's kernel light, the chat's agent actions — and this view names none
+    // of them. It used to hardcode two buttons that submitted prompts, which
+    // meant the notebook knew about the chat.
+    const toolbar = useEditorToolbar(LoopNotebookToolbar, LoopNotebookToolbarItem, {
+        workspace,
+        editorId: notebookId,
+    });
+    /*
+     * One document per mount, built before anything can return.
+     *
+     * `EphemeralNotebook` holds on to the object it is first handed and edits it
+     * in place, so a shared literal would be a shared notebook — hence the memo.
+     * It sits up here with the other hooks because the guard below returns
+     * early, and a hook after an early return runs on some renders and not
+     * others, which is the one thing React cannot tolerate.
+     */
+    /*
+     * A host's own opening notebook wins over the plugin's one cell.
+     *
+     * Read from the `LoopOpeningNotebook` point: a page whose argument needs
+     * several cells and an output in the first viewport contributes them, and
+     * this view opens on that instead. First contribution wins. What to run so
+     * the kernel agrees with the cells comes with it, or is the code cells'
+     * own source joined top to bottom.
+     */
+    const openingEntries = useContributions(LoopOpeningNotebook);
+    const contributedOpening = openingEntries[0]?.value;
+    const opening = useMemo(() => contributedOpening ? contributedOpening.notebook() : openingNotebook(), [contributedOpening]);
+    const primeCode = useMemo(() => {
+        if (!contributedOpening) {
+            return openingCode();
+        }
+        if (contributedOpening.prime !== undefined) {
+            return contributedOpening.prime;
+        }
+        return opening.cells
+            .filter(cell => cell.cell_type === 'code')
+            .map(cell => Array.isArray(cell.source) ? cell.source.join('') : cell.source)
+            .join('\n');
+    }, [contributedOpening, opening]);
+    /*
+     * Run the opening cell on the sandbox, once it has one.
+     *
+     * The notebook opens showing that cell as already executed — `[1]`, with its
+     * frame printed underneath — and until this runs, that is a picture of a
+     * session rather than one: `sales` is on screen and undefined, so the first
+     * thing the agent or the reader does with it raises `NameError`. Executing
+     * the same source the cell displays makes the kernel agree with the page.
+     *
+     * Through the sandbox service rather than the notebook's own run command,
+     * because the two share a kernel and only one of them exists this early: the
+     * service is ready the moment the sandbox is, while the notebook is still
+     * mounting its editor. The output goes to the service's own execution log,
+     * so the cell keeps the result it was born with rather than gaining a second
+     * copy.
+     *
+     * Keyed on the kernel, so a target switch — which is a new kernel — primes
+     * the new one, and a re-render does not run it again.
+     */
+    const primed = useRef(null);
+    useEffect(() => {
+        const kernelId = snapshot.kernelId;
+        if (snapshot.state !== 'running' || !kernelId) {
+            return;
+        }
+        if (primed.current === kernelId) {
+            return;
+        }
+        primed.current = kernelId;
+        void service.execute(primeCode).catch((error) => {
+            // Not worth a banner. The notebook still shows what it showed; what a
+            // reader loses is the variable, and the agent will say so plainly the
+            // first time it looks.
+            console.warn('[loop] could not prime the opening cell', error);
+        });
+    }, [service, snapshot.state, snapshot.kernelId, primeCode]);
+    // The switcher's `canOpen` gate should have kept this view shut, but a
+    // sandbox can go away while it is on screen — say so rather than rendering a
+    // notebook wired to nothing.
+    if (snapshot.state !== 'running') {
+        return (_jsx(Box, { sx: {
+                height: '100%',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                color: 'fg.muted',
+                fontSize: 1,
+                px: 4,
+                textAlign: 'center',
+            }, children: _jsx(Text, { children: "The notebook needs a running sandbox. Open the Sandbox view to see what it is doing." }) }));
+    }
+    // A browser sandbox already owns its kernel; binding to that manager is what
+    // puts the agent's executions and the reader's cells in the same one. A
+    // server sandbox is reached by URL, as before, and returns null here.
+    const browserManager = service.getServiceManager() ??
+        undefined;
+    return (_jsx(Box, { sx: {
+            height: '100%',
+            minHeight: 0,
+            /*
+              A height for the Lumino widgets, forced.
+    
+              WORKAROUND, and knowingly a blunt one. The notebook renders inside a
+              chain of Lumino widgets — `.jp-NotebookPanel` holds `.jp-Notebook`,
+              which is absolutely positioned and therefore sized entirely by its
+              parent. Lumino sets those sizes itself, from a resize it expects to
+              be told about; when that message does not arrive, or arrives before
+              the panel has a box of its own, the parent measures zero and the
+              absolutely positioned notebook inside it has nothing to fill. The
+              cells are in the DOM the whole time. Nothing is on screen.
+    
+              It is intermittent, which is what makes it worth a hack: measured
+              side by side on a good load, every element here — panel, notebook,
+              cell, editor — has exactly the geometry it has locally, so there is
+              no wrong number to correct, only a number that sometimes never
+              arrives. Declaring it in CSS means the browser resolves it on layout
+              whether or not Lumino ever says anything.
+    
+              `!important` because Lumino writes its own inline sizes and would
+              otherwise win. Scoped to this view, so it is the LOOP workspace's
+              notebook that is pinned and not every notebook in the package — the
+              real fix belongs in the widget layer, and this must not make that
+              harder to find.
+            */
+            '& .jp-NotebookPanel': {
+                height: '100% !important',
+                minHeight: 0,
+            },
+            /* The panel is the only thing between the flex column above and the
+               absolutely positioned notebook below, so it has to be a box that
+               fills rather than one that wraps its content. */
+            '& .dla-Box-Notebook': {
+                display: 'flex',
+                flexDirection: 'column',
+                minHeight: 0,
+            },
+        }, children: _jsx(EphemeralNotebook
+        /*
+          Opened on a small analysis that has already run, not on a blank cell.
+
+          Every opener this agent offers refers to "this notebook" — analyze
+          this dataset, find the anomalies, plot revenue by region — and
+          against an empty document those are questions with no answer. Built
+          once per mount: the notebook component keeps the object it is given
+          and edits it in place.
+        */
+        , { 
+            /*
+              Opened on a small analysis that has already run, not on a blank cell.
+    
+              Every opener this agent offers refers to "this notebook" — analyze
+              this dataset, find the anomalies, plot revenue by region — and
+              against an empty document those are questions with no answer. Built
+              once per mount: the notebook component keeps the object it is given
+              and edits it in place.
+            */
+            nbformat: opening, 
+            // The entry point owns the theme; a second provider here would fight
+            // it over BaseStyles and font tokens (§3.5, §3.6).
+            inheritTheme: true, notebookId: notebookId, serviceManager: browserManager, 
+            // Join the sandbox's kernel rather than starting a rival one.
+            kernelId: browserManager ? snapshot.kernelId : undefined, showToolbar: toolbar.present, toolbarExtraItems: toolbar.items, runtimeOverride: !browserManager && snapshot.jupyterUrl
+                ? {
+                    baseUrl: snapshot.jupyterUrl,
+                    // Without the token the server refuses every request and the
+                    // cell runs into silence — no kernel, no output, no error the
+                    // reader can act on.
+                    token: snapshot.jupyterToken,
+                }
+                : undefined }) }));
+}

package/lib/loop/plugins/notebook/index.d.ts

@@ -0,0 +1,3 @@
+export declare const NOTEBOOK_PLUGIN_NAME = "@datalayer/loop-plugin-notebook";
+export declare const NotebookPlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;
+export default NotebookPlugin;

package/lib/loop/plugins/notebook/index.js

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `@datalayer/loop-plugin-notebook` — a notebook editor, beside the chat.
+ *
+ * Contributed to the chat rather than to the workspace: a notebook is what the
+ * conversation is about, and a person reading a reply wants the cell it just
+ * changed in view, not one tab away.
+ *
+ * It declares the sandbox plugin as a dependency, which is the point: the
+ * relationship is in the extension graph rather than in prose, and the reactor
+ * pulls the base plugin in whether or not the host remembered to mount it.
+ *
+ * @module loop/plugins/notebook
+ */
+import { RowsIcon } from '@primer/octicons-react';
+import { contribution, definePlugin } from '@datalayer/reactor';
+import { LoopCommand, LoopEditorView, LoopFrontendTool, LoopOpeningNotebook, requestSurface, LoopNotebookToolbar, } from '../../core';
+import { AgentsPlugin } from '../agents';
+export const NOTEBOOK_PLUGIN_NAME = '@datalayer/loop-plugin-notebook';
+export const NotebookPlugin = definePlugin({
+    name: NOTEBOOK_PLUGIN_NAME,
+    displayName: 'Notebook editor',
+    description: 'A notebook beside the chat, on the session\u2019s kernel.',
+    octicon: 'rows',
+    emoji: '\u{1F4D3}',
+    // The sandbox is a hard dependency: a notebook with no kernel is a text
+    // file. The shell and the chat are extended through their points instead —
+    // a dependency would take this plugin down with them, and unticking the
+    // chat must leave the notebook standing.
+    dependencies: [AgentsPlugin],
+    // Declared, not merely used: the registry knows who contributed to a
+    // point, it cannot know who opened it. Declaring it is also what makes
+    // the notebook toolbar visible on the plugin graph before anything has
+    // filled it — which is exactly when knowing it exists is most useful.
+    // And the opening notebook: what the editor holds before anyone types. The
+    // plugin ships one cell with a result; a host whose argument needs several
+    // contributes its own, and the view opens on that instead.
+    contributionPoints: [LoopNotebookToolbar, LoopOpeningNotebook],
+    contributes: [
+        // The editor: one entry in the shell's segmented control, one view in
+        // the editor column.
+        contribution(LoopEditorView, {
+            surfaceId: 'notebook',
+            title: 'Notebook',
+            icon: RowsIcon,
+            order: 10,
+            canOpen: workspace => workspace.sandbox.state === 'running',
+            unavailableReason: () => 'Needs a running sandbox',
+            load: () => import('./NotebookView'),
+        }, { id: 'notebook', order: 10 }),
+        contribution(LoopCommand, {
+            name: 'notebook',
+            description: 'Open the notebook beside the chat',
+            group: 'Open',
+            keybinding: 'Mod+Alt+N',
+            run: async ({ workspace }) => {
+                // The chat first, because the surface lives beside it; then the
+                // surface itself. Switching the view alone leaves whichever surface
+                // was already open, so on the chat view — where a reader usually is
+                // — this used to do nothing at all.
+                workspace.setActiveViewType('chat');
+                if (!requestSurface('notebook')) {
+                    throw new Error('No chat is on screen to open the notebook beside.');
+                }
+            },
+        }, { id: 'notebook' }),
+    ],
+    build: ctx => {
+        /*
+         * The tools — what lets the agent create, edit and run cells —
+         * contributed when their module arrives. `notebookHooks` imports
+         * `@datalayer/jupyter-react` at module load, which is most of Jupyter's
+         * frontend; a static contribution would put that whole graph in front
+         * of the shell's first paint. The reactor takes contributions at any
+         * time and bumps its revision, so the chat re-reads its tools point
+         * the moment these land — the same arrangement as the document's
+         * lexical tools.
+         */
+        void import('../../../tools/adapters/agent-runtimes/notebookHooks').then(({ createNotebookTools }) => {
+            ctx.contribute(LoopFrontendTool, {
+                id: 'notebook-tools',
+                tools: workspace => createNotebookTools(workspace.surfaceId),
+            }, { id: 'notebook-tools' });
+        });
+        return {};
+    },
+});
+export default NotebookPlugin;