@datalayer/agent-runtimes 1.0.10 → 1.0.17

package/lib/examples/index.js

@@ -3,9 +3,10 @@
  * Distributed under the terms of the Modified BSD License.
  */
 export { default as AgentspecsExample } from './AgentspecsExample';
-export { default as A2UiComponentGalleryExample } from './A2UiComponentGalleryExample';
+export { default as A2UiComponentsGalleryExample } from './A2UiComponentsGalleryExample';
 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 AgUiAgenticExample } from './AgUiAgenticExample';
 export { default as AgUiBackendToolRenderingExample } from './AgUiBackendToolRenderingExample';
@@ -25,6 +26,7 @@ export { default as AgentEvalsExample } from './AgentEvalsExample';
 export { default as AgentGuardrailsExample } from './AgentGuardrailsExample';
 export { default as AgentHooksExample } from './AgentHooksExample';
 export { default as AgentInferenceProviderExample } from './AgentInferenceProviderExample';
+export { default as AgentLoopExample } from './AgentLoopExample';
 export { default as AgentToolApprovalsExample } from './AgentToolApprovalsExample';
 export { default as AgentMemoryExample } from './AgentMemoryExample';
 export { default as AgentOtelExample } from './AgentOtelExample';

package/lib/examples/main.js

@@ -3,26 +3,57 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+import { createDatalayerServiceManager } from '../services/DatalayerServiceManager';
 /// <reference types="vite/client" />
 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, DatalayerLogoText, getLogoColors, themeConfigs, Box, } from '@datalayer/primer-addons';
+import { AgentSummary } from '../components';
 import { HomeIcon, SignInIcon, SignOutIcon } from '@primer/octicons-react';
-import { Button } from '@primer/react';
+import { Button, Spinner, Text } from '@primer/react';
 import { AppearanceControlsWithStore } from '@datalayer/primer-addons/lib/components/appearance';
-import { coreStore, iamStore, createDatalayerServiceManager, } from '@datalayer/core';
+import { coreStore, iamStore } from '@datalayer/core';
+import { DATALAYER_IAM_TOKEN_KEY, DATALAYER_IAM_USER_KEY, } from '../state/substates';
 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 { teardownExampleAgents } from './utils/teardownAgents';
 import { OAuthCallback } from '../identity';
 import { EXAMPLES, getExampleEntries, } from './example-selector';
