@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/examples/utils/localUrl.js

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Whether a URL names a service on this machine.
+ *
+ * Asked this way round on purpose. The test it replaces was "is this prod1?",
+ * which took every host it did not recognise for a local one — so once the
+ * configured service moved to `r1`, Local mode accepted the cloud URL as its
+ * own and the browser dialled it from `localhost`, where CORS refused it.
+ *
+ * The set of remote hosts is open — `prod1`, `r1`, whatever a deployment adds
+ * next — while the set of local ones is not, so the closed set is the one
+ * worth enumerating.
+ *
+ * Shared rather than copied because the same mistake is available to every
+ * "local" URL the examples resolve, and it was made twice: once for the
+ * Jupyter server, and once — unfixed until now — for the agent-runtimes
+ * server, where `VITE_DATALAYER_AGENT_RUNTIMES_URL` defaults to the cloud and
+ * was being handed back as the address of a server running on this laptop.
+ *
+ * @module examples/utils/localUrl
+ */
+/** Hosts that mean "this machine", exhaustively. */
+const LOCAL_HOSTS = new Set([
+    'localhost',
+    '127.0.0.1',
+    '0.0.0.0',
+    '::1',
+    '[::1]',
+]);
+export function isLocalUrl(value) {
+    if (!value) {
+        return false;
+    }
+    let host;
+    try {
+        host = new URL(value).hostname.toLowerCase();
+    }
+    catch {
+        // Not a whole URL — a bare `localhost:8765`, say. Match on the text.
+        return /(^|\/\/)(localhost|127\.0\.0\.1|0\.0\.0\.0|\[?::1\]?)([:/]|$)/.test(value);
+    }
+    return (LOCAL_HOSTS.has(host) ||
+        host.endsWith('.localhost') ||
+        host.endsWith('.local'));
+}
+export default isLocalUrl;

package/lib/examples/utils/notebookToolbarItems.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The toolbar every notebook example shows: the kernel indicator, in the
+ * colours of the theme the reader picked.
+ *
+ * A notebook toolbar knows how to save, run and interrupt; it does not know
+ * what it is running *on*, and someone reading an example wants to see that —
+ * whether a kernel is attached, whether it is busy, what it is. `NotebookToolbar`
+ * takes `extraItems` for exactly this, and its own docstring names the kernel
+ * indicator as the case.
+ *
+ * The examples app lets a reader change theme, and until now the notebook was
+ * the one part of the page that ignored them: a themed shell around a toolbar
+ * on Primer's stock canvas. Its background takes the theme's brand colour now,
+ * which is also what makes the picker legible — you can see what a theme
+ * *does*. The controls themselves stay stock.
+ *
+ * One toolbar, built once here, so every notebook example shows the same thing
+ * in the same place rather than each growing its own.
+ *
+ * @module examples/utils/notebookToolbarItems
+ */
+import type { JSX } from 'react';
+import type { ToolbarItem } from '@datalayer/primer-addons';
+import { type INotebookToolbarProps } from '@datalayer/jupyter-react';
+/**
+ * A toolbar item showing the notebook's kernel.
+ *
+ * Pushed to the trailing edge by a spacer, because it reports rather than
+ * acts: the buttons are what a person reaches for, and a status light sitting
+ * among them reads like one more thing to press.
+ *
+ * @param notebookId Notebook whose kernel to show.
+ */
+export declare function useKernelIndicatorToolbarItems(notebookId: string): ToolbarItem[];
+/**
+ * The toolbar every notebook example uses.
+ *
+ * `NotebookToolbar` with the kernel indicator added — passed as the
+ * `Toolbar` prop of `Notebook`, which hands it the notebook's id.
+ *
+ * Examples pass this rather than assembling the items themselves, so the
+ * indicator appears in the same place with the same behaviour in all of them,
+ * over a background in the colour of the theme the reader chose.
+ */
+export declare function ExampleNotebookToolbar({ notebookId, extraItems, ...rest }: INotebookToolbarProps): JSX.Element;
+export default useKernelIndicatorToolbarItems;

