@datalayer/agent-runtimes 1.0.4 → 1.0.6

package/lib/examples/main.js

@@ -1,19 +1,24 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 /*
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
 /// <reference types="vite/client" />
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import { createRoot } from 'react-dom/client';
 import { loadJupyterConfig, JupyterReactTheme, createServerSettings, setJupyterServerUrl, setJupyterServerToken, getJupyterServerUrl, getJupyterServerToken, } from '@datalayer/jupyter-react';
 import { ServiceManager } from '@jupyterlab/services';
-import { DatalayerThemeProvider, DatalayerLogo, getLogoColors, themeConfigs, Box, } from '@datalayer/primer-addons';
+import { DatalayerThemeProvider, DatalayerLogoText, getLogoColors, themeConfigs, Box, } from '@datalayer/primer-addons';
+import { HomeIcon, SignInIcon, SignOutIcon } from '@primer/octicons-react';
+import { Button } from '@primer/react';
 import { AppearanceControlsWithStore } from '@datalayer/primer-addons/lib/components/appearance';
 import { coreStore, iamStore, createDatalayerServiceManager, } from '@datalayer/core';
-import { useChatStore } from '../stores';
+import { SignInSimple } from '@datalayer/core/lib/views/iam';
+import { UserBadge } from '@datalayer/core/lib/views/profile';
+import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
+import { agentRuntimeStore, useChatStore, useConversationStore, } from '../stores';
 import { OAuthCallback } from '../identity';
-import { EXAMPLES } from './example-selector';
+import { EXAMPLES, getExampleEntries, } from './example-selector';
 import { useExampleThemeStore } from './utils/themeStore';
 import { ExampleWrapper } from './components/ExampleWrapper';
 import nbformatExample from './utils/notebooks/NotebookExample1.ipynb.json';
@@ -60,7 +65,7 @@ const loadConfigurations = () => {
                                 CLI: 0,
                                 VSCode: 0,
                             },
-                            position: {},
+                            position: 'top',
                             tours: {},
                         },
                         events: [],
@@ -91,13 +96,15 @@ const loadConfigurations = () => {
         }
     }
 };
-const getExampleNames = () => Object.keys(EXAMPLES);
+const getExampleEntriesList = () => getExampleEntries();
+const getInitialSearchQuery = () => {
+    const params = new URLSearchParams(window.location.search);
+    return (params.get('q') || '').trim();
+};
 // Check if we're on the notebook-only route
 const isNotebookOnlyRoute = () => {
     const path = window.location.pathname;
-    console.log('Current pathname:', path);
     const isNotebookRoute = path === '/datalayer/notebook';
-    console.log('Is notebook-only route:', isNotebookRoute);
     return isNotebookRoute;
 };
 // Check if we're handling an OAuth callback (code and state in URL params)
@@ -116,6 +123,34 @@ const getDefaultExampleName = () => {
     }
     return 'NotebookExample';
 };
+const parseJwtPayload = (token) => {
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts[1]) {
+        return null;
+    }
+    try {
+        const base64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
+        const decoded = atob(padded);
+        return JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+};
+const isExpiredJwt = (token) => {
+    const payload = parseJwtPayload(token);
+    if (!payload) {
+        // Non-JWT tokens (for example API keys) should not be treated as expired.
+        return false;
+    }
+    const exp = payload.exp;
+    if (typeof exp !== 'number') {
+        return false;
+    }
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    return nowSeconds >= exp;
+};
 // Notebook-only component for iframe display - renders ONLY the notebook without any UI chrome
 const NotebookOnlyApp = () => {
     const [serviceManager, setServiceManager] = useState(null);
@@ -139,7 +174,6 @@ const NotebookOnlyApp = () => {
                             runUrl: configuration.runUrl,
                             token: configuration.token,
                         });
-                        console.log('[NotebookOnlyApp] Created collaboration provider:', provider);
                         setCollaborationProvider(provider);
                     }
                     catch (error) {
@@ -193,11 +227,6 @@ const NotebookOnlyApp = () => {
         return null;
     }
     const NOTEBOOK_ID = '01JZQRQ35GG871QQCZW9TB1A8J';
-    console.log('[NotebookOnlyApp] Rendering with:', {
-        hasServiceManager: !!serviceManager,
-        hasCollaborationProvider: !!collaborationProvider,
-        notebookId: NOTEBOOK_ID,
-    });
     return (_jsx(JupyterReactTheme, { children: _jsx("div", { style: { width: '100vw', height: '100vh' }, children: _jsx(NotebookComponent, { id: NOTEBOOK_ID, height: "100vh", nbformat: nbformat, readonly: false, serviceManager: serviceManager, startDefaultKernel: true, collaborationProvider: collaborationProvider }) }) }));
 };
 // Main App component that loads and renders the selected example
@@ -207,7 +236,26 @@ export const ExampleApp = () => {
     const [error, setError] = useState(null);
     const [serviceManager, setServiceManager] = useState(null);
     const [selectedExample, setSelectedExample] = useState(getDefaultExampleName());
+    const [searchQuery, setSearchQuery] = useState(getInitialSearchQuery());
     const [isChangingExample, setIsChangingExample] = useState(false);
+    const filteredExampleEntries = useMemo(() => {
+        const normalized = searchQuery.trim().toLowerCase();
+        const all = getExampleEntriesList();
+        if (!normalized) {
+            return all;
+        }
+        return all.filter(entry => {
+            const haystack = [
+                entry.id,
+                entry.title,
+                entry.description,
+                entry.tags.join(' '),
+            ]
+                .join(' ')
+                .toLowerCase();
+            return haystack.includes(normalized);
+        });
+    }, [searchQuery]);
     const loadExample = async (exampleName, _manager) => {
         try {
             setIsChangingExample(true);
@@ -276,8 +324,75 @@ export const ExampleApp = () => {
     const handleExampleChange = async (newExample) => {
         if (newExample === selectedExample || !serviceManager)
             return;
-        // Clear chat store when changing examples to start fresh
-        useChatStore.getState().clearMessages();
+        // 1) Unmount the current example FIRST so its useEffect cleanup hooks
+        //    (e.g. AGUIAdapter.disconnect → /ag-ui/terminate, abort fetches,
+        //    close runtime sandboxes) run against a still-valid store state.
+        setIsChangingExample(true);
+        setExampleComponent(null);
+        // Yield to React so the unmount actually commits before we wipe stores.
+        await new Promise(resolve => {
+            requestAnimationFrame(() => resolve());
+        });
+        // 2) Tear down any server-side agents created by the previous example.
+        //    Each example caches its agent id in sessionStorage via
+        //    `uniqueAgentId(baseName)` under key `agent-runtimes:agentId:<base>`.
+        //    Delete those agents on the server and drop the cached ids so the
+        //    next example (and a future re-entry into this one) boots fresh.
+        const agentBaseUrl = import.meta.env.VITE_BASE_URL || 'http://localhost:8765';
+        const token = useSimpleAuthStore.getState().token;
+        const agentIdKeys = [];
+        try {
+            for (let i = 0; i < sessionStorage.length; i++) {
+                const key = sessionStorage.key(i);
+                if (key && key.startsWith('agent-runtimes:agentId:')) {
+                    agentIdKeys.push(key);
+                }
+            }
+        }
+        catch {
+            // sessionStorage unavailable; skip teardown.
+        }
+        await Promise.all(agentIdKeys.map(async (key) => {
+            let agentId = null;
+            try {
+                agentId = sessionStorage.getItem(key);
+            }
+            catch {
+                /* ignore */
+            }
+            if (!agentId)
+                return;
+            try {
+                await fetch(`${agentBaseUrl}/api/v1/agents/${encodeURIComponent(agentId)}`, {
+                    method: 'DELETE',
+                    headers: token ? { Authorization: `Bearer ${token}` } : {},
+                });
+            }
+            catch {
+                // Best-effort teardown: ignore network / 404 errors.
+            }
+            try {
+                sessionStorage.removeItem(key);
+            }
+            catch {
+                /* ignore */
+            }
+        }));
+        // 3) Wipe every piece of in-process agent state so the next example boots
+        //    with a clean slate (no leftover messages, threads, pending tool
+        //    calls, code sandbox snapshots, monitoring caches, or sockets).
+        useChatStore.getState().reset();
+        useConversationStore.getState().clearAll();
+        agentRuntimeStore.getState().reset();
+        // 4) Drop the persisted slice from localStorage so a fresh example never
+        //    rehydrates a previous example's agents / monitoring cache.
+        try {
+            localStorage.removeItem('agent-runtimes-storage');
+        }
+        catch {
+            // Ignore storage failures (e.g. private mode).
+        }
+        // 5) Load and mount the new example.
         setSelectedExample(newExample);
         localStorage.setItem('selectedExample', newExample);
         await loadExample(newExample, serviceManager);
