@datalayer/agent-runtimes 1.0.29 → 1.3.10

package/lib/loop/plugins/agents/agentIcons.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The octicon an agentspec asked for.
+ *
+ * Every spec names one — `mortar-board` for the tutor, `fold` for the
+ * compactor — and until something resolves it, every agent in a menu is drawn
+ * with the same fallback and the names do all the work.
+ *
+ * An explicit map rather than `import * as octicons`. The namespace import
+ * resolves any name in one line and pulls the whole icon set into the bundle
+ * with it, which a landing page that lazy-loads this workspace pays for on
+ * every visit. These are the names the catalogue actually uses.
+ *
+ * @module loop/plugins/agents/agentIcons
+ */
+import { BeakerIcon, BellIcon, BookIcon, BriefcaseIcon, BrowserIcon, BugIcon, ChecklistIcon, CodeReviewIcon, ClockIcon, CodeIcon, CommentDiscussionIcon, CpuIcon, CreditCardIcon, DatabaseIcon, FileIcon, FoldIcon, GitBranchIcon, GlobeIcon, GraphIcon, HeartIcon, IssueOpenedIcon, LightBulbIcon, ListUnorderedIcon, MailIcon, MegaphoneIcon, MortarBoardIcon, NoteIcon, OrganizationIcon, PackageIcon, PencilIcon, PeopleIcon, PlayIcon, PulseIcon, RssIcon, SearchIcon, ShareAndroidIcon, ShieldCheckIcon, ShieldIcon, SlidersIcon, SunIcon, SyncIcon, TableIcon, TagIcon, TasklistIcon, TelescopeIcon, ToolsIcon, RocketIcon, ZapIcon, } from '@primer/octicons-react';
+import { AiAgentIcon } from '@datalayer/icons-react';
+/** What a spec's `icon` string means, by the name the spec uses. */
+const AGENT_ICONS = {
+    agent: AiAgentIcon,
+    beaker: BeakerIcon,
+    bell: BellIcon,
+    book: BookIcon,
+    briefcase: BriefcaseIcon,
+    browser: BrowserIcon,
+    bug: BugIcon,
+    clock: ClockIcon,
+    code: CodeIcon,
+    'comment-discussion': CommentDiscussionIcon,
+    cpu: CpuIcon,
+    'credit-card': CreditCardIcon,
+    database: DatabaseIcon,
+    file: FileIcon,
+    checklist: ChecklistIcon,
+    'code-review': CodeReviewIcon,
+    fold: FoldIcon,
+    'git-branch': GitBranchIcon,
+    globe: GlobeIcon,
+    graph: GraphIcon,
+    heart: HeartIcon,
+    'issue-opened': IssueOpenedIcon,
+    lightbulb: LightBulbIcon,
+    // The name octicons actually use; `lightbulb` above is kept for the specs
+    // that were already written against it.
+    'light-bulb': LightBulbIcon,
+    'list-unordered': ListUnorderedIcon,
+    mail: MailIcon,
+    megaphone: MegaphoneIcon,
+    'mortar-board': MortarBoardIcon,
+    note: NoteIcon,
+    organization: OrganizationIcon,
+    package: PackageIcon,
+    pencil: PencilIcon,
+    people: PeopleIcon,
+    play: PlayIcon,
+    pulse: PulseIcon,
+    rss: RssIcon,
+    search: SearchIcon,
+    'share-2': ShareAndroidIcon,
+    shield: ShieldIcon,
+    'shield-check': ShieldCheckIcon,
+    sliders: SlidersIcon,
+    sun: SunIcon,
+    sync: SyncIcon,
+    table: TableIcon,
+    tag: TagIcon,
+    tasklist: TasklistIcon,
+    telescope: TelescopeIcon,
+    tools: ToolsIcon,
+    // Octicons has no trending icon; the landing's registry makes the same
+    // substitution, so the two agree on what this name draws.
+    'trending-up': GraphIcon,
+    rocket: RocketIcon,
+    zap: ZapIcon,
+};
+/**
+ * The icon for a spec's `icon` value, or the generic agent one.
+ *
+ * Never undefined: a menu row with a gap where its neighbours have icons reads
+ * as a rendering fault, and "some agent" is a true thing to draw.
+ */
+export function agentIcon(name) {
+    return (name ? AGENT_ICONS[name] : undefined) ?? AiAgentIcon;
+}
+export default agentIcon;

