@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/examples/hooks/useExampleJupyterAgent.d.ts

@@ -0,0 +1,91 @@
+import type { ServiceManager } from '@jupyterlab/services';
+import type { ProtocolConfig } from '../../types/protocol';
+import type { FrontendToolDefinition } from '../../types/tools';
+import { type UseExampleAgentRuntimeResult } from './useExampleAgentRuntime';
+export { exampleJupyterSandboxUrl } from '../utils/jupyterSandboxUrl';
+export { useCreateAgentOnce } from './useCreateAgentOnce';
+export interface UseExampleJupyterAgentOptions {
+    /** This example's key, for the summary badge. */
+    exampleId: string;
+    /** The agent's name, which is also its id on the runtime. */
+    agentName: string;
+    /**
+     * The agentspec this example's agent is built from, if it has one.
+     *
+     * Every example is meant to name one: it is what puts a real entry in the
+     * summary's `Spec:` field instead of a dash, and it is what lets the runtime
+     * build the agent from the catalogue — model, skills, tools, guardrails —
+     * rather than from whatever this hook's caller happened to inline. The
+     * inline `systemPrompt` and `model` below stay as the fallback for an
+     * example that has no spec yet, and as the local override for one that does.
+     */
+    specId?: string;
+    /** One line about the agent, shown by the runtime. */
+    description: string;
+    /** The agent's instructions. */
+    systemPrompt: string;
+    /** The notebook or document runtime, which may also be the sandbox. */
+    serviceManager?: ServiceManager.IManager;
+    /** Model override. Defaults to the package's. */
+    model?: string;
+    /**
+     * The tools the agent can call in this page.
+     *
+     * Given here rather than to the chat, because who executes them depends on
+     * where the loop turns and only this hook knows that — see
+     * {@link UseExampleJupyterAgentResult.chatFrontendTools}.
+     */
+    frontendTools?: FrontendToolDefinition[];
+}
+export interface UseExampleJupyterAgentResult extends UseExampleAgentRuntimeResult {
+    /**
+     * Whether *this example's* agent exists on the runtime and is ready.
+     *
+     * Not the same as `isReady`, which reports the runtime. The distinction
+     * matters on the cloud target, where the shell launches the runtime and
+     * creates an agent of its own before the example mounts: the runtime is
+     * ready long before this example's agent has been registered, and a chat
+     * opened in that window posts to an agent id the runtime does not know,
+     * which comes back as "No agent registered for this ID".
+     *
+     * Answered from this hook's own creation call rather than from the shared
+     * runtime state, which `connectAgent` rebuilds without an agent id and which
+     * the shell writes to as well.
+     */
+    agentReady: boolean;
+    /**
+     * What to give the chat, chosen by where the loop turns.
+     *
+     * Remotely it is the Vercel AI wire protocol against the agent's endpoint.
+     * In the browser it is the in-page harness, carrying the prompt and the
+     * tools rather than a URL.
+     */
+    protocol: ProtocolConfig;
+    /**
+     * The tools to pass the chat component — which is not always the tools.
+     *
+     * Against a runtime the chat runs frontend tools itself: a `tool-call`
+     * arrives over the wire and it answers with the result. In the browser the
+     * SDK owns the loop and calls the handlers directly, so handing them to the
+     * chat as well would run every tool twice. Empty there, and the tools go to
+     * the adapter instead.
+     */
+    chatFrontendTools?: FrontendToolDefinition[];
+    /** The sandbox handed to the agent, when there is one. */
+    jupyterSandboxUrl?: string;
+    /** Whether the single creation attempt has been made. */
+    createAttempted: boolean;
+    /**
+     * Why there is no agent, when there is none.
+     *
+     * Either the target has none to begin with, or there is no sandbox to give
+     * it, or the one attempt to create it failed. All three are things an
+     * example should say rather than retry.
+     */
+    unavailableReason?: string;
+}
+/**
+ * An agent for an example, created once against a Jupyter sandbox.
+ */
+export declare function useExampleJupyterAgent(options: UseExampleJupyterAgentOptions): UseExampleJupyterAgentResult;
+export default useExampleJupyterAgent;