@@ -297,16 +412,55 @@ export const ExampleApp = () => {
     if (serviceManager) {
         exampleProps.serviceManager = serviceManager;
     }
-    return (_jsx(ExampleAppThemed, { selectedExample: selectedExample, isChangingExample: isChangingExample, error: error, ExampleComponent: ExampleComponent, exampleProps: exampleProps, onExampleChange: handleExampleChange }));
+    exampleProps.examples = filteredExampleEntries.filter(entry => entry.id !== 'HomeExample');
+    exampleProps.searchQuery = searchQuery;
+    exampleProps.onSearchChange = (value) => setSearchQuery(value);
+    exampleProps.onSelectExample = (name) => {
+        void handleExampleChange(name);
+    };
+    return (_jsx(ExampleAppThemed, { selectedExample: selectedExample, isChangingExample: isChangingExample, error: error, ExampleComponent: ExampleComponent, exampleProps: exampleProps, onExampleChange: handleExampleChange, availableExamples: getExampleEntriesList() }));
 };
 /**
  * Inner shell that reads from the theme store and wires
  * DatalayerThemeProvider + the header bar with selectors.
  */
-const ExampleAppThemed = ({ selectedExample, isChangingExample, error, ExampleComponent, exampleProps, onExampleChange, }) => {
+const ExampleAppThemed = ({ selectedExample, isChangingExample, error, ExampleComponent, exampleProps, onExampleChange, availableExamples, }) => {
     const { colorMode, theme: themeVariant } = useExampleThemeStore();
     const cfg = themeConfigs[themeVariant];
     const logoColors = getLogoColors(themeVariant, colorMode);
+    const { token, setAuth, clearAuth } = useSimpleAuthStore();
+    const [showSignIn, setShowSignIn] = useState(false);
+    const shouldShowAuthScreen = showSignIn && !token;
+    const syncTokenToIamStore = useCallback((newToken) => {
+        import('@datalayer/core/lib/state').then(({ iamStore: coreIamStore }) => {
+            coreIamStore.setState({ token: newToken });
+        });
+    }, []);
+    useEffect(() => {
+        // Keep iamStore aligned with persisted auth token on app load/refresh.
+        syncTokenToIamStore(token || undefined);
+    }, [token, syncTokenToIamStore]);
+    useEffect(() => {
+        if (!token) {
+            setShowSignIn(true);
+            return;
+        }
+        if (isExpiredJwt(token)) {
+            clearAuth();
+            syncTokenToIamStore(undefined);
+            setShowSignIn(true);
+        }
+    }, [token, clearAuth, syncTokenToIamStore]);
+    const handleHeaderSignIn = useCallback((newToken, handle) => {
+        setAuth(newToken, handle);
+        syncTokenToIamStore(newToken);
+        setShowSignIn(false);
+    }, [setAuth, syncTokenToIamStore]);
+    const handleHeaderLogout = useCallback(() => {
+        clearAuth();
+        syncTokenToIamStore(undefined);
+        setShowSignIn(true);
+    }, [clearAuth, syncTokenToIamStore]);
     return (_jsx(DatalayerThemeProvider, { colorMode: colorMode, theme: cfg.primerTheme, themeStyles: cfg.themeStyles, children: _jsxs(Box, { sx: {
                 width: '100vw',
                 height: '100vh',
@@ -328,7 +482,19 @@ const ExampleAppThemed = ({ selectedExample, isChangingExample, error, ExampleCo
                         bg: 'canvas.subtle',
                         borderBottom: '1px solid',
                         borderColor: 'border.default',
-                    }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Box, { as: "select", value: selectedExample, onChange: (e) => onExampleChange(e.target.value), disabled: isChangingExample, sx: {
+                    }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Box, { as: "button", onClick: () => void onExampleChange('HomeExample'), title: "Home", "aria-label": "Go to examples home", sx: {
+                                        display: 'inline-flex',
+                                        alignItems: 'center',
+                                        justifyContent: 'center',
+                                        width: '32px',
+                                        height: '32px',
+                                        border: '1px solid',
+                                        borderColor: 'border.default',
+                                        borderRadius: 2,
+                                        bg: 'canvas.default',
+                                        color: 'fg.default',
+                                        cursor: isChangingExample ? 'not-allowed' : 'pointer',
+                                    }, disabled: isChangingExample, children: _jsx(HomeIcon, { size: 16 }) }), _jsx(Box, { as: "select", value: selectedExample, onChange: (e) => onExampleChange(e.target.value), disabled: isChangingExample, sx: {
                                         px: 2,
                                         py: '6px',
                                         fontSize: 1,
@@ -344,13 +510,80 @@ const ExampleAppThemed = ({ selectedExample, isChangingExample, error, ExampleCo
                                         '&:focus-visible': {
                                             boxShadow: '0 0 0 2px var(--bgColor-accent-muted, rgba(9,105,218,0.3))',
                                         },
-                                    }, children: getExampleNames()
-                                        .sort()
-                                        .map(name => (_jsx("option", { value: name, children: name }, name))) }), isChangingExample && (_jsx(Box, { as: "span", sx: { color: 'fg.muted', fontSize: 0 }, children: "Loading\u2026" })), error && (_jsxs(Box, { as: "span", sx: { color: 'danger.fg', fontSize: 0 }, children: ["Error: ", error] }))] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 3 }, children: [_jsx(AppearanceControlsWithStore, { useStore: useExampleThemeStore }), _jsx(DatalayerLogo, { size: 24, primaryColor: logoColors.primary, secondaryColor: logoColors.secondary })] })] }), _jsx(Box, { sx: {
+                                    }, children: (() => {
+                                        const home = availableExamples.find(e => e.id === 'HomeExample');
+                                        const rest = availableExamples.filter(e => e.id !== 'HomeExample');
+                                        // Classify each example into a named group.
+                                        const groupOf = (id) => {
+                                            if (id === 'AgentspecsExample')
+                                                return 'Personas';
+                                            if (id.startsWith('A2Ui'))
+                                                return 'A2UI';
+                                            if (id.startsWith('AgUi'))
+                                                return 'AG-UI';
+                                            if (id.startsWith('CopilotKit'))
+                                                return 'CopilotKit';
+                                            if (id.startsWith('Agent'))
+                                                return 'Agent';
+                                            if (id.startsWith('Chat'))
+                                                return 'Chat';
+                                            if (id.startsWith('Lexical'))
+                                                return 'Lexical';
+                                            if (id.startsWith('Notebook') ||
+                                                id === 'NotebookCollaborationExample')
+                                                return 'Notebook';
+                                            return 'Cell';
+                                        };
+                                        const groupOrder = [
+                                            'Personas',
+                                            'A2UI',
+                                            'AG-UI',
+                                            'Agent',
+                                            'Chat',
+                                            'Lexical',
+                                            'Notebook',
+                                            'Cell',
+                                            'CopilotKit',
+                                        ];
+                                        const grouped = new Map();
+                                        for (const ex of rest) {
+                                            const g = groupOf(ex.id);
+                                            if (!grouped.has(g))
+                                                grouped.set(g, []);
+                                            grouped.get(g).push(ex);
+                                        }
+                                        for (const list of grouped.values()) {
+                                            list.sort((a, b) => a.title.localeCompare(b.title));
+                                        }
+                                        const nodes = [];
+                                        if (home) {
+                                            nodes.push(_jsx("option", { value: home.id, disabled: home.id === selectedExample, children: home.title }, home.id));
+                                        }
+                                        let sepIndex = 0;
+                                        for (const g of groupOrder) {
+                                            const items = grouped.get(g);
+                                            if (!items || items.length === 0)
+                                                continue;
+                                            nodes.push(_jsxs("option", { disabled: true, value: `__sep_${sepIndex}`, children: ["\u2500\u2500\u2500\u2500\u2500\u2500 ", g, " \u2500\u2500\u2500\u2500\u2500\u2500"] }, `__sep_${sepIndex++}`));
+                                            for (const example of items) {
+                                                nodes.push(_jsx("option", { value: example.id, disabled: example.id === selectedExample, children: example.title }, example.id));
+                                            }
+                                        }
+                                        return _jsx(_Fragment, { children: nodes });
+                                    })() }), isChangingExample && (_jsx(Box, { as: "span", sx: { color: 'fg.muted', fontSize: 0 }, children: "Loading\u2026" })), error && (_jsxs(Box, { as: "span", sx: { color: 'danger.fg', fontSize: 0 }, children: ["Error: ", error] }))] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 3 }, children: [_jsx(AppearanceControlsWithStore, { useStore: useExampleThemeStore }), _jsx(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: token ? (_jsxs(_Fragment, { children: [_jsx(UserBadge, { token: token, variant: "small", onTokenExpired: () => {
+                                                    handleHeaderLogout();
+                                                    setShowSignIn(true);
+                                                } }), _jsx(Button, { size: "small", variant: "invisible", onClick: handleHeaderLogout, leadingVisual: SignOutIcon, sx: { color: 'fg.muted' }, children: "Sign out" })] })) : (_jsx(Button, { size: "small", variant: "invisible", onClick: () => setShowSignIn(true), leadingVisual: SignInIcon, sx: { color: 'fg.muted' }, children: "Sign in" })) }), _jsx(Box, { as: "a", href: "https://datalayer.ai", target: "_blank", rel: "noopener noreferrer", "aria-label": "Open Datalayer website", sx: { display: 'inline-flex', alignItems: 'center' }, children: _jsx(DatalayerLogoText, { size: 24, variant: themeVariant, colorMode: colorMode, primaryColor: logoColors.primary, secondaryColor: logoColors.secondary, textColor: logoColors.textColor, primaryGradient: logoColors.primaryGradient, secondaryGradient: logoColors.secondaryGradient, gradient: true }) })] })] }), _jsx(Box, { sx: {
                         marginTop: '60px',
                         height: 'calc(100vh - 60px)',
                         overflow: 'hidden',
-                    }, children: isChangingExample ? (_jsxs(Box, { sx: { p: 5, textAlign: 'center', color: 'fg.muted' }, children: [_jsxs("h3", { children: ["Loading ", selectedExample, "\u2026"] }), _jsx("p", { children: "Please wait while the example loads." })] })) : ExampleComponent ? (_jsx(ExampleWrapper, { children: _jsx(ExampleComponent, { ...exampleProps }) })) : null })] }) }));
+                    }, children: shouldShowAuthScreen ? (_jsx(Box, { sx: {
+                            width: '100%',
+                            height: '100%',
+                            bg: 'canvas.backdrop',
+                            p: 3,
+                            overflow: 'auto',
+                        }, children: _jsx(Box, { sx: { maxWidth: 640, mx: 'auto' }, children: _jsx(SignInSimple, { onSignIn: handleHeaderSignIn, onApiKeySignIn: apiKey => handleHeaderSignIn(apiKey, 'api-key-user'), title: "Agent Runtimes Examples", description: "Sign in to run authenticated examples and tools.", leadingIcon: _jsx(HomeIcon, { size: 24 }) }) }) })) : isChangingExample ? (_jsxs(Box, { sx: { p: 5, textAlign: 'center', color: 'fg.muted' }, children: [_jsxs("h3", { children: ["Loading ", selectedExample, "\u2026"] }), _jsx("p", { children: "Please wait while the example loads." })] })) : ExampleComponent ? (_jsx(ExampleWrapper, { children: _jsx(ExampleComponent, { ...exampleProps }, selectedExample) }, selectedExample)) : null })] }) }));
 };
 // Mount the app - check route to determine which app to render
 const root = document.getElementById('root');
