@datalayer/agent-runtimes 1.0.2 → 1.0.4

package/lib/examples/AgentOtelExample.js

@@ -0,0 +1,281 @@
+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.
+ */
+/**
+ * AgentOtelExample
+ *
+ * Combines the Datalayer OTEL observability dashboard with an AI agent sidebar.
+ * The main view shows the same Live / SQL / System content as the standalone
+ * OTEL example (sourced from `@datalayer/core/views/otel`).  The right panel
+ * is a ChatSidebar whose agent is selected from the agent-runtimes library spec
+ * list and launched on demand.
+ *
+ * The OTEL backend is configured via `configuration.otelRunUrl` when available
+ * (falling back to `configuration.runUrl`, then `VITE_OTEL_BASE_URL`, then
+ * `VITE_DATALAYER_RUN_URL`, then https://prod1.datalayer.run).
+ * Agent routes use `VITE_BASE_URL` when provided, otherwise the same resolved
+ * direct run URL to avoid proxy-relative calls.
+ *
+ * For Python-side observability, wire in `agent_runtimes/otel.py`:
+ *   from agent_runtimes.otel import setup_otel
+ *   setup_otel(service_name="my-otel-demo")
+ */
+/// <reference types="vite/client" />
+import { useState, useEffect, useCallback, useRef, useMemo, } from 'react';
+import { Text, Button, Select, FormControl } from '@primer/react';
+import { TelescopeIcon, PlugIcon, XIcon } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+import { OtelHeader, DashboardView, SqlView, SystemView, useSimpleAuthStore, } from '@datalayer/core/lib/views/otel';
+import { SignInSimple } from '@datalayer/core/lib/views/iam';
+import { useCoreStore } from '@datalayer/core';
+import { ThemedProvider } from './utils/themedProvider';
+import { ChatSidebar } from '../chat';
+import { DEFAULT_MODEL } from '../specs';
+// ─── Environment / defaults ────────────────────────────────────────────────
+const OTEL_BASE_URL_ENV = import.meta.env.VITE_OTEL_BASE_URL ?? '';
+const DATALAYER_RUN_URL_ENV = import.meta.env.VITE_DATALAYER_RUN_URL ?? '';
+/**
+ * Base URL of the agent-runtimes server.
+ * Defaults to proxy-relative calls when VITE_BASE_URL is unset.
+ */
+const AGENT_BASE_URL_ENV = import.meta.env.VITE_BASE_URL || '';
+const DEFAULT_AGENT_PROTOCOL = 'vercel-ai';
+const DEFAULT_AGENT_LIBRARY = 'pydantic-ai';
+/**
+ * Small form for picking an agent spec and launching it.
+ * Renders as the `children` of the ChatSidebar so it appears above the chat.
+ */
+const AgentSelectorPanel = ({ baseUrl, onConnected, onDisconnected, isConnected, connectedAgentName, }) => {
+    const [specs, setSpecs] = useState([]);
+    const [selectedSpecId, setSelectedSpecId] = useState('');
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // Fetch library specs on mount
+    useEffect(() => {
+        const load = async () => {
+            try {
+                const res = await fetch(`${baseUrl}/api/v1/agents/library`);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const data = await res.json();
+                setSpecs(data);
+                if (data.length > 0)
+                    setSelectedSpecId(data[0].id);
+            }
+            catch (e) {
+                setError('Could not load agent specs from the backend.');
+                console.warn('[AgentOtelExample] Failed to load library specs:', e);
+            }
+        };
+        void load();
+    }, [baseUrl]);
+    const handleLaunch = useCallback(async () => {
+        if (!selectedSpecId)
+            return;
+        setLoading(true);
+        setError(null);
+        try {
+            const spec = specs.find(s => s.id === selectedSpecId);
+            const transport = spec?.transport ?? DEFAULT_AGENT_PROTOCOL;
+            const res = await fetch(`${baseUrl}/api/v1/agents`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    name: selectedSpecId,
+                    description: `Launched from AgentOtelExample`,
+                    agent_library: DEFAULT_AGENT_LIBRARY,
+                    transport,
+                    model: DEFAULT_MODEL,
+                    system_prompt: 'You are a helpful AI assistant observing OTEL telemetry data.',
+                    agent_spec_id: selectedSpecId,
+                }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ detail: 'Unknown error' }));
+                throw new Error(err.detail || `Failed to create agent: ${res.status}`);
+            }
+            const data = await res.json();
+            onConnected(data.id, transport);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e.message : 'Failed to launch agent');
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [selectedSpecId, specs, baseUrl, onConnected]);
+    if (isConnected) {
+        return (_jsxs(Box, { sx: {
+                px: 3,
+                py: 2,
+                borderBottom: '1px solid',
+                borderColor: 'border.default',
+                display: 'flex',
+                alignItems: 'center',
+                gap: 2,
+                flexShrink: 0,
+                bg: 'success.subtle',
+            }, children: [_jsx(PlugIcon, { size: 14 }), _jsx(Text, { sx: { fontSize: 1, flex: 1, color: 'success.fg' }, children: connectedAgentName ?? 'Agent connected' }), _jsx(Button, { size: "small", variant: "invisible", onClick: onDisconnected, leadingVisual: XIcon, sx: { color: 'fg.muted' }, children: "Disconnect" })] }));
+    }
+    return (_jsxs(Box, { sx: {
+            px: 3,
+            py: 2,
+            borderBottom: '1px solid',
+            borderColor: 'border.default',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 2,
+            flexShrink: 0,
+            bg: 'canvas.subtle',
+        }, children: [_jsx(Text, { sx: { fontSize: 0, fontWeight: 'bold', color: 'fg.muted' }, children: "SELECT AGENT" }), specs.length > 0 ? (_jsxs(_Fragment, { children: [_jsxs(FormControl, { children: [_jsx(FormControl.Label, { visuallyHidden: true, children: "Agent spec" }), _jsx(Select, { value: selectedSpecId, onChange: e => setSelectedSpecId(e.target.value), block: true, size: "small", disabled: loading, children: specs.map(s => (_jsx(Select.Option, { value: s.id, children: s.name ?? s.id }, s.id))) })] }), _jsx(Button, { variant: "primary", size: "small", onClick: handleLaunch, disabled: loading || !selectedSpecId, leadingVisual: PlugIcon, sx: { width: '100%' }, children: loading ? 'Launching…' : 'Launch Agent' })] })) : error ? (_jsx(Text, { sx: { fontSize: 1, color: 'danger.fg' }, children: error })) : (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Loading specs\u2026" })), error && specs.length > 0 && (_jsx(Text, { sx: { fontSize: 1, color: 'danger.fg' }, children: error }))] }));
+};
+const TAB_SX = (active) => ({
+    px: 3,
+    py: 2,
+    cursor: 'pointer',
+    fontSize: 1,
+    fontWeight: active ? 'bold' : 'normal',
+    color: active ? 'accent.fg' : 'fg.muted',
+    borderBottom: '2px solid',
+    borderColor: active ? 'accent.fg' : 'transparent',
+    '&:hover': { color: 'fg.default' },
+});
+const AgentOtelExampleInner = ({ token, onSignOut }) => {
+    const { configuration } = useCoreStore();
+    const resolvedRunUrl = configuration?.otelRunUrl ||
+        configuration?.runUrl ||
+        OTEL_BASE_URL_ENV ||
+        DATALAYER_RUN_URL_ENV ||
+        'https://prod1.datalayer.run';
+    const otelBaseUrl = resolvedRunUrl;
+    const agentBaseUrl = AGENT_BASE_URL_ENV;
+    // ── OTEL view state ─────────────────────────────────────────────
+    const [view, setView] = useState('dashboard');
+    const signalSetterRef = useRef(null);
+    const handleSignalRef = useCallback((setter) => {
+        signalSetterRef.current = setter;
+    }, []);
+    const handleNavigate = useCallback((signal) => {
+        setView('dashboard');
+        signalSetterRef.current?.(signal);
+    }, []);
+    // ── Agent state ─────────────────────────────────────────────────
+    const [connectedAgentId, setConnectedAgentId] = useState(null);
+    const [connectedAgentTransport, setConnectedAgentTransport] = useState(DEFAULT_AGENT_PROTOCOL);
+    const handleAgentConnected = useCallback((agentId, protocol) => {
+        setConnectedAgentId(agentId);
+        setConnectedAgentTransport(protocol);
+    }, []);
+    const handleAgentDisconnected = useCallback(async () => {
+        if (connectedAgentId) {
+            try {
+                await fetch(`${agentBaseUrl}/api/v1/agents/${connectedAgentId}`, {
+                    method: 'DELETE',
+                });
+            }
+            catch (e) {
+                console.warn('[AgentOtelExample] Failed to delete agent:', e);
+            }
+        }
+        setConnectedAgentId(null);
+    }, [connectedAgentId, agentBaseUrl]);
+    // Build protocol config from connected agent
+    const protocolConfig = useMemo(() => {
+        if (!connectedAgentId)
+            return undefined;
+        if (connectedAgentTransport === 'ag-ui') {
+            return {
+                type: 'ag-ui',
+                endpoint: `${agentBaseUrl}/api/v1/examples/${connectedAgentId}/`,
+                agentId: connectedAgentId,
+            };
+        }
+        if (connectedAgentTransport === 'a2a') {
+            return {
+                type: 'a2a',
+                endpoint: `${agentBaseUrl}/api/v1/a2a/${connectedAgentId}`,
+                agentId: connectedAgentId,
+            };
+        }
+        if (connectedAgentTransport === 'vercel-ai') {
+            return {
+                type: 'vercel-ai',
+                endpoint: `${agentBaseUrl}/api/v1/vercel-ai/${connectedAgentId}`,
+                agentId: connectedAgentId,
+            };
+        }
+        // Fallback – vercel-ai
+        return {
+            type: 'vercel-ai',
+            endpoint: `${agentBaseUrl}/api/v1/vercel-ai/${connectedAgentId}`,
+            agentId: connectedAgentId,
+        };
+    }, [connectedAgentId, connectedAgentTransport, agentBaseUrl]);
+    return (_jsxs(Box, { sx: {
+            display: 'flex',
+            flexDirection: 'column',
+            height: 'calc(100vh - 90px)',
+            overflow: 'hidden',
+            bg: 'canvas.default',
+            color: 'fg.default',
+        }, children: [_jsx(OtelHeader, { baseUrl: otelBaseUrl, token: token, onNavigate: handleNavigate, onSignOut: onSignOut, showGenerateButtons: false, trailing: _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(TelescopeIcon, { size: 16 }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: otelBaseUrl })] }) }), _jsxs(Box, { sx: {
+                    display: 'flex',
+                    flex: 1,
+                    minHeight: 0,
+                    overflow: 'hidden',
+                }, children: [_jsxs(Box, { sx: {
+                            display: 'flex',
+                            flexDirection: 'column',
+                            flex: 1,
+                            minWidth: 0,
+                            overflow: 'hidden',
+                        }, children: [_jsx(Box, { sx: {
+                                    display: 'flex',
+                                    alignItems: 'center',
+                                    px: 2,
+                                    bg: 'canvas.default',
+                                    borderBottom: '1px solid',
+                                    borderColor: 'border.default',
+                                    flexShrink: 0,
+                                }, children: ['dashboard', 'sql', 'system'].map(v => (_jsx(Box, { sx: TAB_SX(view === v), onClick: () => setView(v), children: _jsx(Text, { children: v === 'dashboard' ? 'Live' : v === 'sql' ? 'SQL' : 'System' }) }, v))) }), _jsx(Box, { sx: {
+                                    display: 'flex',
+                                    flex: 1,
+                                    minHeight: 0,
+                                    overflow: 'hidden',
+                                }, children: view === 'dashboard' ? (_jsx(DashboardView, { baseUrl: otelBaseUrl, wsBaseUrl: otelBaseUrl, token: token, autoRefreshMs: 5000, defaultSignal: "traces", limit: 200, onSignalRef: handleSignalRef })) : view === 'sql' ? (_jsx(SqlView, { baseUrl: otelBaseUrl, token: token })) : (_jsx(SystemView, { baseUrl: otelBaseUrl, token: token })) })] }), _jsx(ChatSidebar, { title: "AI Agent", protocol: protocolConfig, position: "right", width: 380, defaultOpen: true, showNewChatButton: true, showClearButton: true, showSettingsButton: false, clickOutsideToClose: false, placeholder: "Ask the agent about your telemetry data\u2026", description: "Connect an agent to start chatting about your traces, logs, and metrics.", panelProps: protocolConfig
+                            ? {
+                                protocol: protocolConfig,
+                                useStore: true,
+                                suggestions: [
+                                    {
+                                        title: '🔍 Recent traces',
+                                        message: 'What do the most recent traces show?',
+                                    },
+                                    {
+                                        title: '⚠️ Errors',
+                                        message: 'Are there any errors or anomalies in the telemetry?',
+                                    },
+                                    {
+                                        title: '📊 Metrics summary',
+                                        message: 'Give me a summary of the current metrics.',
+                                    },
+                                    {
+                                        title: '🕵️ Root cause',
+                                        message: 'Help me find the root cause of slow requests.',
+                                    },
+                                ],
+                            }
+                            : { useStore: true }, children: _jsx(AgentSelectorPanel, { baseUrl: agentBaseUrl, onConnected: handleAgentConnected, onDisconnected: handleAgentDisconnected, isConnected: !!connectedAgentId, connectedAgentName: connectedAgentId ?? undefined }) })] })] }));
+};
+/**
+ * AgentOtelExample – themed root with auth gate.
+ */
+const AgentOtelExample = () => {
+    const token = useSimpleAuthStore(s => s.token);
+    const setAuth = useSimpleAuthStore(s => s.setAuth);
+    const clearAuth = useSimpleAuthStore(s => s.clearAuth);
+    return (_jsx(ThemedProvider, { children: !token ? (_jsx(SignInSimple, { onSignIn: setAuth, onApiKeySignIn: apiKey => setAuth(apiKey, 'api-key-user'), title: "Datalayer OTEL", description: "Sign in to access the observability dashboard.", leadingIcon: _jsx(TelescopeIcon, { size: 24 }) })) : (_jsx(AgentOtelExampleInner, { token: token, onSignOut: clearAuth })) }));
+};
+export default AgentOtelExample;