package/lib/examples/hooks/useExampleJupyterAgent.js

@@ -0,0 +1,151 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * One agent, on a Jupyter sandbox, created once.
+ *
+ * Five examples wanted the same thing — an agent that can drive the notebook
+ * or document on the page — and each grew its own copy of the same twenty
+ * lines. The copies shared two bugs, and sharing them is why this hook exists.
+ *
+ * **It never retries** — see {@link useCreateAgentOnce}, which is where the
+ * copies' retry loop was.
+ *
+ * **It does not invent a sandbox** — see {@link exampleJupyterSandboxUrl},
+ * which is where they invented one.
+ *
+ * Both live in modules of their own, free of the runtime graph this hook pulls
+ * in, so the two things that were actually broken can be tested without it.
+ *
+ * @module examples/hooks/useExampleJupyterAgent
+ */
+import { useMemo } from 'react';
+import { DEFAULT_MODEL } from '../../specs';
+import { BROWSER_SIGN_IN_REASON, useExampleAgentProtocol, } from './useExampleAgentProtocol';
+import { exampleJupyterSandboxUrl } from '../utils/jupyterSandboxUrl';
+import { runsInBrowser } from '../../runtimes/variants';
+import { useCreateAgentOnce } from './useCreateAgentOnce';
+import { useExampleAgentRuntime, } from './useExampleAgentRuntime';
+export { exampleJupyterSandboxUrl } from '../utils/jupyterSandboxUrl';
+export { useCreateAgentOnce } from './useCreateAgentOnce';
+/**
+ * Statuses that mean a runtime is on its way rather than missing.
+ *
+ * A runtime that has not arrived yet is not a problem to report; one that is
+ * not coming is.
+ */
+/*
+ * Statuses that mean "not yet", as opposed to "not going to".
+ *
+ * `idle` belongs here on a target that starts a runtime by itself. It is where
+ * the hook sits while it asks whether a runtime for this spec is already
+ * running — a question asked on every mount, so switching examples lands here
+ * every time — and reading it as a settled answer is what put "No runtime is
+ * connected" on screen a moment before one connected.
+ */
+const STARTING_UP = new Set([
+    'idle',
+    'launching',
+    'connecting',
+    'pending',
+    'resuming',
+    'starting',
+]);
+/**
+ * An agent for an example, created once against a Jupyter sandbox.
+ */
+export function useExampleJupyterAgent(options) {
+    const { exampleId, agentName, specId, description, systemPrompt, serviceManager, model = DEFAULT_MODEL, frontendTools, } = options;
+    const jupyterSandboxUrl = useMemo(() => exampleJupyterSandboxUrl(serviceManager), [serviceManager]);
+    const agentConfig = useMemo(() => ({
+        name: agentName,
+        description,
+        protocol: 'vercel-ai',
+        model,
+        systemPrompt,
+        enableCodemode: false,
+        sandboxVariant: 'jupyter-server',
+        jupyterSandbox: jupyterSandboxUrl,
+        // Named here as well as passed below: `useExampleAgentRuntimes` only
+        // folds the spec id into the config on the local target, and the runtime
+        // needs it on every one.
+        ...(specId ? { agentSpecId: specId } : {}),
+    }), [agentName, description, model, systemPrompt, jupyterSandboxUrl, specId]);
+    const result = useExampleAgentRuntime({
+        exampleId,
+        agentName,
+        specId,
+        autoCreateAgent: false,
+        agentConfig,
+    });
+    const { agentId, createAgent, hasAgent, chatGate, runtime, status, variant } = result;
+    // The one branch this hook exists to hide. Everything about *reaching* an
+    // agent differs between a runtime and this page; nothing else does.
+    const inBrowser = runsInBrowser(variant);
+    const { protocol, chatFrontendTools, needsSignIn } = useExampleAgentProtocol({
+        inBrowser,
+        agentName,
+        systemPrompt,
+        model,
+        frontendTools,
+        remoteBaseUrl: result.baseUrl,
+    });
+    const { attempted, created, error: createError, } = useCreateAgentOnce({
+        /*
+         * Three things have to be true before there is anything to attempt.
+         *
+         * The third — a connected runtime — is a precondition rather than a
+         * preference: the store's `createAgent` needs one to know where to post,
+         * and throws "No runtime connected" without it. On the cloud target that
+         * runtime is launched by the shell, which finishes after the example has
+         * mounted, so an attempt made on mount is always too early.
+         *
+         * The copies this hook replaced survived that ordering by accident: they
+         * retried without limit, so one of the attempts eventually landed after
+         * the runtime appeared. Waiting for the precondition is what makes a
+         * single attempt correct — the effect simply does not run until it can
+         * succeed.
+         */
+        // Nothing to create in the browser: the loop is already here, and there
+        // is no runtime to register an agent on.
+        enabled: !inBrowser && hasAgent && !!jupyterSandboxUrl && !!runtime,
+        // Ours, by name. The runtime state is shared with the shell, which
+        // registers an agent of its own on the cloud target — treating that as
+        // "already created" is what left this example without one.
+        alreadyCreated: agentId === agentName,
+        createAgent,
+        config: agentConfig,
+    });
+    const unavailableReason = !hasAgent
+        ? chatGate.disableReason
+        : inBrowser
+            ? needsSignIn
+                ? BROWSER_SIGN_IN_REASON
+                : undefined
+            : !jupyterSandboxUrl
+                ? 'No Jupyter server to run this agent on. Start one and set VITE_JUPYTER_SANDBOX_URL, or switch the runtime target.'
+                : !runtime
+                    ? // Still arriving is not a fault; still absent once everything has
+                        // settled is. Said out loud because the alternative — which this
+                        // replaces — was a chat that simply never appeared, with nothing
+                        // anywhere to say why.
+                        STARTING_UP.has(status)
+                            ? undefined
+                            : 'No runtime is connected, so there is nowhere to create this agent. Try switching the runtime target again.'
+                    : createError;
+    return {
+        ...result,
+        // In the browser there is nothing to wait for: no runtime to start and no
+        // agent to register. Elsewhere, our own call having returned — not a read
+        // of the shared runtime state, which `connectAgent` rebuilds without an
+        // agent id whenever anything reconnects, and which the shell writes to too.
+        agentReady: inBrowser ? !needsSignIn : !!created || agentId === agentName,
+        protocol,
+        chatFrontendTools,
+        jupyterSandboxUrl,
+        createAttempted: attempted,
+        unavailableReason,
+    };
+}
+export default useExampleJupyterAgent;