@@ -359,15 +592,12 @@ if (root) {
         (window.__agentRuntimesExamplesRoot = createRoot(root));
     if (isOAuthCallback()) {
         // Handle OAuth callback - render OAuthCallback component
-        console.log('Rendering OAuthCallback (popup flow)');
         appRoot.render(_jsx(JupyterReactTheme, { children: _jsx(OAuthCallback, { autoClose: true, autoCloseDelay: 1000 }) }));
     }
     else if (isNotebookOnlyRoute()) {
-        console.log('Rendering NotebookOnlyApp');
         appRoot.render(_jsx(NotebookOnlyApp, {}));
     }
     else {
-        console.log('Rendering ExampleApp');
         appRoot.render(_jsx(ExampleApp, {}));
     }
 }

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

@@ -0,0 +1,18 @@
+import { type ReactComponentImplementation } from '@a2ui/react/v0_9';
+import { MessageProcessor, type A2uiClientAction, type A2uiMessage, type SurfaceModel } from '@a2ui/web_core/v0_9';
+export type A2uiProcessor = MessageProcessor<ReactComponentImplementation>;
+export type A2uiSurfaceModel = SurfaceModel<ReactComponentImplementation>;
+export declare function useA2uiProcessor(onAction?: (action: A2uiClientAction) => void): {
+    processor: MessageProcessor<ReactComponentImplementation>;
+    surfaces: A2uiSurfaceModel[];
+    processMessages: (messages: A2uiMessage[]) => void;
+    resetSurfaces: () => void;
+};
+export declare function createSceneMessages(args: {
+    surfaceId: string;
+    components: Array<Record<string, unknown>>;
+    value?: Record<string, unknown>;
+    path?: string;
+    theme?: Record<string, unknown>;
+    sendDataModel?: boolean;
+}): A2uiMessage[];

