@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/loop/core/index.js

@@ -0,0 +1,264 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `@datalayer/loop-core` — the contracts, and nothing else.
+ *
+ * Everything the workspace can be extended with is declared here: the points
+ * plugins contribute to, and the shapes they contribute. No React, no server
+ * calls, no opinions about layout — a plugin depends on this and on the reactor,
+ * never on the shell, so the shell can be replaced (a browser page, a JupyterLab
+ * panel) without touching a single plugin.
+ *
+ * @module loop/core
+ */
+import { defineContributionPoint, defineGate } from '@datalayer/reactor';
+/**
+ * What a view reads while the sandbox plugin is absent.
+ *
+ * Every plugin that watches the sandbox has to call `useSignalValue`
+ * unconditionally — the plugin can be switched off from the sidebar, and hook
+ * order cannot depend on that — so each needs something signal-shaped to read
+ * instead. They used to declare their own, and all four made the same mistake:
+ * building the value inside `peek()`.
+ *
+ * `useSignalValue` is a `useSyncExternalStore`, so `peek()` *is* the snapshot
+ * and React compares it by identity. A fresh object per call means the snapshot
+ * never settles, and the page re-renders without bound — React says "the result
+ * of getSnapshot should be cached", and then a nested-update overflow surfaces
+ * wherever the fiftieth render happens to land, which is nowhere near here.
+ *
+ * So: one frozen value, read by every caller. Typed rather than cast, because
+ * the `as never` the four copies used is exactly what let the wrong shape
+ * through without a word from the compiler.
+ */
+export const IDLE_SANDBOX_SNAPSHOT = Object.freeze({
+    state: 'idle',
+});
+/** {@link IDLE_SANDBOX_SNAPSHOT}, shaped as a signal to be read like one. */
+export const IDLE_SANDBOX_SNAPSHOT_SIGNAL = {
+    value: IDLE_SANDBOX_SNAPSHOT,
+    peek: () => IDLE_SANDBOX_SNAPSHOT,
+};
+/**
+ * The target read while the sandbox plugin is absent.
+ *
+ * Typed as `undefined` rather than `string | undefined` so that
+ * `service?.target ?? IDLE_SANDBOX_TARGET_SIGNAL` keeps whatever the service
+ * says a target is: widening it here would quietly turn every caller's
+ * `SandboxTarget` into a bare string.
+ */
+export const IDLE_SANDBOX_TARGET_SIGNAL = {
+    value: undefined,
+    peek: () => undefined,
+};
+/**
+ * The id the workspace's surfaces are known by.
+ *
+ * One expression in one place, because three things have to agree on it: the
+ * notebook that renders, the document that renders, and the frontend tools an
+ * in-page agent is given to reach them. A tool addressed to a different id than
+ * the surface on screen edits nothing and reports success, which is the worst
+ * way for this to be wrong.
+ *
+ * Keyed on the *session*, never on the agent. Keying it on the agent meant
+ * every switch renamed the surface, and a renamed surface is a new one: the
+ * notebook remounted empty, so changing who you were talking to silently threw
+ * away the work you were talking about. The notebook belongs to the workspace;
+ * the agent is only a visitor to it.
+ */
+export function loopSurfaceId(sessionId) {
+    return `loop-${sessionId || 'default'}`;
+}
+/** Create a prompt channel. The shell owns one per workspace. */
+export function createPromptChannel() {
+    const listeners = new Set();
+    return {
+        submit(message) {
+            if (listeners.size === 0) {
+                return false;
+            }
+            for (const listener of [...listeners]) {
+                listener(message);
+            }
+            return true;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+/** Views the workspace may open. */
+export const LoopViewType = defineContributionPoint('loop.viewType');
+/** Editors the chat hosts beside the conversation. */
+/**
+ * Editors the shell hosts beside the conversation.
+ *
+ * Owned by the shell plugin, not the chat: which editors exist is a fact
+ * about the workspace, and the segmented control that offers them shows
+ * nothing at all until a plugin contributes one. The chat renders the chosen
+ * editor's column, but the choice is the shell's.
+ *
+ * `LoopChatSurface` is the same point under its historical name, kept so
+ * nothing that contributed to it has to move in the same commit.
+ */
+export const LoopEditorView = defineContributionPoint('loop.chat.surface');
+/** @deprecated Use {@link LoopEditorView}: the shell owns the point now. */
+export const LoopChatSurface = LoopEditorView;
+export const LoopFrontendTool = defineContributionPoint('loop.frontendTool');
+export const LoopChatComposer = defineContributionPoint('loop.chat.composer');
+export const LoopChatHeader = defineContributionPoint('loop.chat.header');
+export const LoopAgentBlueprint = defineContributionPoint('loop.agent.blueprint');
+export const LoopChatSuggestion = defineContributionPoint('loop.chat.suggestion');
+export const LoopChatExtras = defineContributionPoint('loop.chat.extras');
+export const LoopOpeningNotebook = defineContributionPoint('loop.notebook.opening');
+export const LoopOpeningDocument = defineContributionPoint('loop.document.opening');
+/**
+ * Whether there is anything to chat with.
+ *
+ * A gate rather than an extension point of its own: `defineGate` is the
+ * reactor's primitive for exactly this — one plugin asking the others whether
+ * something may happen, and being told why not in words it can show. The chat
+ * asks; the sandbox plugin answers, because only some of the places code runs
+ * bring an agent with them. Neither imports the other.
+ *
+ * Nothing answering means allowed, so a workspace with no sandbox plugin has a
+ * working chat.
+ */
+export const LoopAgentGate = defineGate('loop.agent.available');
+/** @deprecated Use `LoopAgentGate`; chat is one consumer of agent availability. */
+export const LoopChatGate = LoopAgentGate;
+/**
+ * The notebook editor's toolbar.
+ *
+ * Offered by the notebook plugin and filled by the notebook toolbar plugin.
+ * The notebook names neither the toolbar nor anything on it.
+ */
+export const LoopNotebookToolbar = defineContributionPoint('loop.notebook.toolbar');
+/**
+ * What goes on the notebook's toolbar, once something provides one.
+ *
+ * Offered by the *toolbar* plugin, not by the editor: the bar is what accepts
+ * buttons, so the plugin that owns the bar is the one that opens the point.
+ * The chat puts its agent actions here.
+ */
+export const LoopNotebookToolbarItem = defineContributionPoint('loop.notebook.toolbar.item');
+/** The document editor's toolbar. The same arrangement, for prose. */
+export const LoopDocumentToolbar = defineContributionPoint('loop.document.toolbar');
+/** What goes on the document's toolbar, once something provides one. */
+export const LoopDocumentToolbarItem = defineContributionPoint('loop.document.toolbar.item');
+// Asking the chat to open a surface, from a command that runs outside it.
+export { onSurfaceRequest, requestSurface, } from './surfaceRequests';
+// Asking whatever renders the prompt to focus it, the same way.
+export { focusPrompt, onPromptFocusRequest } from './focusRequests';
+/** Slash commands, shared in shape with the CLI. */
+export const LoopCommand = defineContributionPoint('loop.command');
+/** `@` namespaces. */
+export const LoopMention = defineContributionPoint('loop.mention');
+/** Slot names the shell renders. Slots render everything; points choose one. */
+export const LoopSlots = {
+    /** Agent picker, model chip, status indicators. */
+    header: 'loop.header',
+    /**
+     * The chat's own title bar, beside the agent's name.
+     *
+     * Distinct from `header`, which is the workspace's row above every view: a
+     * host can hide one and keep the other, and what belongs here is what is
+     * true of the *conversation* rather than of the workspace — how long the
+     * visitor's trial key has left, say.
+     *
+     * Empty for most workspaces, and the chat asks whether anyone contributed
+     * before it draws anything, so an unfilled slot costs nothing.
+     */
+    chatHeader: 'loop.chatHeader',
+    /** Buttons beside the prompt. */
+    promptAction: 'loop.promptAction',
+    /**
+     * The strip inside the prompt, above where the typing goes.
+     *
+     * Kept and rendered, and nothing contributes to it today: the controls that
+     * decide what the next message does — agent, tools, skills, model — live in
+     * the footer under the prompt, which already had three of the four. This is
+     * for whatever wants to sit *in* the prompt rather than under it, and it
+     * draws nothing while it is empty.
+     */
+    inpromptMenu: 'loop.inpromptMenu',
+    /**
+     * Under the view, above the status line.
+     *
+     * Where the chat plugin puts its prompt. A slot rather than a fixed place in
+     * the shell, so a workspace mounted without a chat has nothing there instead
+     * of an input box wired to nothing.
+     */
+    footer: 'loop.footer',
+    /** Small status items under the prompt. */
+    status: 'loop.status',
+    /**
+     * A mount point for plugins that position themselves.
+     *
+     * Rendered once, with no layout of its own. What goes here paints over the
+     * workspace from a portal — the command palette does — so the slot only has
+     * to exist somewhere the reactor is running. It is `root` rather than
+     * `loop.root` because it is the reactor's convention rather than the loop's:
+     * the music and CMS applications render the same name for the same plugins.
+     */
+    root: 'root',
+    /**
+     * The trailing edge, beside the view: the plugin list, and anything else
+     * that belongs next to the work rather than in front of it.
+     *
+     * A slot, so a workspace with no sidebar plugin has no sidebar at all — the
+     * column is not drawn when nothing fills it.
+     */
+    sidebar: 'loop.sidebar',
+};
+/**
+ * The sandbox's lifecycle, in the vocabulary a kernel indicator speaks.
+ *
+ * Here rather than beside either renderer because two of them draw the same
+ * fact — the control in the workspace header, and the chat's own header for a
+ * host that hides the workspace's. Two copies of this mapping would eventually
+ * disagree about what `starting` looks like, and a workspace showing two
+ * indicators that disagree is worse than one showing none.
+ *
+ * The execution state is the finer answer and wins when there is one: a
+ * running sandbox is either working or waiting, and which of the two is the
+ * thing a person actually watches for.
+ */
+export function sandboxIndicatorState(state, executionState, isExecuting) {
+    if (state === 'error')
+        return 'connected-dead';
+    if (state === 'starting')
+        return 'connected-starting';
+    if (state === 'stopping')
+        return 'disconnecting';
+    if (state !== 'running')
+        return 'disconnected';
+    return executionState === 'busy' || isExecuting
+        ? 'connected-busy'
+        : 'connected-idle';
+}
+/** Whether a view or a chat surface can be opened right now. */
+export function canOpenView(contribution, workspace) {
+    return contribution.canOpen ? contribution.canOpen(workspace) : true;
+}
+/** Parse `/name rest` into its parts. Returns undefined when it is not a command. */
+export function parseCommand(input) {
+    const text = input.trimStart();
+    if (!text.startsWith('/')) {
+        return undefined;
+    }
+    const [head, ...rest] = text.slice(1).split(/\s+/);
+    if (!head) {
+        return undefined;
+    }
+    return { name: head.toLowerCase(), argv: rest.join(' ').trim() };
+}
+export { useLoopPromptStore, suggestLoopPrompt, } from './promptStore';
+export const LoopChatLayout = defineContributionPoint('loop.chat.layout');
+export const LoopPromptPanel = defineContributionPoint('loop.prompt.panel');
+export const LoopChatTurn = defineContributionPoint('loop.chat.turn');

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

@@ -0,0 +1,44 @@
+/** A prompt offered to whichever workspace is listening. */
+export type SuggestedPrompt = {
+    /** What to put in the box. */
+    text: string;
+    /** Whether to send it as well as type it. Off by default. */
+    submit: boolean;
+    /**
+     * Tells two suggestions of the same text apart.
+     *
+     * Without it, clicking the same "Try this" button twice would set state to
+     * a value it already held, React would render nothing, and the second click
+     * would look broken. It is also what the prompt watches to take focus again.
+     */
+    nonce: number;
+};
+export type LoopPromptState = {
+    /** The suggestion waiting to be picked up, if there is one. */
+    pending?: SuggestedPrompt;
+    /** Offer a prompt to the workspace. */
+    suggest: (text: string, options?: {
+        submit?: boolean;
+    }) => void;
+    /** Called by the prompt once it has taken it. */
+    consume: () => void;
+};
+export declare const useLoopPromptStore: import("zustand").UseBoundStore<import("zustand").StoreApi<LoopPromptState>>;
+/**
+ * Offer a prompt to the workspace, from anywhere.
+ *
+ * The function a host calls. It does not need the hook, a provider, or a
+ * React tree — a click handler in a landing page is the case this is for:
+ *
+ * ```ts
+ * <Button onClick={() => suggestLoopPrompt('Plot this data as a histogram')}>
+ * ```
+ *
+ * Safe to call before the workspace has mounted: the suggestion waits, and the
+ * prompt picks it up when it arrives. That matters for a lazily loaded
+ * workspace, where the button can easily be clicked first.
+ */
+export declare function suggestLoopPrompt(text: string, options?: {
+    submit?: boolean;
+}): void;
+export default useLoopPromptStore;

package/lib/loop/core/promptStore.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Putting words in the workspace's prompt from outside it.
+ *
+ * A page that embeds the workspace often has something to say about it — a
+ * "try this" button beside the notebook, a suggestion in a landing hero — and
+ * the honest version of that button is not a link to documentation but the
+ * request itself, typed into the prompt where the visitor can read it, edit it
+ * and decide whether to send it.
+ *
+ * A store rather than a prop, because the two sides are far apart: the button
+ * lives in the host's page and the prompt lives several plugins deep inside
+ * the workspace, and threading a callback between them would put the host's
+ * copy into the workspace's props. The host calls a function; whichever prompt
+ * is mounted answers. Nothing is imported in the other direction.
+ *
+ * What is *not* here: sending. A suggestion arrives as a draft, and the
+ * visitor presses the button. A page that could make an agent run without
+ * anyone reading what it was asked is a page that can spend somebody's compute
+ * on their behalf — `submit` exists for the host that genuinely wants that,
+ * and defaults to off.
+ *
+ * @module loop/core/promptStore
+ */
+import { create } from 'zustand';
+export const useLoopPromptStore = create((set, get) => ({
+    pending: undefined,
+    suggest: (text, options) => {
+        const trimmed = text.trim();
+        if (!trimmed) {
+            return;
+        }
+        set({
+            pending: {
+                text: trimmed,
+                submit: options?.submit ?? false,
+                nonce: (get().pending?.nonce ?? 0) + 1,
+            },
+        });
+    },
+    consume: () => set({ pending: undefined }),
+}));
+/**
+ * Offer a prompt to the workspace, from anywhere.
+ *
+ * The function a host calls. It does not need the hook, a provider, or a
+ * React tree — a click handler in a landing page is the case this is for:
+ *
+ * ```ts
+ * <Button onClick={() => suggestLoopPrompt('Plot this data as a histogram')}>
+ * ```
+ *
+ * Safe to call before the workspace has mounted: the suggestion waits, and the
+ * prompt picks it up when it arrives. That matters for a lazily loaded
+ * workspace, where the button can easily be clicked first.
+ */
+export function suggestLoopPrompt(text, options) {
+    useLoopPromptStore.getState().suggest(text, options);
+}
+export default useLoopPromptStore;

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

@@ -0,0 +1,33 @@
+/**
+ * Asking the chat to open a surface, from outside React.
+ *
+ * The surface beside the chat — a notebook, a document — is the chat's own
+ * state, held in the component that draws it. That is right: the chat decides
+ * what it shows, and lifting it into a global store so anything could set it
+ * would make every caller a co-owner of the chat's layout.
+ *
+ * But a command runs outside the component tree, and `/notebook` has to be
+ * able to open the notebook. Both editor commands used to call
+ * `setActiveViewType('chat')` and stop there, which shows the chat and leaves
+ * whichever surface was already open — so on the chat view, where a reader
+ * usually is, they did nothing at all.
+ *
+ * This is the narrow channel between the two: a command asks, the chat
+ * answers, and nobody else gains a way to set the chat's state. `requestSurface`
+ * reports whether anything was listening, so a command invoked with no chat on
+ * screen can say so rather than failing silently — which is how this went
+ * unnoticed.
+ *
+ * @module loop/core/surfaceRequests
+ */
+/** Told which surface somebody asked for. */
+export type SurfaceRequestListener = (surfaceId: string) => void;
+/**
+ * Ask for a surface by id.
+ *
+ * @returns whether anything was listening — `false` means no chat is mounted,
+ *   and the caller should say so rather than assume it worked.
+ */
+export declare function requestSurface(surfaceId: string): boolean;
+/** Listen for those requests. Returns the unsubscribe. */
+export declare function onSurfaceRequest(listener: SurfaceRequestListener): () => void;

package/lib/loop/core/surfaceRequests.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+const listeners = new Set();
+/**
+ * Ask for a surface by id.
+ *
+ * @returns whether anything was listening — `false` means no chat is mounted,
+ *   and the caller should say so rather than assume it worked.
+ */
+export function requestSurface(surfaceId) {
+    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(surfaceId);
+    }
+    return true;
+}
+/** Listen for those requests. Returns the unsubscribe. */
+export function onSurfaceRequest(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}

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

@@ -0,0 +1,28 @@
+import type { ContributionPoint } from '@datalayer/reactor';
+import type { ToolbarItem } from '@datalayer/primer-addons';
+import type { EditorToolbarContext, EditorToolbarContribution, EditorToolbarItemContribution } from './index';
+/** What an editor needs to know to draw its toolbar, or not draw it. */
+export type EditorToolbar = {
+    /**
+     * Whether any plugin provides one.
+     *
+     * `false` means render no toolbar at all — not an empty one. An empty bar
+     * would still take a row of space and a border, and would make the toolbar
+     * plugin look like decoration rather than the thing that owns the bar.
+     */
+    present: boolean;
+    /** Everything to put on it, ordered by the editor's own toolbar. */
+    items: ToolbarItem[];
+};
+/**
+ * The toolbar for this editor: whether there is one, and what is on it.
+ *
+ * Reading both points is also what activates the plugins waiting on them: an
+ * editor that renders causes its toolbar's provider to load, without naming
+ * it.
+ *
+ * @param point The point a plugin provides the toolbar through
+ * @param itemPoint The point other plugins add to it through
+ * @param context What contributors are handed
+ */
+export declare function useEditorToolbar(point: ContributionPoint<EditorToolbarContribution>, itemPoint: ContributionPoint<EditorToolbarItemContribution>, context: EditorToolbarContext): EditorToolbar;

package/lib/loop/core/toolbar.js

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Reading an editor toolbar out of the plugins that provide and fill it.
+ *
+ * One hook rather than the same logic in each editor, because the rule — no
+ * provider, no toolbar, and no items either — has to be the same in both or
+ * the two editors disagree about what switching a toolbar plugin off means.
+ *
+ * @module loop/core/toolbar
+ */
+import { useMemo } from 'react';
+import { useContributions } from '@datalayer/reactor/react';
+/** Build one plugin's items, without letting a broken one take the editor down. */
+function itemsOf(entry, context) {
+    try {
+        return entry.value.items?.(context) ?? [];
+    }
+    catch (error) {
+        // The notebook is the work, the toolbar is furniture: one plugin with a
+        // broken item must not cost the reader their editor.
+        console.warn(`[loop] The plugin ${entry.plugin} failed to build its toolbar items.`, error);
+        return [];
+    }
+}
+/**
+ * The toolbar for this editor: whether there is one, and what is on it.
+ *
+ * Reading both points is also what activates the plugins waiting on them: an
+ * editor that renders causes its toolbar's provider to load, without naming
+ * it.
+ *
+ * @param point The point a plugin provides the toolbar through
+ * @param itemPoint The point other plugins add to it through
+ * @param context What contributors are handed
+ */
+export function useEditorToolbar(point, itemPoint, context) {
+    const providers = useContributions(point);
+    const additions = useContributions(itemPoint);
+    const { workspace, editorId } = context;
+    return useMemo(() => {
+        if (providers.length === 0) {
+            // Nobody provides the bar, so nothing goes on it. Returning the
+            // additions here would leave the chat's buttons looking for a toolbar
+            // that the editor is not going to draw.
+            return { present: false, items: [] };
+        }
+        const scoped = { workspace, editorId };
+        return {
+            present: true,
+            items: [
+                ...providers.flatMap(entry => itemsOf(entry, scoped)),
+                ...additions.flatMap(entry => itemsOf(entry, scoped)),
+            ],
+        };
+    }, [providers, additions, workspace, editorId]);
+}

package/lib/loop/embed/LoopEmbed.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Loop, ready to drop into somebody else's page.
+ *
+ * The supported way to embed the workspace: a plugin set from `loopPlugins`, a
+ * query client, an optional theme, and the shell. Everything a host has to do
+ * around Loop, done once here instead of once per host.
+ *
+ * It exists because the landing page was embedding the *example*. An example is
+ * written to be read — its props are demonstration switches, its wiring is
+ * whatever made the demo clearest, and none of it is a promise. A page that
+ * embeds Loop needs a supported surface, and the two drifting apart should not
+ * be able to break somebody's home page.
+ *
+ * What a host still owns is the frame it puts around this and how much of the
+ * page to give it. `WindowFrame` is there for the first; the second is a
+ * `height` on whatever wraps this.
+ *
+ * @module loop/embed/LoopEmbed
+ */
+import { type ReactNode } from 'react';
+import type { PluginRef } from '@datalayer/reactor';
+import { type LoopPresetOptions } from '../presets';
+export type LoopEmbedProps = LoopPresetOptions & {
+    /** Which agent the conversation is with. */
+    agentId?: string;
+    /** Whether the shell draws its own header row above the views. */
+    showHeader?: boolean;
+    /** Extra controls for the chat's own header, beside the agent's name. */
+    chatHeaderActions?: ReactNode;
+    /** The host's own controls for the workspace header row. */
+    headerActions?: ReactNode;
+    /**
+     * Draw the workspace inside a window frame with this title bar.
+     *
+     * The composition every embedding page was writing for itself: the frame
+     * around the shell, the title in its bar. Giving a title is what asks for
+     * the frame; it also switches the `windowFrame` plugin on, since a frame
+     * whose title-bar slots are closed to plugins is only half the point.
+     */
+    frameTitle?: ReactNode;
+    /**
+     * How tall the frame stands. Left unset it fills whatever wraps this,
+     * which is what a full-page host wants.
+     */
+    frameHeight?: number | string;
+    /**
+     * The host's own plugins, mounted alongside the preset's.
+     *
+     * How a page adds something to Loop rather than around it — a button in the
+     * window's title bar, a panel of its own, a command. Without this a host
+     * would have to rebuild the plugin list to add one thing to it, which is the
+     * assembly this component exists to save.
+     */
+    plugins?: PluginRef[];
+};
+export declare function LoopEmbed({ agentId, showHeader, chatHeaderActions, headerActions, frameTitle, frameHeight, plugins, ...preset }: LoopEmbedProps): React.JSX.Element;
+export default LoopEmbed;