+import { runtimeTargetStore, useRuntimeTargetStore, } from './utils/runtimeTargetStore';
+import { resolveExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { agentSummaryStore } from './utils/agentSummaryStore';
+import { useAgentSummaryStore } from './utils/agentSummaryStore';
 import { useExampleThemeStore } from './utils/themeStore';
 import { ExampleWrapper } from './components/ExampleWrapper';
+import { ExampleErrorBoundary } from './components/ExampleErrorBoundary';
 import nbformatExample from './utils/notebooks/NotebookExample1.ipynb.json';
 import '../../style/primer-primitives.css';
+const DEFAULT_RUNTIMES_URL = 'https://r1.datalayer.run';
+const resolveRuntimesUrl = (configured) => {
+    const envRuntimeUrl = import.meta.env.VITE_DATALAYER_RUNTIMES_URL;
+    const envBaseUrl = import.meta.env.VITE_DATALAYER_URL;
+    const candidate = configured || envRuntimeUrl || envBaseUrl;
+    if (!candidate) {
+        return DEFAULT_RUNTIMES_URL;
+    }
+    if (candidate.includes('prod1.datalayer.run')) {
+        return DEFAULT_RUNTIMES_URL;
+    }
+    return candidate.replace(/\/$/, '');
+};
+const toAgentRuntimesBaseUrl = (value) => {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().replace(/\/$/, '');
+    if (!normalized) {
+        return undefined;
+    }
+    return normalized;
+};
 // Load configurations from DOM
 const loadConfigurations = () => {
     // Load Datalayer configuration
@@ -38,7 +69,8 @@ const loadConfigurations = () => {
                     datalayerConfig.token = envToken;
                 }
             }
-            if (datalayerConfig.runUrl) {
+            if (datalayerConfig.datalayerUrl) {
+                datalayerConfig.runtimesUrl = resolveRuntimesUrl(datalayerConfig.runtimesUrl);
                 coreStore.getState().setConfiguration(datalayerConfig);
                 // Also set the token in the IAM store for API authentication
                 if (datalayerConfig.token) {
@@ -115,6 +147,150 @@ const isOAuthCallback = () => {
     const hasError = params.has('error');
     return (hasCode && hasState) || hasError;
 };
+const isIAMSocialCallback = () => {
+    const path = window.location.pathname;
+    const params = new URLSearchParams(window.location.search);
+    const isCallbackPath = /\/iam\/oauth2\/[^/]+\/callback$/.test(path);
+    return isCallbackPath && (params.has('token') || params.has('error'));
+};
+const resolveNavigationTarget = (params) => {
+    const candidate = params.get('navigate_to') ||
+        params.get('navigation') ||
+        params.get('post_auth_redirect') ||
+        params.get('redirect_url');
+    if (!candidate) {
+        return undefined;
+    }
+    const normalized = String(candidate).trim();
+    if (!normalized.startsWith('/') || normalized.startsWith('//')) {
+        return undefined;
+    }
+    if (/^\/iam\/oauth2\/[^/]+\/callback$/.test(normalized)) {
+        return undefined;
+    }
+    return normalized;
+};
+const parseUserFromCallback = (encodedUser) => {
+    if (!encodedUser) {
+        return undefined;
+    }
+    const attempts = [encodedUser];
+    try {
+        attempts.push(decodeURIComponent(encodedUser));
+    }
+    catch {
+        // ignore decode failure
+    }
+    if (attempts.length > 1) {
+        try {
+            attempts.push(decodeURIComponent(attempts[1]));
+        }
+        catch {
+            // ignore double decode failure
+        }
+    }
+    for (const candidate of attempts) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (parsed && typeof parsed === 'object') {
+                return parsed;
+            }
+        }
+        catch {
+            // keep trying
+        }
+    }
+    return undefined;
+};
+const AgentRuntimesIAMCallback = () => {
+    const [status, setStatus] = useState('processing');
+    const [message, setMessage] = useState('Finalizing social sign-in...');
+    useEffect(() => {
+        const params = new URLSearchParams(window.location.search);
+        const provider = window.location.pathname.match(/\/iam\/oauth2\/([^/]+)\/callback$/)?.[1] || '';
+        const token = params.get('token') || '';
+        const error = params.get('error') || '';
+        if (error) {
+            setStatus('error');
+            setMessage(error);
+            return;
+        }
+        if (!token) {
+            setStatus('error');
+            setMessage('Missing token in OAuth callback.');
+            return;
+        }
+        const callbackUser = parseUserFromCallback(params.get('user'));
+        const handle = String(callbackUser?.handle_s ||
+            callbackUser?.handle ||
+            callbackUser?.email_s ||
+            callbackUser?.email ||
+            'user').trim() || 'user';
+        const storedUser = {
+            uid: String(callbackUser?.uid || ''),
+            handle,
+            firstName: String(callbackUser?.first_name_t || callbackUser?.firstName || ''),
+            lastName: String(callbackUser?.last_name_t || callbackUser?.lastName || ''),
+            email: String(callbackUser?.email_s || callbackUser?.email || ''),
+            displayName: String(callbackUser?.display_name_t || callbackUser?.displayName || '').trim() || handle,
+            avatarUrl: String(callbackUser?.avatar_url_s || callbackUser?.avatarUrl || ''),
+            roles: Array.isArray(callbackUser?.roles_ss)
+                ? callbackUser?.roles_ss
+                : [],
+            setRoles: () => { },
+            iamProviders: [],
+            settings: {},
+            unsubscribedFromOutbounds: false,
+            onboarding: {
+                clients: {
+                    Platform: 0,
+                    JupyterLab: 0,
+                    CLI: 0,
+                    VSCode: 0,
+                },
+                position: 'top',
+                tours: {},
+            },
+            events: [],
+            initials: handle.slice(0, 2).toUpperCase(),
+            id: String(callbackUser?.uid || ''),
+        };
+        window.localStorage.setItem(DATALAYER_IAM_TOKEN_KEY, token);
+        window.localStorage.setItem(DATALAYER_IAM_USER_KEY, JSON.stringify(storedUser));
+        useSimpleAuthStore.getState().setAuth(token, handle);
+        iamStore.getState().setLogin(storedUser, token);
+        const providerAccessToken = provider
+            ? params.get(`${provider}_access_token`)
+            : null;
+        if (providerAccessToken &&
+            (provider === 'github' ||
+                provider === 'google' ||
+                provider === 'linkedin' ||
+                provider === 'okta' ||
+                provider === 'bluesky')) {
+            iamStore
+                .getState()
+                .setIAMProviderAccessToken(provider, providerAccessToken);
+        }
+        const target = resolveNavigationTarget(params);
+        if (target) {
+            window.location.replace(target);
+            return;
+        }
+        window.localStorage.setItem('selectedExample', 'HomeExample');
+        window.location.replace('/');
+    }, []);
+    return (_jsx(JupyterReactTheme, { children: _jsx(Box, { sx: {
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                minHeight: '100vh',
+                p: 3,
+            }, children: _jsxs(Box, { sx: { textAlign: 'center' }, children: [status === 'processing' ? _jsx(Spinner, { size: "large" }) : null, _jsx(Text, { as: "p", sx: {
+                            mt: 3,
+                            color: status === 'error' ? 'danger.fg' : 'fg.default',
+                        }, children: message })] }) }) }));
+};
 // Get the default example name from localStorage
 const getDefaultExampleName = () => {
     const stored = localStorage.getItem('selectedExample');
@@ -166,12 +342,12 @@ const NotebookOnlyApp = () => {
         const initializeApp = async () => {
             try {
                 const { configuration } = coreStore.getState();
-                // Always try to create collaboration provider if we have token and runUrl
-                if (configuration?.token && configuration?.runUrl) {
+                // Always try to create collaboration provider if we have token and datalayerUrl
+                if (configuration?.token && configuration?.datalayerUrl) {
                     try {
-                        const { DatalayerCollaborationProvider } = await import('@datalayer/core/lib/collaboration/DatalayerCollaborationProvider');
+                        const { DatalayerCollaborationProvider } = await import('../collaboration/DatalayerCollaborationProvider');
                         const provider = new DatalayerCollaborationProvider({
-                            runUrl: configuration.runUrl,
+                            datalayerUrl: configuration.datalayerUrl,
                             token: configuration.token,
                         });
                         setCollaborationProvider(provider);
@@ -181,7 +357,8 @@ const NotebookOnlyApp = () => {
                     }
                 }
                 // Create service manager
-                if (configuration?.token) {
+                if (runtimeTargetStore.getState().target === 'cloud' &&
+                    configuration?.token) {
                     try {
                         const manager = await createDatalayerServiceManager(configuration.cpuEnvironment || 'python-3.11', configuration.credits || 100);
                         await manager.ready;
@@ -238,6 +415,8 @@ export const ExampleApp = () => {
     const [selectedExample, setSelectedExample] = useState(getDefaultExampleName());
     const [searchQuery, setSearchQuery] = useState(getInitialSearchQuery());
     const [isChangingExample, setIsChangingExample] = useState(false);
+    const runtimeTarget = useRuntimeTargetStore(state => state.target);
+    const setRuntimeTarget = useRuntimeTargetStore(state => state.setTarget);
     const filteredExampleEntries = useMemo(() => {
         const normalized = searchQuery.trim().toLowerCase();
         const all = getExampleEntriesList();
@@ -274,38 +453,58 @@ export const ExampleApp = () => {
             setIsChangingExample(false);
         }
     };
+    const createLocalServiceManager = async () => {
+        const serverSettings = createServerSettings(getJupyterServerUrl(), getJupyterServerToken());
+        const manager = new ServiceManager({ serverSettings });
+        await manager.ready;
+        return manager;
+    };
+    const createCloudServiceManager = async () => {
+        const { configuration } = coreStore.getState();
+        if (!configuration?.token) {
+            throw new Error('Cloud runtime requires authentication. Please sign in.');
+        }
+        const activeSummary = agentSummaryStore.getState().active;
+        const selectedEntry = getExampleEntriesList().find(entry => entry.id === selectedExample);
+        const resolvedSpecId = activeSummary?.exampleId === selectedExample
+            ? activeSummary.specId
+            : undefined;
+        const runtimeDescriptor = resolvedSpecId || selectedEntry?.title || selectedExample;
+        const contextualRuntimeName = `Agent Runtime - ${runtimeDescriptor}`;
+        const manager = await createDatalayerServiceManager(configuration.cpuEnvironment || 'python-3.11', configuration.credits || 100, contextualRuntimeName);
+        await manager.ready;
+        return manager;
+    };
     useEffect(() => {
         // Load configurations
         loadConfigurations();
         // Create service manager and load example - must be sequential
         const initializeApp = async () => {
             try {
-                const { configuration } = coreStore.getState();
-                // Try to use DatalayerServiceManager if we have a token
-                if (configuration?.token) {
+                const runtimeTarget = runtimeTargetStore.getState().target;
+                // Only create a cloud Datalayer runtime when the user picked "cloud".
+                // In "local" mode we must never hit the cloud runtimes API.
+                if (runtimeTarget === 'cloud') {
                     try {
-                        const manager = await createDatalayerServiceManager(configuration.cpuEnvironment || 'python-3.11', configuration.credits || 100);
-                        await manager.ready;
+                        const manager = await createCloudServiceManager();
                         setServiceManager(manager);
                         // Load initial example
                         await loadExample(selectedExample, manager);
                     }
                     catch (error) {
                         console.error('Failed to create DatalayerServiceManager:', error);
-                        // Fall back to regular ServiceManager
-                        const serverSettings = createServerSettings(getJupyterServerUrl(), getJupyterServerToken());
-                        const manager = new ServiceManager({ serverSettings });
-                        await manager.ready;
+                        // Surface the failure in the UI, then fall back to local so the
+                        // app stays usable.
+                        setError(`Cloud runtime unavailable, using local instead: ${error instanceof Error ? error.message : String(error)}`);
+                        const manager = await createLocalServiceManager();
                         setServiceManager(manager);
                         // Load initial example
                         await loadExample(selectedExample, manager);
                     }
                 }
                 else {
-                    // Use regular ServiceManager (no Datalayer token)
-                    const serverSettings = createServerSettings(getJupyterServerUrl(), getJupyterServerToken());
-                    const manager = new ServiceManager({ serverSettings });
-                    await manager.ready;
+                    // Local runtime target (or no token): use the local Jupyter server.
+                    const manager = await createLocalServiceManager();
                     setServiceManager(manager);
                     // Load initial example
                     await loadExample(selectedExample, manager);
@@ -333,70 +532,51 @@ export const ExampleApp = () => {
         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';
+        // 2) Tear down any server-side agents created by the previous example and
+        //    wipe in-process agent state so the next example boots fresh.
+        const agentBaseUrl = resolveExampleAgentRuntimesUrl(runtimeTargetStore.getState().target);
         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.
+        await teardownExampleAgents(agentBaseUrl, token ?? undefined);
+        // 3) Load and mount the new example.
         setSelectedExample(newExample);
         localStorage.setItem('selectedExample', newExample);
         await loadExample(newExample, serviceManager);
     };
+    const handleRuntimeTargetChange = async (newTarget) => {
+        if (newTarget === runtimeTarget || !serviceManager)
+            return;
+        let nextManager;
+        try {
+            nextManager =
+                newTarget === 'cloud'
+                    ? await createCloudServiceManager()
+                    : await createLocalServiceManager();
+        }
+        catch (switchError) {
+            setError(`Failed to switch to ${newTarget}: ${switchError instanceof Error
+                ? switchError.message
+                : String(switchError)}`);
+            return;
+        }
+        // 1) Unmount the current example FIRST so its cleanup hooks run against the
+        //    still-valid OLD runtime (AG-UI disconnect, abort fetches, sandboxes).
+        setIsChangingExample(true);
+        setExampleComponent(null);
+        await new Promise(resolve => {
+            requestAnimationFrame(() => resolve());
+        });
+        // 2) Tear down the agents created on the OLD target, then wipe state so a
+        //    brand-new runtime is launched for the new target.
+        const oldAgentBaseUrl = resolveExampleAgentRuntimesUrl(runtimeTarget);
+        const token = useSimpleAuthStore.getState().token;
+        await teardownExampleAgents(oldAgentBaseUrl, token ?? undefined);
+        // 3) Switch the target and re-mount the example (its key includes the
+        //    target, so this launches/connects a fresh runtime).
+        setRuntimeTarget(newTarget);
+        setServiceManager(nextManager);
+        setError(null);
+        await loadExample(selectedExample, nextManager);
+    };
     if (loading) {
         return (_jsxs("div", { style: { padding: '20px', textAlign: 'center' }, children: [_jsxs("h2", { children: ["Loading Example: ", selectedExample] }), _jsx("p", { children: "Please wait..." })] }));
     }
@@ -418,24 +598,51 @@ export const ExampleApp = () => {
     exampleProps.onSelectExample = (name) => {
         void handleExampleChange(name);
     };
-    return (_jsx(ExampleAppThemed, { selectedExample: selectedExample, isChangingExample: isChangingExample, error: error, ExampleComponent: ExampleComponent, exampleProps: exampleProps, onExampleChange: handleExampleChange, availableExamples: getExampleEntriesList() }));
+    return (_jsx(ExampleAppThemed, { selectedExample: selectedExample, isChangingExample: isChangingExample, error: error, ExampleComponent: ExampleComponent, exampleProps: exampleProps, serviceManager: serviceManager, onExampleChange: handleExampleChange, onRuntimeTargetChange: handleRuntimeTargetChange, 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, availableExamples, }) => {
+const ExampleAppThemed = ({ selectedExample, isChangingExample, error, ExampleComponent, exampleProps, serviceManager, onExampleChange, onRuntimeTargetChange, availableExamples, }) => {
     const { colorMode, theme: themeVariant } = useExampleThemeStore();
+    const runtimeTarget = useRuntimeTargetStore(state => state.target);
+    const agentSummary = useAgentSummaryStore(state => state.active);
     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 }) => {
+        import('../state/substates').then(({ iamStore: coreIamStore }) => {
             coreIamStore.setState({ token: newToken });
         });
     }, []);
+    useEffect(() => {
+        const baseUrl = toAgentRuntimesBaseUrl(serviceManager?.serverSettings.baseUrl) ||
+            resolveExampleAgentRuntimesUrl(runtimeTarget);
+        // Seed a base summary for the selected example. Do NOT clobber a richer
+        // summary that the mounted example already published (spec id, agent id,
+        // readiness) for the same example + target — otherwise fast-settling local
+        // agents lose their spec/agent id in the indicator.
+        const current = agentSummaryStore.getState().active;
+        const alreadyEnriched = current != null &&
+            current.exampleId === selectedExample &&
+            current.location === runtimeTarget &&
+            (current.specId != null ||
+                current.agentId != null ||
+                current.isReady !== undefined);
+        if (alreadyEnriched) {
+            return;
+        }
+        agentSummaryStore.getState().setActive({
+            exampleId: selectedExample,
+            agentName: selectedExample,
+            location: runtimeTarget,
+            baseUrl,
+            status: isChangingExample ? 'switching' : 'selected',
+        });
+    }, [selectedExample, runtimeTarget, isChangingExample, serviceManager]);
     useEffect(() => {
         // Keep iamStore aligned with persisted auth token on app load/refresh.
         syncTokenToIamStore(token || undefined);
@@ -515,7 +722,7 @@ const ExampleAppThemed = ({ selectedExample, isChangingExample, error, ExampleCo
                                         const rest = availableExamples.filter(e => e.id !== 'HomeExample');
                                         // Classify each example into a named group.
                                         const groupOf = (id) => {
-                                            if (id === 'AgentspecsExample')
+                                            if (id === 'AgentspecsExample' || id === 'AgentLoopExample')
                                                 return 'Personas';
                                             if (id.startsWith('A2Ui'))
                                                 return 'A2UI';
@@ -548,12 +755,33 @@ const ExampleAppThemed = ({ selectedExample, isChangingExample, error, ExampleCo
                                         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);
+                                            const group = grouped.get(g);
+                                            if (group) {
+                                                group.push(ex);
+                                            }
+                                            else {
+                                                grouped.set(g, [ex]);
+                                            }
                                         }
-                                        for (const list of grouped.values()) {
-                                            list.sort((a, b) => a.title.localeCompare(b.title));
+                                        for (const [groupName, list] of grouped.entries()) {
+                                            if (groupName === 'Personas') {
+                                                const personaOrder = (id) => {
+                                                    if (id === 'AgentspecsExample')
+                                                        return 0;
+                                                    if (id === 'AgentLoopExample')
+                                                        return 1;
+                                                    return 2;
+                                                };
+                                                list.sort((a, b) => {
+                                                    const orderDelta = personaOrder(a.id) - personaOrder(b.id);
+                                                    if (orderDelta !== 0)
+                                                        return orderDelta;
+                                                    return a.title.localeCompare(b.title);
+                                                });
+                                            }
+                                            else {
+                                                list.sort((a, b) => a.title.localeCompare(b.title));
+                                            }
                                         }
                                         const nodes = [];
                                         if (home) {
@@ -570,7 +798,23 @@ const ExampleAppThemed = ({ selectedExample, isChangingExample, error, ExampleCo
                                             }
                                         }
                                         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: () => {
+                                    })() }), _jsxs(Box, { as: "select", value: runtimeTarget, onChange: (e) => void onRuntimeTargetChange(e.target.value), disabled: isChangingExample, "aria-label": "Runtime target", title: "Runtime target", sx: {
+                                        px: 2,
+                                        py: '6px',
+                                        fontSize: 1,
+                                        fontFamily: 'mono',
+                                        border: '1px solid',
+                                        borderColor: 'border.default',
+                                        borderRadius: 2,
+                                        bg: 'canvas.default',
+                                        color: 'fg.default',
+                                        cursor: isChangingExample ? 'not-allowed' : 'pointer',
+                                        minWidth: '120px',
+                                        outline: 'none',
+                                        '&:focus-visible': {
+                                            boxShadow: '0 0 0 2px var(--bgColor-accent-muted, rgba(9,105,218,0.3))',
+                                        },
+                                    }, children: [_jsx("option", { value: "local", children: "Local" }), _jsx("option", { value: "cloud", children: "Cloud" })] }), _jsx(AgentSummary, { summary: agentSummary }), 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: {
@@ -583,14 +827,17 @@ const ExampleAppThemed = ({ selectedExample, isChangingExample, error, ExampleCo
                             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 })] }) }));
+                        }, 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(ExampleErrorBoundary, { children: _jsx(ExampleWrapper, { children: _jsx(ExampleComponent, { ...exampleProps }, `${selectedExample}:${runtimeTarget}`) }, `${selectedExample}:${runtimeTarget}`) }, `${selectedExample}:${runtimeTarget}`)) : null })] }) }));
 };
 // Mount the app - check route to determine which app to render
 const root = document.getElementById('root');
 if (root) {
     const appRoot = window.__agentRuntimesExamplesRoot ??
         (window.__agentRuntimesExamplesRoot = createRoot(root));
-    if (isOAuthCallback()) {
+    if (isIAMSocialCallback()) {
+        appRoot.render(_jsx(AgentRuntimesIAMCallback, {}));
+    }
+    else if (isOAuthCallback()) {
         // Handle OAuth callback - render OAuthCallback component
         appRoot.render(_jsx(JupyterReactTheme, { children: _jsx(OAuthCallback, { autoClose: true, autoCloseDelay: 1000 }) }));
     }

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

@@ -1,3 +1,4 @@
+import type { CSSProperties } from 'react';
 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>;
@@ -7,6 +8,7 @@ export declare function useA2uiProcessor(onAction?: (action: A2uiClientAction) =
     surfaces: A2uiSurfaceModel[];
     processMessages: (messages: A2uiMessage[]) => void;
     resetSurfaces: () => void;
+    themeStyle: CSSProperties;
 };
 export declare function createSceneMessages(args: {
     surfaceId: string;