package/lib/examples/utils/a2ui.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { basicCatalog, } from '@a2ui/react/v0_9';
+import { MessageProcessor, } from '@a2ui/web_core/v0_9';
+export function useA2uiProcessor(onAction) {
+    const processor = useMemo(() => new MessageProcessor([basicCatalog], onAction), [onAction]);
+    const [surfaces, setSurfaces] = useState(() => Array.from(processor.model.surfacesMap.values()));
+    useEffect(() => {
+        const createdSub = processor.onSurfaceCreated(surface => {
+            setSurfaces(prev => [...prev, surface]);
+        });
+        const deletedSub = processor.onSurfaceDeleted(id => {
+            setSurfaces(prev => prev.filter(surface => surface.id !== id));
+        });
+        return () => {
+            createdSub.unsubscribe();
+            deletedSub.unsubscribe();
+        };
+    }, [processor]);
+    const processMessages = useCallback((messages) => {
+        processor.processMessages(messages);
+    }, [processor]);
+    const resetSurfaces = useCallback(() => {
+        Array.from(processor.model.surfacesMap.keys()).forEach(id => {
+            processor.model.deleteSurface(id);
+        });
+    }, [processor]);
+    return {
+        processor,
+        surfaces,
+        processMessages,
+        resetSurfaces,
+    };
+}
+export function createSceneMessages(args) {
+    const { surfaceId, components, value, path = '/', theme, sendDataModel = true, } = args;
+    const messages = [
+        {
+            version: 'v0.9',
+            createSurface: {
+                surfaceId,
+                catalogId: basicCatalog.id,
+                theme,
+                sendDataModel,
+            },
+        },
+        {
+            version: 'v0.9',
+            updateComponents: {
+                surfaceId,
+                components,
+            },
+        },
+    ];
+    if (value !== undefined) {
+        messages.push({
+            version: 'v0.9',
+            updateDataModel: {
+                surfaceId,
+                path,
+                value,
+            },
+        });
+    }
+    return messages;
+}

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