package/lib/examples/utils/notebookToolbarItems.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo } from 'react';
+import { KernelIndicator, NOTEBOOK_TOOLBAR_ITEM_ORDERS, NotebookToolbar, useNotebookStore, } from '@datalayer/jupyter-react';
+import { useThemeBrandColor } from './themedProvider';
+/** Trailing edge of the toolbar: past the last item the notebook contributes. */
+const KERNEL_INDICATOR_ORDER = NOTEBOOK_TOOLBAR_ITEM_ORDERS.cellType + 100;
+/**
+ * The kernel indicator for one notebook.
+ *
+ * A component rather than a value captured in the toolbar item, because a
+ * notebook gets its kernel *after* its toolbar first renders — the adapter is
+ * registered, then the kernel is attached, then it connects. Reading the store
+ * from inside the render means each of those steps reaches the indicator; a
+ * kernel captured when the item was built would stay `null` and the indicator
+ * would sit at an unknown state forever.
+ */
+function NotebookKernelIndicator({ notebookId, }) {
+    const notebookStore = useNotebookStore();
+    // Subscribing to the store means every adapter/kernel/status change
+    // re-renders this, which is what keeps the light honest.
+    const kernel = notebookStore.selectNotebookAdapter(notebookId)?.kernel ?? null;
+    return (_jsx(KernelIndicator, { kernel: kernel, 
+        // Borderless: the toolbar already draws the frame around it.
+        bordered: false }));
+}
+/**
+ * A toolbar item showing the notebook's kernel.
+ *
+ * Pushed to the trailing edge by a spacer, because it reports rather than
+ * acts: the buttons are what a person reaches for, and a status light sitting
+ * among them reads like one more thing to press.
+ *
+ * @param notebookId Notebook whose kernel to show.
+ */
+export function useKernelIndicatorToolbarItems(notebookId) {
+    return useMemo(() => [
+        {
+            key: 'notebook-kernel-indicator-spacer',
+            type: 'spacer',
+            order: KERNEL_INDICATOR_ORDER - 1,
+        },
+        {
+            key: 'notebook-kernel-indicator',
+            type: 'custom',
+            order: KERNEL_INDICATOR_ORDER,
+            group: 'kernel',
+            render: () => _jsx(NotebookKernelIndicator, { notebookId: notebookId }),
+        },
+    ], [notebookId]);
+}
+/**
+ * A colour at an opacity, whatever notation it was written in.
+ *
+ * Theme brand colours are hex, and mixing hex by hand is three lines of
+ * parsing; `color-mix` does it for any notation and is the fallback for
+ * anything that is not a plain `#rrggbb`.
+ */
+function tint(color, alpha) {
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
+    if (!hex) {
+        return `color-mix(in srgb, ${color} ${Math.round(alpha * 100)}%, transparent)`;
+    }
+    const digits = hex[1].length === 3
+        ? hex[1]
+            .split('')
+            .map(digit => digit + digit)
+            .join('')
+        : hex[1];
+    const value = parseInt(digits, 16);
+    // eslint-disable-next-line no-bitwise
+    return `rgba(${(value >> 16) & 255}, ${(value >> 8) & 255}, ${value & 255}, ${alpha})`;
+}
+/** The one stylesheet holding the toolbar's themed background. */
+const TOOLBAR_THEME_STYLE_ID = 'dla-example-notebook-toolbar-theme';
+/**
+ * Paint the notebook toolbars in the theme's colour.
+ *
+ * Through a stylesheet rather than a wrapper element, and that is not a
+ * stylistic preference — a wrapper is a bug here. `Notebook` renders the
+ * toolbar as a direct child of `#dla-Jupyter-Notebook`, a box of *fixed*
+ * height, and the toolbar keeps itself to one line by measuring the room it
+ * has with a `ResizeObserver` on itself **and on its parent**. Wrap it and the
+ * parent becomes a box whose height follows its content: the toolbar
+ * re-lays-out, the wrapper resizes, the observer fires, the toolbar
+ * re-lays-out — a render loop with no end. Styling it in place leaves the
+ * parent exactly as the notebook built it.
+ *
+ * Only the background is themed. The controls keep Primer's own colours: they
+ * are the things a person presses, and a toolbar whose buttons change hue with
+ * a theme picker reads as decoration rather than as controls.
+ */
+function useThemedToolbarBackground(brandColor) {
+    useEffect(() => {
+        if (typeof document === 'undefined') {
+            return;
+        }
+        let style = document.getElementById(TOOLBAR_THEME_STYLE_ID);
+        if (!style) {
+            style = document.createElement('style');
+            style.id = TOOLBAR_THEME_STYLE_ID;
+            document.head.appendChild(style);
+        }
+        // Scoped to the notebook's own container, so nothing else in the examples
+        // app picks the colour up by accident.
+        style.textContent = `
+      #dla-Jupyter-Notebook > [role='toolbar'] {
+        background: ${tint(brandColor, 0.09)};
+        border-bottom: 1px solid ${tint(brandColor, 0.24)};
+      }
+    `;
+    }, [brandColor]);
+}
+/**
+ * The toolbar every notebook example uses.
+ *
+ * `NotebookToolbar` with the kernel indicator added — passed as the
+ * `Toolbar` prop of `Notebook`, which hands it the notebook's id.
+ *
+ * Examples pass this rather than assembling the items themselves, so the
+ * indicator appears in the same place with the same behaviour in all of them,
+ * over a background in the colour of the theme the reader chose.
+ */
+export function ExampleNotebookToolbar({ notebookId, extraItems, ...rest }) {
+    const kernelItems = useKernelIndicatorToolbarItems(notebookId);
+    const items = useMemo(() => [...kernelItems, ...(extraItems ?? [])], [kernelItems, extraItems]);
+    useThemedToolbarBackground(useThemeBrandColor());
+    return (_jsx(NotebookToolbar, { notebookId: notebookId, extraItems: items, ...rest }));
+}
+export default useKernelIndicatorToolbarItems;