package/lib/loop/plugins/agents/browserService.d.ts

@@ -0,0 +1,50 @@
+import type { ServiceManager } from '@jupyterlab/services';
+import type { SandboxService } from './service';
+/** What a browser sandbox additionally exposes. */
+export type BrowserSandboxService = SandboxService & {
+    /** `'browser'`, so callers can tell what they are holding. */
+    readonly kind: 'browser';
+    /**
+     * The in-browser Jupyter services, once the kernel is up.
+     *
+     * The notebook and document views bind to *this* manager rather than opening
+     * one of their own, so the code a person runs in a cell and the code the
+     * agent runs through the sandbox land in the same kernel — which is the whole
+     * point of a shared sandbox.
+     */
+    getServiceManager: () => ServiceManager.IManager | null;
+};
+/**
+ * How a kernel-backed sandbox gets its services.
+ *
+ * The browser builds a JupyterLite manager; JupyterLab hands over the one the
+ * application already has. Everything after that — starting a session,
+ * executing, collecting outputs — is identical, which is why it is one
+ * implementation with this as its only variable.
+ */
+export type ServiceManagerSource = {
+    /** Where the kernel runs, for the snapshot and for callers that must ask. */
+    variant: string;
+    /** Produce the services. Called once, on first connect. */
+    acquire: () => Promise<ServiceManager.IManager>;
+    /**
+     * Undo whatever `acquire` did to state outside itself.
+     *
+     * Optional, because most sources take nothing: only the in-page one has to
+     * repoint the page's shared Jupyter configuration at this origin, and only
+     * it has anything to give back.
+     */
+    release?: () => void;
+    /** Whether this sandbox owns the manager and should dispose it on stop. */
+    owned: boolean;
+};
+/** A sandbox on a JupyterLite kernel in this page. */
+export declare function browserSource(): ServiceManagerSource;
+/**
+ * A sandbox on services someone else owns — JupyterLab's, typically.
+ *
+ * `owned: false` matters: disconnecting must not dispose a manager the host is
+ * still using for every other notebook it has open.
+ */
+export declare function suppliedSource(manager: ServiceManager.IManager, variant?: string): ServiceManagerSource;
+export declare function createBrowserSandboxService(source?: ServiceManagerSource): BrowserSandboxService;

package/lib/loop/plugins/agents/browserService.js