@@ -0,0 +1,7 @@
+import React from 'react';
+/**
+ * Provides the A2UI v0.9 markdown renderer to all child `A2uiSurface`
+ * instances. Without it, `Text` components fall back to the raw markdown
+ * string (e.g. `## Title` instead of a rendered `<h2>`).
+ */
+export declare const A2uiMarkdownProvider: React.FC<React.PropsWithChildren>;

package/lib/examples/utils/a2uiMarkdownProvider.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MarkdownContext } from '@a2ui/react/v0_9';
+import { renderMarkdown } from '@a2ui/markdown-it';
+/**
+ * Provides the A2UI v0.9 markdown renderer to all child `A2uiSurface`
+ * instances. Without it, `Text` components fall back to the raw markdown
+ * string (e.g. `## Title` instead of a rendered `<h2>`).
+ */
+export const A2uiMarkdownProvider = ({ children, }) => (_jsx(MarkdownContext.Provider, { value: renderMarkdown, children: children }));

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

@@ -0,0 +1,18 @@
+/**
+ * Build a unique agent ID by appending a random slug to a base name.
+ *
+ * The resulting id is cached in ``sessionStorage`` under a key derived from
+ * ``baseName``, so a browser refresh within the same tab reuses the same
+ * agent id.  This is required for server-side per-agent state (enabled
+ * tools, approved tools, approved skills, codemode status…) to survive a
+ * page reload — those maps are keyed by ``agent_id`` in
+ * ``agent_runtimes.streams.loop``.
+ *
+ * A fresh tab (or a ``sessionStorage.clear()``) produces a new id, which
+ * preserves the original "clean telemetry per run" guarantee.
+ *
+ * @example
+ *   uniqueAgentId('simple')           // → "simple-a3f7b2" (cached)
+ *   uniqueAgentId('codemode-demo')    // → "codemode-example-k9x2m1" (cached)
+ */
+export declare function uniqueAgentId(baseName: string): string;