package/lib/examples/index.d.ts

@@ -4,6 +4,10 @@ export { default as A2UiContactCardExample } from './A2UiContactCardExample';
 export { default as A2UiRestaurantExample } from './A2UiRestaurantExample';
 export { default as A2UiAgentExample } from './A2UiAgentExample';
 export { default as A2UiViewerExample } from './A2UiViewerExample';
+export { default as LoopShellExample } from './LoopShellExample';
+export { default as LoopWorkspaceExample } from './LoopWorkspaceExample';
+export { default as LoopWorkspaceEmbed, preloadLoopWorkspace, type LoopWorkspaceEmbedProps, } from './LoopWorkspaceEmbed';
+export { default as A2UiJupyterOutputExample } from './A2UiJupyterOutputExample';
 export { default as AgUiAgenticExample } from './AgUiAgenticExample';
 export { default as AgUiBackendToolRenderingExample } from './AgUiBackendToolRenderingExample';
 export { default as AgUiHaikuGenUiExample } from './AgUiHaikuGenUiExample';

package/lib/examples/index.js

@@ -8,6 +8,12 @@ export { default as A2UiContactCardExample } from './A2UiContactCardExample';
 export { default as A2UiRestaurantExample } from './A2UiRestaurantExample';
 export { default as A2UiAgentExample } from './A2UiAgentExample';
 export { default as A2UiViewerExample } from './A2UiViewerExample';