package/lib/examples/utils/runtimeTargetStore.d.ts

@@ -1,4 +1,35 @@
-export type ExampleRuntimeTarget = 'local' | 'cloud';
+/** Where the code runs. */
+export type ExampleRuntimeTarget = 
+/** Pyodide in this page, and the agent loop with it. */
+'browser'
+/** A local agent-runtimes server and the Jupyter server beside it. */
+ | 'local'
+/** An anonymous Jupyter server on prod1.datalayer.run. Sandbox only. */
+ | 'jupyter'
+/** An authenticated Datalayer agent runtime. */
+ | 'datalayer';
+/** What a target offers, so callers ask rather than special-case. */
+export interface RuntimeTargetCapabilities {
+    /** How to name it in the control. */
+    readonly label: string;
+    /** One line for the tooltip: what this actually is. */
+    readonly hint: string;
+    /** Whether an agent runs alongside the sandbox. */
+    readonly hasAgent: boolean;
+    /** Whether reaching it needs the person to be signed in. */
+    readonly requiresAuth: boolean;
+    /** Why the chat is off here, when it is. Empty when there is an agent. */
+    readonly noAgentReason: string;
+}
+/**
+ * The four targets, in the order the control shows them: nearest the person
+ * first, furthest last.
+ */
+export declare const RUNTIME_TARGETS: ReadonlyArray<ExampleRuntimeTarget>;
+/** What a target offers. */
+export declare function runtimeTargetCapabilities(target: ExampleRuntimeTarget): RuntimeTargetCapabilities;
+/** Whether an agent runs on this target — the question the chat asks. */
+export declare function targetHasAgent(target: ExampleRuntimeTarget): boolean;
 interface RuntimeTargetState {
     target: ExampleRuntimeTarget;
     setTarget: (target: ExampleRuntimeTarget) => void;
@@ -6,4 +37,12 @@ interface RuntimeTargetState {
 export declare const runtimeTargetStore: import("zustand").StoreApi<RuntimeTargetState>;
 export declare function useRuntimeTargetStore(): RuntimeTargetState;
 export declare function useRuntimeTargetStore<T>(selector: (state: RuntimeTargetState) => T): T;
+/**
+ * The current target and what it offers, in one read.
+ *
+ * This is what an example uses: it asks what it has, not where it is.
+ */
+export declare function useRuntimeTarget(): {
+    target: ExampleRuntimeTarget;
+} & RuntimeTargetCapabilities;
 export {};

package/lib/examples/utils/runtimeTargetStore.js

@@ -2,15 +2,87 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+/**
+ * Where an example's code runs, and whether an agent runs with it.
+ *
+ * Four positions rather than two, because "local or cloud" hid a second
+ * question a person actually has: is there an agent here at all? One of these
+ * targets is a sandbox and nothing else — an anonymous Jupyter server — and an
+ * example mounted on it can execute code but has nobody to talk to. Saying so
+ * in the model means the chat can be shown and switched off with a reason,
+ * rather than each example guessing.
+ *
+ * The browser used to be the second such target. It has an agent now: the loop
+ * turns in the page with the Vercel AI SDK, which needs no server behind it.
+ * The spec's own `harness` does not decide that — the location does, because
+ * the browser cannot turn a pydantic-ai loop whatever a spec asks for.
+ *
+ * The examples shell owns launching and switching. An example reads the target
+ * and what it offers; it never creates a runtime itself.
+ *
+ * @module examples/utils/runtimeTargetStore
+ */
 import { createStore } from 'zustand/vanilla';
 import { useStore } from 'zustand';
+/**
+ * The four targets, in the order the control shows them: nearest the person
+ * first, furthest last.
+ */
+export const RUNTIME_TARGETS = [
+    'browser',
+    'local',
+    'jupyter',
+    'datalayer',
+];
+const CAPABILITIES = {
+    browser: {
+        label: 'Browser',
+        hint: 'Python in this page (Pyodide), with the agent loop running here too — no runtime to allocate. Only the model is asked over the network.',
+        hasAgent: true,
+        // The agent needs none, but the model it asks does: the inference service
+        // holds the provider credentials and admits signed-in members only.
+        requiresAuth: true,
+        noAgentReason: '',
+    },
+    local: {
+        label: 'Local',
+        hint: 'An agent on your machine, with the Jupyter server beside it.',
+        hasAgent: true,
+        requiresAuth: false,
+        noAgentReason: '',
+    },
+    jupyter: {
+        label: 'Jupyter',
+        hint: 'An anonymous Jupyter server on prod1.datalayer.run. Sandbox only — no agent.',
+        hasAgent: false,
+        requiresAuth: false,
+        noAgentReason: 'No agent on an anonymous Jupyter server',
+    },
+    datalayer: {
+        label: 'Datalayer',
+        hint: 'An authenticated Datalayer agent runtime, with its sandbox.',
+        hasAgent: true,
+        requiresAuth: true,
+        noAgentReason: '',
+    },
+};
+/** What a target offers. */
+export function runtimeTargetCapabilities(target) {
+    return CAPABILITIES[target] ?? CAPABILITIES.local;
+}
+/** Whether an agent runs on this target — the question the chat asks. */
+export function targetHasAgent(target) {
+    return runtimeTargetCapabilities(target).hasAgent;
+}
 const STORAGE_KEY = 'agent-runtimes.examples.runtime-target';
+const isTarget = (value) => typeof value === 'string' &&
+    RUNTIME_TARGETS.includes(value);
 const readStoredTarget = () => {
     if (typeof window === 'undefined') {
         return 'local';
     }
     const value = window.localStorage.getItem(STORAGE_KEY);
-    return value === 'cloud' ? 'cloud' : 'local';
+    return isTarget(value) ? value : 'local';
 };
 export const runtimeTargetStore = createStore(set => ({
     target: readStoredTarget(),
@@ -25,3 +97,12 @@ export const runtimeTargetStore = createStore(set => ({
 export function useRuntimeTargetStore(selector) {
     return useStore(runtimeTargetStore, selector);
 }
+/**
+ * The current target and what it offers, in one read.
+ *
+ * This is what an example uses: it asks what it has, not where it is.
+ */
+export function useRuntimeTarget() {
+    const target = useRuntimeTargetStore(state => state.target);
+    return { target, ...runtimeTargetCapabilities(target) };
+}

package/lib/examples/utils/themedProvider.d.ts

@@ -42,4 +42,11 @@ export declare const ThemedProvider: React.FC<React.PropsWithChildren<Omit<IData
 export declare const useThemeBrandColor: () => string;
 export declare const ThemedJupyterProvider: React.FC<React.PropsWithChildren<{
     useJupyterReactTheme?: boolean;
+    /**
+     * Make the notebook fill this provider's container.
+     *
+     * Needed by any example whose notebook is sized `height="100%"` and whose
+     * sizing container is outside this provider. See {@link FILL_CONTAINER}.
+     */
+    fullHeight?: boolean;
 }>>;

package/lib/examples/utils/themedProvider.js

@@ -18,8 +18,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * and swap `<DatalayerThemeProvider>` → `<ThemedProvider>`.
  */
 import { useEffect } from 'react';
-import { DatalayerThemeProvider, themeConfigs, useThemeStore as usePrimerThemeStore, } from '@datalayer/primer-addons';
-import { JupyterReactTheme } from '@datalayer/jupyter-react';
+import { Box, DatalayerThemeProvider, themeConfigs, useThemeStore as usePrimerThemeStore, } from '@datalayer/primer-addons';
+// The lean `/core` entry: the theme without the component library.
+import { JupyterReactTheme } from '@datalayer/jupyter-react/core';
 import { useExampleThemeStore } from './themeStore';
 /**
  * Drop-in replacement for `<DatalayerThemeProvider>`.
@@ -37,6 +38,28 @@ export const ThemedProvider = ({ children, ...rest }) => {
     useEffect(() => {
         usePrimerThemeStore.setState({ theme: themeVariant, colorMode });
     }, [themeVariant, colorMode]);
+    // And the other way round. The reactor's `theme.toggleColorMode` command —
+    // the palette, Mod+Alt+C — and any primer-addons consumer move the
+    // singleton, not the examples' store; with only the mirror above, the chat
+    // (which reads the singleton) changed and the provider around everything
+    // else kept the old mode. Following the singleton here brings the header,
+    // the sidebar and every editor along on the first call. Through the
+    // store's setters rather than `setState`, so the active variant's saved
+    // preference moves too. No loop: the mirror above then writes back the same
+    // values, and equal values are not a change.
+    useEffect(() => usePrimerThemeStore.subscribe((state, previous) => {
+        if (state.colorMode === previous.colorMode &&
+            state.theme === previous.theme) {
+            return;
+        }
+        const example = useExampleThemeStore.getState();
+        if (example.colorMode !== state.colorMode) {
+            example.setColorMode(state.colorMode);
+        }
+        if (example.theme !== state.theme) {
+            example.setTheme(state.theme);
+        }
+    }), []);
     return (_jsx(DatalayerThemeProvider, { colorMode: rest.colorMode ?? colorMode, theme: rest.theme ?? cfg.primerTheme, themeStyles: rest.themeStyles ?? cfg.themeStyles, ...rest, children: children }));
 };
 /**
@@ -61,7 +84,36 @@ export const useThemeBrandColor = () => {
     const { theme: themeVariant } = useExampleThemeStore();
     return themeConfigs[themeVariant].brandColor;
 };
-export const ThemedJupyterProvider = ({ children, useJupyterReactTheme = true }) => {
+/**
+ * Give the notebook the container's height, however deep it sits.
+ *
+ * `DatalayerThemeProvider` renders Primer's `BaseStyles` and `JupyterReactTheme`
+ * renders a `div`, and neither has a height of its own. A `<Notebook
+ * height="100%">` inside them resolves against `auto` and collapses to nothing
+ * — present in the DOM, zero pixels tall, sitting at the bottom of the column.
+ *
+ * Sizing those wrappers by counting levels (`& > div > div`) was the first
+ * attempt and it is the wrong shape: it breaks the moment either provider adds
+ * or removes an element. Taking the notebook out of the flow instead makes the
+ * chain irrelevant — an absolutely positioned box resolves against the nearest
+ * *positioned* ancestor, which is the one wrapper here that is ours.
+ *
+ * `!important` because `Notebook` sets `position` and `height` in an inline
+ * `style`, which no stylesheet rule can otherwise outrank.
+ */
+const FILL_CONTAINER = {
+    position: 'relative',
+    height: '100%',
+    minHeight: 0,
+    '& #dla-Jupyter-Notebook': {
+        position: 'absolute !important',
+        top: '0 !important',
+        right: '0 !important',
+        bottom: '0 !important',
+        left: '0 !important',
+    },
+};
+export const ThemedJupyterProvider = ({ children, useJupyterReactTheme = true, fullHeight = false }) => {
     const { colorMode, theme: themeVariant } = useExampleThemeStore();
     const cfg = themeConfigs[themeVariant];
     // Resolve 'auto' to an actual mode so we can pick the right style set.
@@ -76,9 +128,10 @@ export const ThemedJupyterProvider = ({ children, useJupyterReactTheme = true })
     // Extract the canvas background from the theme's CSS-var overrides.
     const modeStyles = resolvedMode === 'dark' ? cfg.themeStyles.dark : cfg.themeStyles.light;
     const backgroundColor = modeStyles['--bgColor-default'];
-    return (_jsx(ThemedProvider, { children: useJupyterReactTheme ? (
+    const themed = (_jsx(ThemedProvider, { children: useJupyterReactTheme ? (
         // `ThemedProvider` (DatalayerThemeProvider) already applies Primer
         // BaseStyles with the branded theme font. Disable the inner BaseStyles
         // so Jupyter examples inherit that font instead of Primer's default.
         _jsx(JupyterReactTheme, { colormode: colorMode, backgroundColor: backgroundColor, useBaseStyles: false, children: children })) : (children) }));
+    return fullHeight ? _jsx(Box, { sx: FILL_CONTAINER, children: themed }) : themed;
 };

package/lib/examples/utils/useExampleAgentRuntimesUrl.js

@@ -4,6 +4,8 @@
  */
 import { useMemo } from 'react';
 import { useRuntimeTargetStore, } from './runtimeTargetStore';
+import { useAgentSummaryStore } from './agentSummaryStore';
+import { isLocalUrl } from './localUrl';
 const normalizeBaseUrl = (value) => {
     if (!value) {
         return undefined;
@@ -20,12 +22,31 @@ export function resolveExampleAgentRuntimesUrl(target, override) {
     if (override) {
         return normalizeBaseUrl(override) ?? override;
     }
-    const localUrl = normalizeBaseUrl(import.meta.env.VITE_DATALAYER_AGENT_RUNTIMES_URL) ??
-        LOCAL_DEFAULT;
-    const cloudUrl = normalizeBaseUrl(import.meta.env.VITE_DATALAYER_AGENT_RUNTIMES_URL) ??
+    const configured = normalizeBaseUrl(import.meta.env.VITE_DATALAYER_AGENT_RUNTIMES_URL);
+    /*
+     * The Local target's server runs on this machine, and only a URL that
+     * names this machine can be it.
+     *
+     * `VITE_DATALAYER_AGENT_RUNTIMES_URL` serves both targets, and the
+     * `examples:vite` script sets it to the cloud host by default — so taking
+     * it here unconditionally, which is what this used to do, answered "where
+     * is the local agent-runtimes server?" with `https://r1.datalayer.run`.
+     * The summary then read `Location: local` beside `Agent base URL:
+     * https://r1.datalayer.run`, every agent call was cross-origin, and the
+     * chat failed with a bare "Failed to fetch".
+     *
+     * `main.tsx` already learned this for the Jupyter server URL — see
+     * `isLocalUrl`, whose comment describes the same bug — and the predicate is
+     * shared so the two cannot drift apart again. An override that really is
+     * local (a different port, say) is still honoured.
+     */
+    const localUrl = configured && isLocalUrl(configured) ? configured : LOCAL_DEFAULT;
+    const cloudUrl = (configured && !isLocalUrl(configured) ? configured : undefined) ??
         normalizeBaseUrl(import.meta.env.VITE_DATALAYER_RUNTIMES_URL) ??
         CLOUD_DEFAULT;
-    return target === 'cloud' ? cloudUrl : localUrl;
+    // Only the Datalayer target reaches the hosted service; the rest are local
+    // or have no agent at all, and asking the cloud for one would be wrong.
+    return target === 'datalayer' ? cloudUrl : localUrl;
 }
 /**
  * Resolve the base URL used by examples to call the agent-runtimes service.
@@ -33,7 +54,11 @@ export function resolveExampleAgentRuntimesUrl(target, override) {
  */
 export function useExampleAgentRuntimesUrl(override) {
     const target = useRuntimeTargetStore(state => state.target);
+    const activeRuntimeBaseUrl = useAgentSummaryStore(state => state.active?.location === target ? state.active.baseUrl : undefined);
     return useMemo(() => {
+        if (target === 'datalayer' && activeRuntimeBaseUrl) {
+            return normalizeBaseUrl(activeRuntimeBaseUrl) ?? activeRuntimeBaseUrl;
+        }
         return resolveExampleAgentRuntimesUrl(target, override);
-    }, [target, override]);
+    }, [activeRuntimeBaseUrl, target, override]);
 }

package/lib/examples/utils/waitForAgent.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Wait for an agent the Loop is creating to exist on the server.
+ *
+ * The examples used to create their agent by hand and gate their sidebars on
+ * that request. Now the Loop creates the agent from the capacity plugin's
+ * blueprint when it mounts, so a page that wants to follow the agent over a
+ * websocket or read its spec asks the server until the agent answers.
+ *
+ * @module examples/utils/waitForAgent
+ */
+export interface WaitForAgentOptions {
+    /** Stops the wait; the promise then resolves `false`. */
+    signal?: AbortSignal;
+    /** Give up after this long (default 120 s). */
+    timeoutMs?: number;
+    /** Time between two asks (default 1.5 s). */
+    intervalMs?: number;
+    /** Headers for the ask, e.g. an Authorization header. */
+    headers?: Record<string, string>;
+}
+/** Resolves `true` once `GET /api/v1/agents/{id}` answers 200, `false` on timeout or abort. */
+export declare function waitForAgent(serverUrl: string, agentId: string, options?: WaitForAgentOptions): Promise<boolean>;
+export default waitForAgent;

package/lib/examples/utils/waitForAgent.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Resolves `true` once `GET /api/v1/agents/{id}` answers 200, `false` on timeout or abort. */
+export async function waitForAgent(serverUrl, agentId, options = {}) {
+    const { signal, timeoutMs = 120_000, intervalMs = 1_500, headers } = options;
+    const base = serverUrl.replace(/\/+$/, '');
+    const url = `${base}/api/v1/agents/${encodeURIComponent(agentId)}`;
+    const started = Date.now();
+    while (!signal?.aborted && Date.now() - started < timeoutMs) {
+        try {
+            const response = await fetch(url, { headers, signal });
+            if (response.ok)
+                return true;
+        }
+        catch {
+            // Not there, or the server is not up yet: ask again.
+        }
+        await new Promise(resolve => setTimeout(resolve, intervalMs));
+    }
+    return false;
+}
+export default waitForAgent;

package/lib/examples2/CellExample.d.ts

@@ -2,5 +2,5 @@ import { ServiceManager } from '@jupyterlab/services';
 type ICellExampleProps = {
     serviceManager?: ServiceManager.IManager;
 };
-export declare const CellExample: (props: ICellExampleProps) => import("react/jsx-runtime").JSX.Element;
+export declare const CellExample: (props: ICellExampleProps) => import("react").JSX.Element;
 export default CellExample;

package/lib/examples2/DatalayerNotebookExample.d.ts

@@ -12,5 +12,5 @@ import { ServiceManager } from '@jupyterlab/services';
 type IDatalayerNotebookExampleProps = {
     serviceManager?: ServiceManager.IManager;
 };
-declare const DatalayerNotebookExample: (props: IDatalayerNotebookExampleProps) => import("react/jsx-runtime").JSX.Element;
+declare const DatalayerNotebookExample: (props: IDatalayerNotebookExampleProps) => import("react").JSX.Element;
 export default DatalayerNotebookExample;

package/lib/examples2/NotebookExample.d.ts

@@ -2,5 +2,5 @@ import { ServiceManager } from '@jupyterlab/services';
 type INotebookExampleProps = {
     serviceManager?: ServiceManager.IManager;
 };
-export declare const NotebookExample: (props: INotebookExampleProps) => import("react/jsx-runtime").JSX.Element;
+export declare const NotebookExample: (props: INotebookExampleProps) => import("react").JSX.Element;
 export default NotebookExample;

package/lib/examples2/NotebookMutationsKernel.d.ts

@@ -1,2 +1,2 @@
-declare const NotebookMutationsKernel: () => import("react/jsx-runtime").JSX.Element;
+declare const NotebookMutationsKernel: () => import("react").JSX.Element;
 export default NotebookMutationsKernel;

package/lib/examples2/NotebookMutationsServiceManager.d.ts

@@ -1,2 +1,2 @@
-declare const NotebookMutationsServiceManager: () => import("react/jsx-runtime").JSX.Element;
+declare const NotebookMutationsServiceManager: () => import("react").JSX.Element;
 export default NotebookMutationsServiceManager;