package/lib/examples/AgentOutputsExample.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AgentOutputsExample
+ *
+ * Demonstrates rich output rendering for agent responses: structured data
+ * tables, charts, downloadable artifacts, and multi-format output panels.
+ *
+ * - Creates a cloud agent runtime (environment: 'ai-agents-env') via the Datalayer
+ *   Runtimes API and deploys an agent on its sidecar
+ * - Shows an output gallery alongside the chat with tabs for different
+ *   output formats (table, JSON, chart, file)
+ */
+import React from 'react';
+declare const AgentOutputsExample: React.FC;
+export default AgentOutputsExample;

package/lib/examples/AgentOutputsExample.js

@@ -0,0 +1,205 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * AgentOutputsExample
+ *
+ * Demonstrates rich output rendering for agent responses: structured data
+ * tables, charts, downloadable artifacts, and multi-format output panels.
+ *
+ * - Creates a cloud agent runtime (environment: 'ai-agents-env') via the Datalayer
+ *   Runtimes API and deploys an agent on its sidecar
+ * - Shows an output gallery alongside the chat with tabs for different
+ *   output formats (table, JSON, chart, file)
+ */
+/// <reference types="vite/client" />
+import { useEffect, useState, useCallback, useRef } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { Text, Button, Spinner, Heading, Label } from '@primer/react';
+import { TableIcon, FileIcon, CodeIcon, GraphIcon, DownloadIcon, SignOutIcon, } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+import { ErrorView } from './components';
+import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
+import { SignInSimple } from '@datalayer/core/lib/views/iam';
+import { UserBadge } from '@datalayer/core/lib/views/profile';
+import { ThemedProvider } from './utils/themedProvider';
+import { useAgents } from '../hooks/useAgents';
+import { Chat } from '../chat';
+const queryClient = new QueryClient();
+// ─── Constants ─────────────────────────────────────────────────────────────
+const AGENT_NAME = 'output-demo-agent';
+const AGENT_SPEC_ID = 'monitor-sales-kpis';
+// ─── Inner component (rendered after auth) ─────────────────────────────────
+const AgentOutputsInner = ({ onLogout, }) => {
+    const { token } = useSimpleAuthStore();
+    const { runtime, status: runtimeStatus, isReady, error: hookError, } = useAgents({
+        agentSpecId: AGENT_SPEC_ID,
+        autoStart: true,
+        agentConfig: {
+            name: AGENT_NAME,
+            protocol: 'ag-ui',
+            description: 'Agent with rich output rendering and artifact management',
+        },
+    });
+    const [activeTab, setActiveTab] = useState('table');
+    const [artifacts, setArtifacts] = useState([]);
+    const agentBaseUrl = runtime?.agentBaseUrl || '';
+    const agentId = runtime?.agentId || AGENT_NAME;
+    const podName = runtime?.podName || '(launching…)';
+    // Authenticated fetch helper
+    const authFetch = useCallback((url, opts = {}) => fetch(url, {
+        ...opts,
+        headers: {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            ...(opts.headers ?? {}),
+        },
+    }), [token]);
+    // ── Poll output artifacts ─────────────────────────────────────────────
+    useEffect(() => {
+        if (!isReady || !agentBaseUrl)
+            return;
+        const poll = async () => {
+            try {
+                const res = await authFetch(`${agentBaseUrl}/api/v1/agents/${agentId}/outputs`);
+                if (res.ok) {
+                    const d = await res.json();
+                    setArtifacts(Array.isArray(d) ? d : (d.artifacts ?? []));
+                }
+            }
+            catch {
+                /* ok */
+            }
+        };
+        poll();
+        const interval = setInterval(poll, 10_000);
+        return () => clearInterval(interval);
+    }, [isReady, agentBaseUrl, agentId, authFetch]);
+    // ── Loading / Error ───────────────────────────────────────────────────
+    if (!isReady && runtimeStatus !== 'error') {
+        return (_jsxs(Box, { sx: {
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                justifyContent: 'center',
+                height: '100vh',
+                gap: 3,
+            }, children: [_jsx(Spinner, { size: "large" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: runtimeStatus === 'launching'
+                        ? 'Launching runtime for output agent…'
+                        : 'Creating output demo agent…' })] }));
+    }
+    if (runtimeStatus === 'error' || hookError) {
+        return _jsx(ErrorView, { error: hookError, onLogout: onLogout });
+    }
+    const filtered = artifacts.filter(a => a.type === activeTab);
+    return (_jsxs(Box, { sx: {
+            height: 'calc(100vh - 60px)',
+            display: 'flex',
+            flexDirection: 'column',
+        }, children: [_jsxs(Box, { sx: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 2,
+                    px: 3,
+                    py: 2,
+                    borderBottom: '1px solid',
+                    borderColor: 'border.default',
+                    flexShrink: 0,
+                }, children: [_jsx(TableIcon, { size: 16 }), _jsxs(Heading, { as: "h3", sx: { fontSize: 2, flex: 1 }, children: ["Agent Outputs \u2014 ", podName] }), token && _jsx(UserBadge, { token: token, variant: "small" }), _jsx(Button, { size: "small", variant: "invisible", onClick: onLogout, leadingVisual: SignOutIcon, sx: { color: 'fg.muted' }, children: "Sign out" })] }), _jsxs(Box, { sx: { flex: 1, minHeight: 0, display: 'flex' }, children: [_jsx(Box, { sx: { flex: 1, minWidth: 0 }, children: _jsx(Chat, { protocol: "ag-ui", baseUrl: agentBaseUrl, agentId: agentId, title: "Output Agent", placeholder: "Ask the agent to generate reports, data, or files\u2026", description: `${artifacts.length} artifact${artifacts.length !== 1 ? 's' : ''} produced`, showHeader: true, autoFocus: true, height: "100%", runtimeId: podName, historyEndpoint: `${agentBaseUrl}/api/v1/history`, suggestions: [
+                                {
+                                    title: 'Generate report',
+                                    message: 'Generate a KPI summary report as a table',
+                                },
+                                {
+                                    title: 'Export JSON',
+                                    message: 'Export the latest sales data as JSON',
+                                },
+                            ], submitOnSuggestionClick: true }) }), _jsxs(Box, { sx: {
+                            width: 380,
+                            borderLeft: '1px solid',
+                            borderColor: 'border.default',
+                            display: 'flex',
+                            flexDirection: 'column',
+                            overflow: 'auto',
+                        }, children: [_jsx(Box, { sx: {
+                                    display: 'flex',
+                                    borderBottom: '1px solid',
+                                    borderColor: 'border.default',
+                                    flexShrink: 0,
+                                }, children: [
+                                    { key: 'table', icon: TableIcon, label: 'Table' },
+                                    { key: 'json', icon: CodeIcon, label: 'JSON' },
+                                    { key: 'chart', icon: GraphIcon, label: 'Chart' },
+                                    { key: 'files', icon: FileIcon, label: 'Files' },
+                                ].map(t => (_jsx(Button, { size: "small", variant: "invisible", leadingVisual: t.icon, onClick: () => setActiveTab(t.key), sx: {
+                                        flex: 1,
+                                        borderRadius: 0,
+                                        borderBottom: activeTab === t.key ? '2px solid' : '2px solid transparent',
+                                        borderColor: activeTab === t.key ? 'accent.fg' : 'transparent',
+                                        fontWeight: activeTab === t.key ? 'bold' : 'normal',
+                                    }, children: t.label }, t.key))) }), _jsxs(Box, { sx: { p: 3, flex: 1, overflow: 'auto' }, children: [_jsxs(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: [activeTab.charAt(0).toUpperCase() + activeTab.slice(1), " Outputs"] }), filtered.length === 0 ? (_jsxs(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: ["No ", activeTab, " outputs yet. Ask the agent to generate some."] })) : (filtered.map(art => (_jsxs(Box, { sx: {
+                                            p: 2,
+                                            mb: 2,
+                                            border: '1px solid',
+                                            borderColor: 'border.default',
+                                            borderRadius: 2,
+                                        }, children: [_jsxs(Box, { sx: {
+                                                    display: 'flex',
+                                                    justifyContent: 'space-between',
+                                                    alignItems: 'center',
+                                                    mb: 1,
+                                                }, children: [_jsx(Text, { sx: { fontSize: 1, fontWeight: 'bold' }, children: art.name }), _jsx(Label, { size: "small", variant: "secondary", children: art.size != null
+                                                            ? `${(art.size / 1024).toFixed(1)} KB`
+                                                            : activeTab })] }), art.preview && (_jsx(Box, { sx: {
+                                                    bg: 'canvas.subtle',
+                                                    p: 2,
+                                                    borderRadius: 2,
+                                                    fontFamily: 'mono',
+                                                    fontSize: 0,
+                                                    mb: 1,
+                                                    maxHeight: 120,
+                                                    overflow: 'auto',
+                                                    whiteSpace: 'pre-wrap',
+                                                }, children: art.preview })), _jsxs(Box, { sx: {
+                                                    display: 'flex',
+                                                    justifyContent: 'space-between',
+                                                    fontSize: 0,
+                                                    color: 'fg.muted',
+                                                }, children: [_jsx(Text, { children: new Date(art.timestamp).toLocaleString() }), _jsx(Button, { size: "small", variant: "invisible", leadingVisual: DownloadIcon, onClick: () => window.open(`${agentBaseUrl}/api/v1/agents/${agentId}/outputs/${art.id}/download`), children: "Download" })] })] }, art.id))))] })] })] })] }));
+};
+// ─── Sync token to core IAM store ──────────────────────────────────────────
+const syncTokenToIamStore = (token) => {
+    import('@datalayer/core/lib/state').then(({ iamStore }) => {
+        iamStore.setState({ token });
+    });
+};
+// ─── Main component with auth gate ─────────────────────────────────────────
+const AgentOutputsExample = () => {
+    const { token, setAuth, clearAuth } = useSimpleAuthStore();
+    const hasSynced = useRef(false);
+    useEffect(() => {
+        if (token && !hasSynced.current) {
+            hasSynced.current = true;
+            syncTokenToIamStore(token);
+        }
+    }, [token]);
+    const handleSignIn = useCallback((newToken, handle) => {
+        setAuth(newToken, handle);
+        hasSynced.current = true;
+        syncTokenToIamStore(newToken);
+    }, [setAuth]);
+    const handleLogout = useCallback(() => {
+        clearAuth();
+        hasSynced.current = false;
+        import('@datalayer/core/lib/state').then(({ iamStore }) => {
+            iamStore.setState({ token: undefined });
+        });
+    }, [clearAuth]);
+    if (!token) {
+        return (_jsx(ThemedProvider, { children: _jsx(SignInSimple, { onSignIn: handleSignIn, onApiKeySignIn: apiKey => handleSignIn(apiKey, 'api-key-user'), title: "Agent Outputs", description: "Sign in to view and manage agent output artifacts.", leadingIcon: _jsx(TableIcon, { size: 24 }) }) }));
+    }
+    return (_jsx(QueryClientProvider, { client: queryClient, children: _jsx(ThemedProvider, { children: _jsx(AgentOutputsInner, { onLogout: handleLogout }) }) }));
+};
+export default AgentOutputsExample;

package/lib/examples/AgentSandboxExample.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AgentSandboxExample
+ *
+ * Demonstrates sandbox variant switching (local-eval / jupyter) with a live
+ * sidebar that streams WebSocket messages to and from the
+ * `/configure/sandbox/ws` endpoint.
+ *
+ * - Creates a local agent (spec: demo-full) with codemode enabled
+ * - SegmentedControl toggles between "local-eval" and "jupyter" variants
+ * - Sidebar shows live sandbox status, WebSocket event log, and an
+ *   interrupt button
+ *
+ * @module examples/AgentSandboxExample
+ */
+import React from 'react';
+declare const AgentSandboxExample: React.FC;
+export default AgentSandboxExample;