package/lib/examples/utils/agentId.js

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Generate a short random alphanumeric slug (e.g. "a3f7b2").
+ * Used to make agent IDs unique per session so that each fresh
+ * example run starts with clean OTEL / telemetry data.
+ */
+function randomSlug(length = 6) {
+    const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    let slug = '';
+    const array = new Uint8Array(length);
+    crypto.getRandomValues(array);
+    for (let i = 0; i < length; i++) {
+        slug += chars[array[i] % chars.length];
+    }
+    return slug;
+}
+/**
+ * Build a unique agent ID by appending a random slug to a base name.
+ *
+ * The resulting id is cached in ``sessionStorage`` under a key derived from
+ * ``baseName``, so a browser refresh within the same tab reuses the same
+ * agent id.  This is required for server-side per-agent state (enabled
+ * tools, approved tools, approved skills, codemode status…) to survive a
+ * page reload — those maps are keyed by ``agent_id`` in
+ * ``agent_runtimes.streams.loop``.
+ *
+ * A fresh tab (or a ``sessionStorage.clear()``) produces a new id, which
+ * preserves the original "clean telemetry per run" guarantee.
+ *
+ * @example
+ *   uniqueAgentId('simple')           // → "simple-a3f7b2" (cached)
+ *   uniqueAgentId('codemode-demo')    // → "codemode-example-k9x2m1" (cached)
+ */
+export function uniqueAgentId(baseName) {
+    const storageKey = `agent-runtimes:agentId:${baseName}`;
+    try {
+        if (typeof sessionStorage !== 'undefined') {
+            const cached = sessionStorage.getItem(storageKey);
+            if (cached && cached.startsWith(`${baseName}-`)) {
+                return cached;
+            }
+            const fresh = `${baseName}-${randomSlug()}`;
+            sessionStorage.setItem(storageKey, fresh);
+            return fresh;
+        }
+    }
+    catch {
+        // sessionStorage unavailable (e.g. SSR, privacy mode); fall through.
+    }
+    return `${baseName}-${randomSlug()}`;
+}