+export { default as LoopShellExample } from './LoopShellExample';
+export { default as LoopWorkspaceExample } from './LoopWorkspaceExample';
+// The same workspace with the lazy loading, the preload and the error
+// boundary a host would otherwise write for itself.
+export { default as LoopWorkspaceEmbed, preloadLoopWorkspace, } from './LoopWorkspaceEmbed';
+export { default as A2UiJupyterOutputExample } from './A2UiJupyterOutputExample';
 export { default as AgUiAgenticExample } from './AgUiAgenticExample';
 export { default as AgUiBackendToolRenderingExample } from './AgUiBackendToolRenderingExample';
 export { default as AgUiHaikuGenUiExample } from './AgUiHaikuGenUiExample';

package/lib/examples/lexical/editorConfig.d.ts

@@ -1,77 +1,4 @@
-import { HeadingNode, QuoteNode } from '@lexical/rich-text';
-import { ListNode, ListItemNode } from '@lexical/list';
-import { CodeNode, CodeHighlightNode } from '@lexical/code';
-import { LinkNode } from '@lexical/link';
-import { TableNode, TableCellNode, TableRowNode } from '@lexical/table';
-import { HashtagNode } from '@lexical/hashtag';
-import { MarkNode } from '@lexical/mark';
-import { OverflowNode } from '@lexical/overflow';
-import { HorizontalRuleNode } from '@lexical/react/LexicalHorizontalRuleNode';
-import { EquationNode, ImageNode, YouTubeNode, ExcalidrawNode, CollapsibleContainerNode, CollapsibleTitleNode, CollapsibleContentNode, JupyterCellNode, JupyterInputNode, JupyterInputHighlightNode, JupyterOutputNode, InlineCompletionNode } from '@datalayer/jupyter-lexical';
 /**
- * Lexical editor configuration
+ * Lexical editor extension
  */
-export declare const editorConfig: {
-    namespace: string;
-    editable: boolean;
-    theme: {
-        text: {
-            bold: string;
-            italic: string;
-            underline: string;
-            strikethrough: string;
-            code: string;
-            subscript: string;
-            superscript: string;
-        };
-        paragraph: string;
-        quote: string;
-        heading: {
-            h1: string;
-            h2: string;
-            h3: string;
-            h4: string;
-            h5: string;
-            h6: string;
-        };
-        list: {
-            ul: string;
-            ol: string;
-            listitem: string;
-            nested: {
-                listitem: string;
-            };
-            checklist: string;
-            listitemChecked: string;
-            listitemUnchecked: string;
-        };
-        code: string;
-        codeHighlight: {
-            comment: string;
-            punctuation: string;
-            property: string;
-            selector: string;
-            operator: string;
-            attr: string;
-            variable: string;
-            function: string;
-            keyword: string;
-            string: string;
-            number: string;
-            boolean: string;
-            regex: string;
-        };
-        link: string;
-        autolink: string;
-        table: string;
-        tableCell: string;
-        tableCellHeader: string;
-        hashtag: string;
-        image: string;
-        hr: string;
-        mark: string;
-    };
-    editorState: string;
-    nodes: (typeof HeadingNode | typeof QuoteNode | typeof ListNode | typeof ListItemNode | typeof CodeNode | typeof CodeHighlightNode | typeof LinkNode | typeof TableNode | typeof TableCellNode | typeof TableRowNode | typeof HashtagNode | typeof MarkNode | typeof OverflowNode | typeof HorizontalRuleNode | typeof EquationNode | typeof ImageNode | typeof YouTubeNode | typeof ExcalidrawNode | typeof CollapsibleContainerNode | typeof CollapsibleTitleNode | typeof CollapsibleContentNode | typeof JupyterCellNode | typeof JupyterInputNode | typeof JupyterInputHighlightNode | typeof JupyterOutputNode | typeof InlineCompletionNode)[];
-    onError(_error: Error): void;
-};
+export declare const editorExtension: import("lexical").LexicalExtension<import("lexical").ExtensionConfigBase, "@datalayer/agent-runtimes/examples/Lexical", unknown, unknown>;