@@ -0,0 +1,233 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The sandbox, in the browser.
+ *
+ * Pyodide is not a `code_sandboxes` variant and never will be — that catalogue
+ * is server-side by construction (`docker`, `e2b`, `jupyter-server`, `modal`).
+ * This is a *second implementation of the same interface*, which is what the
+ * interface was for. If `SandboxService` could not be re-implemented against a
+ * browser kernel, it would not be an interface; it would be one implementation
+ * with a type annotation.
+ *
+ * Everything heavy — JupyterLite, the Pyodide kernel, Lumino — is behind a
+ * dynamic `import()` inside `connect()`, so a workspace that never starts a
+ * browser sandbox never downloads one.
+ *
+ * @module loop/plugins/agents/browserService
+ */
+import { computed, signal } from '@datalayer/reactor';
+import { PageConfig } from '@jupyterlab/coreutils';
+/** Collects one execution's outputs from the kernel's IOPub stream. */
+function collect(message, into) {
+    const type = message?.header?.msg_type;
+    const content = message?.content ?? {};
+    if (type === 'stream') {
+        into.stdout.push(String(content.text ?? ''));
+        into.outputs.push({ output_type: 'stream', text: content.text });
+    }
+    else if (type === 'execute_result' || type === 'display_data') {
+        into.outputs.push({ output_type: type, data: content.data });
+    }
+    else if (type === 'error') {
+        into.error = `${content.ename ?? 'Error'}: ${content.evalue ?? ''}`;
+        into.outputs.push({
+            output_type: 'error',
+            ename: content.ename,
+            evalue: content.evalue,
+            traceback: content.traceback,
+        });
+    }
+}
+/** A sandbox on a JupyterLite kernel in this page. */
+export function browserSource() {
+    /** Where the page was pointed before this sandbox repointed it. */
+    let pointedAt;
+    return {
+        variant: 'pyodide',
+        // Dynamic: JupyterLite and the Pyodide kernel are megabytes, and a
+        // workspace that never opens a browser sandbox should never pay for them.
+        acquire: async () => {
+            const { createLiteServiceManager, jupyterReactStore, loadJupyterConfig } = await import('@datalayer/jupyter-react');
+            /*
+             * Point Jupyter at this page before building the kernel that lives in it.
+             *
+             * A JupyterLite service manager takes its `serverSettings` from
+             * `PageConfig` at the moment it is created, and JupyterLab's kernel
+             * connection then opens a socket at `wsUrl`. So whatever set that option
+             * last decides where an *in-page* kernel looks for itself: on a host
+             * configured for a remote Jupyter — which any signed-in Datalayer page
+             * is — the browser sandbox started a WebSocket to that remote host, was
+             * refused, and every cell ran into silence. No error, no output, nothing
+             * to act on; the kernel was fine and nobody was talking to it.
+             *
+             * `loadJupyterConfig({ lite: true })` is jupyter-react's own way of
+             * saying "the page is the server": it points the base and socket URLs at
+             * this origin, where JupyterLite's service worker is listening. It also
+             * initialises the config, which the plain setter refuses to do — and a
+             * workspace can start a sandbox before any Jupyter component has mounted
+             * to load one.
+             */
+            pointedAt = pointedAt ?? {
+                baseUrl: PageConfig.getOption('baseUrl'),
+                wsUrl: PageConfig.getOption('wsUrl'),
+            };
+            loadJupyterConfig({ lite: true });
+            const manager = await createLiteServiceManager();
+            // Publish it to jupyter-react's store, which is what any component
+            // reached through `useJupyter()` without a manager of its own falls back
+            // to. Without this, a Jupyter cell dropped into the document built a
+            // second manager from the page's configured Jupyter URL and polled a
+            // server nobody asked for — the CORS failures came from there, while the
+            // cell itself ran perfectly on the kernel in this page.
+            jupyterReactStore.getState().setServiceManager(manager);
+            return manager;
+        },
+        /*
+         * Put the page back the way it was found.
+         *
+         * `PageConfig` is a singleton the whole page shares, and a workspace is a
+         * component on somebody's page rather than the page itself. Leaving it
+         * pointed at this origin after the reader moves the sandbox elsewhere
+         * would break the next thing to read it — which, in the app, is a notebook
+         * that belongs to a runtime somewhere else.
+         */
+        release: () => {
+            if (!pointedAt) {
+                return;
+            }
+            PageConfig.setOption('baseUrl', pointedAt.baseUrl);
+            PageConfig.setOption('wsUrl', pointedAt.wsUrl);
+            pointedAt = undefined;
+        },
+        owned: true,
+    };
+}
+/**
+ * A sandbox on services someone else owns — JupyterLab's, typically.
+ *
+ * `owned: false` matters: disconnecting must not dispose a manager the host is
+ * still using for every other notebook it has open.
+ */
+export function suppliedSource(manager, variant = 'jupyter-server') {
+    return { variant, acquire: async () => manager, owned: false };
+}
+export function createBrowserSandboxService(source = browserSource()) {
+    const status = signal(null);
+    const lifecycle = signal('idle');
+    const lastExecution = signal(null);
+    const snapshot = computed(() => ({
+        state: lifecycle.value,
+        variant: source.variant,
+        kernelId: status.value?.kernel_id,
+    }));
+    const ready = computed(() => lifecycle.value === 'running');
+    let serviceManager = null;
+    let kernel = null;
+    let starting = null;
+    async function start() {
+        if (kernel) {
+            return;
+        }
+        lifecycle.value = 'starting';
+        serviceManager = await source.acquire();
+        const connection = await serviceManager.sessions.startNew({
+            name: 'loop',
+            path: 'loop.ipynb',
+            type: 'notebook',
+            kernel: { name: 'python' },
+        });
+        kernel = connection.kernel;
+        status.value = {
+            variant: source.variant,
+            sandbox_running: true,
+            kernel_id: kernel?.id,
+            kernel_name: 'python',
+        };
+        lifecycle.value = 'running';
+    }
+    return {
+        kind: 'browser',
+        snapshot,
+        status,
+        ready,
+        lastExecution,
+        // No server backs this sandbox. Callers that need one — the A2UI converter
+        // lives on the server — should ask `kind` rather than discover it here.
+        serverUrl: '',
+        getServiceManager: () => serviceManager,
+        report(next) {
+            status.value = next;
+        },
+        setState(state) {
+            lifecycle.value = state;
+        },
+        connect() {
+            // Starting a Pyodide kernel takes seconds and megabytes; do it once, and
+            // let a second caller await the same start rather than racing it.
+            starting =
+                starting ??
+                    start().catch(error => {
+                        lifecycle.value = 'error';
+                        status.value = null;
+                        starting = null;
+                        throw error;
+                    });
+            void starting;
+            return () => {
+                // Shut down the kernel this sandbox started, but never the manager
+                // when the host owns it — JupyterLab is still using it for every other
+                // notebook that is open.
+                void kernel?.shutdown?.();
+                kernel = null;
+                serviceManager = source.owned ? null : serviceManager;
+                // And hand back whatever the source borrowed from the page.
+                source.release?.();
+                starting = null;
+                lifecycle.value = 'idle';
+                status.value = null;
+            };
+        },
+        async execute(code) {
+            const startedAt = Date.now();
+            try {
+                await (starting ?? start());
+                if (!kernel) {
+                    throw new Error('The browser kernel did not start');
+                }
+                const gathered = {
+                    outputs: [],
+                    stdout: [],
+                    error: '',
+                };
+                const future = kernel.requestExecute({ code });
+                future.onIOPub = message => collect(message, gathered);
+                await future.done;
+                const execution = {
+                    code,
+                    success: !gathered.error,
+                    stdout: gathered.stdout.join(''),
+                    error: gathered.error || undefined,
+                    outputs: gathered.outputs,
+                    startedAt,
+                    finishedAt: Date.now(),
+                };
+                lastExecution.value = execution;
+                return execution;
+            }
+            catch (error) {
+                const execution = {
+                    code,
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    startedAt,
+                    finishedAt: Date.now(),
+                };
+                lastExecution.value = execution;
+                return execution;
+            }
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+/**
+ * `@datalayer/loop-plugin-agents` — the sandbox, owned in one place.
+ *
+ * @module loop/plugins/agents
+ */
+export { AGENTS_PLUGIN_NAME, AgentsPlugin, type AgentsConfig, type AgentsOutput, } from './plugin';
+export { AgentsPlugin as default } from './plugin';
+export { browserSource, createBrowserSandboxService, suppliedSource, type BrowserSandboxService, type ServiceManagerSource, } from './browserService';
+export { createServerSandboxService, summarize, type SandboxExecution, type SandboxService, type SandboxStatusPayload, } from './service';
+export { useOptionalSandboxService, useSandboxService, } from './useSandboxService';
+export { SandboxStatusBridge } from './SandboxStatusBridge';
+export { SandboxSelector } from './SandboxSelector';
+export { SANDBOX_TARGETS, TARGET_SPECS, targetHasAgent, targetRunsAgentInPage, createSwitchableSandboxService, type SandboxTarget, type SwitchableSandboxService, } from './switchable';

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

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `@datalayer/loop-plugin-agents` — the sandbox, owned in one place.
+ *
+ * @module loop/plugins/agents
+ */
+export { AGENTS_PLUGIN_NAME, AgentsPlugin, } from './plugin';
+export { AgentsPlugin as default } from './plugin';
+export { browserSource, createBrowserSandboxService, suppliedSource, } from './browserService';
+export { createServerSandboxService, summarize, } from './service';
+export { useOptionalSandboxService, useSandboxService, } from './useSandboxService';
+export { SandboxStatusBridge } from './SandboxStatusBridge';
+export { SandboxSelector } from './SandboxSelector';
+export { SANDBOX_TARGETS, TARGET_SPECS, targetHasAgent, targetRunsAgentInPage, createSwitchableSandboxService, } from './switchable';

package/lib/loop/plugins/agents/plugin.d.ts

@@ -0,0 +1,91 @@
+import type { ReactorSlotComponent } from '@datalayer/reactor/react';
+import type { ServiceManagerSource } from './browserService';
+import { type TeamSelection } from './team';
+import { type SandboxTarget, type SwitchableSandboxService } from './switchable';
+export declare const AGENTS_PLUGIN_NAME = "@datalayer/loop-plugin-agents";
+export type AgentsConfig = {
+    /** Server the server-backed targets are reached through. */
+    serverUrl: string;
+    /**
+     * Where the sandbox starts.
+     *
+     * `browser` runs Python in the page through a Pyodide kernel; `local` and
+     * `cloud` are server-backed and differ in the variant the server runs. A
+     * reader can move it afterwards from the header — the same interface, three
+     * things behind it, which is the test of whether it is an interface at all.
+     */
+    target?: SandboxTarget;
+    /** Agent creation payload used by the Local target. */
+    localAgent?: {
+        createPayload: Record<string, unknown>;
+    };
+    /**
+     * Whether the workspace header carries the agent summary badge.
+     *
+     * True by default: the badge is how the workspace says what it is talking
+     * to. False for a host whose page already introduces the agent — a landing
+     * page names it in the copy around the embed, and a second summary inside
+     * is the introduction made twice.
+     */
+    showAgentSummary?: boolean;
+    /**
+     * Where the in-page kernel comes from, when the host has one of its own.
+     *
+     * JupyterLab supplies `suppliedSource(app.serviceManager)`, so the agent runs
+     * in the kernel the user is already looking at.
+     */
+    kernelSource?: ServiceManagerSource;
+    /**
+     * Whether a reader may choose where the agent runs.
+     *
+     * True by default: the control in the header is the thing that makes
+     * "browser, local or cloud" a choice rather than a build-time decision.
+     *
+     * A host that has already decided passes `false`, and then only the browser
+     * is offered — no control, and the target pinned to the one location that
+     * needs nothing behind it. That is what a public page wants: a visitor with
+     * no account cannot reach a local server or a Datalayer runtime, so offering
+     * them is offering three doors of which two are locked.
+     */
+    showAgentVariants?: boolean;
+    /**
+     * The team this workspace works with, by id.
+     *
+     * A team is a group of agents with one front door — `jupyter` is a
+     * tutor and a compactor behind a supervising tutor. Given one, the header
+     * gains a control for choosing which member the next prompt reaches, and the
+     * teamspec decides what each of them is told about the conversation.
+     */
+    teamId?: string;
+    /**
+     * Whether the header offers the team's member picker.
+     *
+     * True by default: with a team there is a choice to make, and the picker is
+     * what makes it. A host that draws the choice itself — a presence strip
+     * whose avatars address a member, say — passes `false`, and the choice
+     * stays available from the composer's agents menu regardless.
+     */
+    showTeamPicker?: boolean;
+    /**
+     * The agentspec the Datalayer target runs.
+     *
+     * That target allocates a runtime and creates an agent on it from this spec.
+     * The other targets take their agent from wherever they already run one.
+     */
+    datalayerAgentSpecId?: string;
+};
+export type AgentsOutput = {
+    sandbox: SwitchableSandboxService;
+    /**
+     * Who the next prompt goes to, when this workspace runs a team.
+     *
+     * Absent for the ordinary case of one agent: a workspace with nothing to
+     * choose between should not have to carry a selection, and a picker with one
+     * option is furniture.
+     */
+    team?: TeamSelection;
+    /** Rendered by `ReactorSlot`; see `ReactorReactOutput`. */
+    components: ReactorSlotComponent[];
+};
+export declare const AgentsPlugin: import("@datalayer/reactor").ReactorPlugin<AgentsConfig, unknown, AgentsOutput>;
+export default AgentsPlugin;