package/lib/examples/utils/agents/earthquake-detector.json

@@ -1,13 +1,13 @@
 {
-    "id": "earthquake-detector",
-    "title": "Earthquake Detector",
-    "description": "Real-time seismic activity monitoring and earthquake alert system.",
-    "image": "https://images.unsplash.com/photo-1589519160732-57fc498494f8?w=300&h=150&fit=crop",
-    "author": "Eric Charles",
-    "editTimestamp": "53 minutes ago",
-    "status": "paused",
-    "transport": "ag-ui",
-    "avatarUrl": "https://avatars.githubusercontent.com/atom",
-    "stars": 4,
-    "notifications": 0
+  "id": "earthquake-detector",
+  "title": "Earthquake Detector",
+  "description": "Real-time seismic activity monitoring and earthquake alert system.",
+  "image": "https://images.unsplash.com/photo-1589519160732-57fc498494f8?w=300&h=150&fit=crop",
+  "author": "Eric Charles",
+  "editTimestamp": "53 minutes ago",
+  "status": "paused",
+  "transport": "ag-ui",
+  "avatarUrl": "https://avatars.githubusercontent.com/atom",
+  "stars": 4,
+  "notifications": 0
 }

package/lib/examples/utils/agents/sales-forecaster.json

@@ -1,13 +1,13 @@
 {
-    "id": "sales-forecaster",
-    "title": "Sales Forecaster",
-    "description": "AI-powered sales prediction and revenue forecasting tool.",
-    "image": "https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=300&h=150&fit=crop",
-    "author": "Eric Charles",
-    "editTimestamp": "1 hour ago",
-    "status": "running",
-    "transport": "vercel-ai",
-    "avatarUrl": "https://avatars.githubusercontent.com/github",
-    "stars": 5,
-    "notifications": 2
+  "id": "sales-forecaster",
+  "title": "Sales Forecaster",
+  "description": "AI-powered sales prediction and revenue forecasting tool.",
+  "image": "https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=300&h=150&fit=crop",
+  "author": "Eric Charles",
+  "editTimestamp": "1 hour ago",
+  "status": "running",
+  "transport": "vercel-ai",
+  "avatarUrl": "https://avatars.githubusercontent.com/github",
+  "stars": 5,
+  "notifications": 2
 }