package/lib/examples/lexical/editorConfig.js

@@ -2,60 +2,38 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { HeadingNode, QuoteNode } from '@lexical/rich-text';
-import { ListNode, ListItemNode } from '@lexical/list';
-import { CodeNode, CodeHighlightNode } from '@lexical/code';
-import { LinkNode, AutoLinkNode } from '@lexical/link';
-import { TableNode, TableCellNode, TableRowNode } from '@lexical/table';
-import { HashtagNode } from '@lexical/hashtag';
-import { MarkNode } from '@lexical/mark';
-import { OverflowNode } from '@lexical/overflow';
-import { HorizontalRuleNode } from '@lexical/react/LexicalHorizontalRuleNode';
-import { EquationNode, ImageNode, YouTubeNode, ExcalidrawNode, CollapsibleContainerNode, CollapsibleTitleNode, CollapsibleContentNode, JupyterCellNode, JupyterInputNode, JupyterInputHighlightNode, JupyterOutputNode, InlineCompletionNode, } from '@datalayer/jupyter-lexical';
+/**
+ * The Lexical editor the examples share, as a root extension.
+ *
+ * `JupyterLexicalExtension` is the document — every node and behaviour of
+ * `@datalayer/jupyter-lexical` — and this adds what is the examples' own:
+ * their namespace, their theme, the demo content, focus on mount and the
+ * overflow node. Defined once at module scope so a composer never rebuilds
+ * the editor on a re-render.
+ *
+ * @module examples/lexical/editorConfig
+ */
+import { AutoFocusExtension } from '@lexical/extension';
+import { OverflowExtension } from '@lexical/overflow';
+import { JupyterLexicalExtension } from '@datalayer/jupyter-lexical';
+import { defineExtension } from 'lexical';
 import { lexicalTheme } from './theme';
 import initialContent from './initial-content.json';
 /**
- * Lexical editor configuration
+ * Lexical editor extension
  */
-export const editorConfig = {
+export const editorExtension = defineExtension({
+    name: '@datalayer/agent-runtimes/examples/Lexical',
     namespace: 'AgUiLexicalEditor',
     editable: true,
     theme: lexicalTheme,
-    editorState: JSON.stringify(initialContent),
-    nodes: [
-        // Basic rich text nodes
-        HeadingNode,
-        QuoteNode,
-        ListNode,
-        ListItemNode,
-        CodeNode,
-        CodeHighlightNode,
-        LinkNode,
-        AutoLinkNode,
-        // Table nodes
-        TableNode,
-        TableCellNode,
-        TableRowNode,
-        // Additional nodes from @lexical packages
-        HashtagNode,
-        MarkNode,
-        OverflowNode,
-        HorizontalRuleNode,
-        // Simple lexical nodes
-        EquationNode,
-        ImageNode,
-        YouTubeNode,
-        ExcalidrawNode,
-        CollapsibleContainerNode,
-        CollapsibleTitleNode,
-        CollapsibleContentNode,
-        JupyterCellNode,
-        JupyterInputNode,
-        JupyterInputHighlightNode,
-        JupyterOutputNode,
-        InlineCompletionNode,
+    dependencies: [
+        JupyterLexicalExtension,
+        AutoFocusExtension,
+        OverflowExtension,
     ],
-    onError(_error) {
-        // Lexical error handler
+    $initialEditorState: JSON.stringify(initialContent),
+    onError(error) {
+        console.error('[LexicalExample]', error);
     },
-};
+});