@datalayer/agent-runtimes 1.0.2 → 1.0.4

package/lib/examples/AgentMonitoringExample.js

@@ -0,0 +1,305 @@
+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.
+ */
+/**
+ * AgentMonitoringExample
+ *
+ * Demonstrates runtime and agent monitoring with a live metrics panel,
+ * health status, and recent alert history.
+ *
+ * - Creates a cloud agent runtime (environment: 'ai-agents-env') via the Datalayer
+ *   Runtimes API and deploys an agent on its sidecar
+ * - Shows a monitoring panel alongside the chat with key operational signals
+ */
+/// <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 { CheckCircleIcon, GraphIcon, SignOutIcon, } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+import { ErrorView } from './components';
+import { ThemedProvider } from './utils/themedProvider';
+const queryClient = new QueryClient();
+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 { Chat } from '../chat';
+import { useAgents } from '../hooks/useAgents';
+const AGENT_NAME = 'monitoring-demo-agent';
+const AGENT_SPEC_ID = 'monitor-sales-kpis';
+const clampPercent = (value) => Math.max(0, Math.min(100, value));
+const toNumber = (value, fallback) => {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : fallback;
+};
+const randomOffset = (range) => (Math.random() - 0.5) * range;
+const createSyntheticSnapshot = (previous) => {
+    const baseCpu = previous?.cpuPercent ?? 42;
+    const baseMemory = previous?.memoryPercent ?? 57;
+    const baseLatency = previous?.latencyMs ?? 320;
+    const baseErrorRate = previous?.errorRatePercent ?? 1.6;
+    const baseQueueDepth = previous?.queueDepth ?? 12;
+    const cpuPercent = clampPercent(baseCpu + randomOffset(10));
+    const memoryPercent = clampPercent(baseMemory + randomOffset(8));
+    const latencyMs = Math.max(30, baseLatency + randomOffset(120));
+    const errorRatePercent = clampPercent(baseErrorRate + randomOffset(0.8));
+    const queueDepth = Math.max(0, Math.round(baseQueueDepth + randomOffset(8)));
+    let status = 'healthy';
+    if (errorRatePercent > 4 || latencyMs > 1200 || cpuPercent > 90) {
+        status = 'critical';
+    }
+    else if (errorRatePercent > 2 || latencyMs > 700 || cpuPercent > 80) {
+        status = 'degraded';
+    }
+    return {
+        timestamp: new Date().toISOString(),
+        cpuPercent,
+        memoryPercent,
+        latencyMs,
+        errorRatePercent,
+        queueDepth,
+        status,
+    };
+};
+const normalizeSnapshot = (raw, previous) => {
+    if (!raw || typeof raw !== 'object') {
+        return createSyntheticSnapshot(previous);
+    }
+    const data = raw;
+    const snapshot = createSyntheticSnapshot(previous);
+    const statusValue = String(data.status ?? snapshot.status).toLowerCase();
+    const status = statusValue === 'healthy' ||
+        statusValue === 'degraded' ||
+        statusValue === 'critical'
+        ? statusValue
+        : 'unknown';
+    return {
+        timestamp: String(data.timestamp ?? new Date().toISOString()),
+        cpuPercent: clampPercent(toNumber(data.cpuPercent ?? data.cpu, snapshot.cpuPercent)),
+        memoryPercent: clampPercent(toNumber(data.memoryPercent ?? data.memory, snapshot.memoryPercent)),
+        latencyMs: Math.max(0, toNumber(data.latencyMs ?? data.latency, snapshot.latencyMs)),
+        errorRatePercent: clampPercent(toNumber(data.errorRatePercent ?? data.errorRate, snapshot.errorRatePercent)),
+        queueDepth: Math.max(0, Math.round(toNumber(data.queueDepth, snapshot.queueDepth))),
+        status,
+    };
+};
+const normalizeAlert = (raw, index) => {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const data = raw;
+    const severityValue = String(data.severity ?? 'info').toLowerCase();
+    const severity = severityValue === 'warning' || severityValue === 'critical'
+        ? severityValue
+        : 'info';
+    return {
+        id: String(data.id ?? `alert-${Date.now()}-${index}`),
+        title: String(data.title ?? 'Agent alert detected'),
+        severity,
+        timestamp: String(data.timestamp ?? new Date().toISOString()),
+    };
+};
+const statusVariant = (status) => {
+    if (status === 'healthy')
+        return 'success';
+    if (status === 'degraded')
+        return 'attention';
+    if (status === 'critical')
+        return 'danger';
+    return 'secondary';
+};
+const alertVariant = (severity) => {
+    if (severity === 'critical')
+        return 'danger';
+    if (severity === 'warning')
+        return 'attention';
+    return 'secondary';
+};
+const MetricRow = ({ label, value, percent }) => {
+    return (_jsxs(Box, { sx: { mb: 2 }, children: [_jsxs(Box, { sx: {
+                    display: 'flex',
+                    justifyContent: 'space-between',
+                    alignItems: 'center',
+                    mb: 1,
+                }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: label }), _jsx(Text, { sx: { fontSize: 0, fontWeight: 'bold' }, children: value })] }), _jsx(Box, { sx: {
+                    width: '100%',
+                    height: 8,
+                    bg: 'canvas.subtle',
+                    borderRadius: 6,
+                    overflow: 'hidden',
+                }, children: _jsx(Box, { sx: {
+                        width: `${clampPercent(percent)}%`,
+                        height: '100%',
+                        bg: percent >= 85 ? 'danger.emphasis' : 'accent.emphasis',
+                        transition: 'width 300ms ease-out',
+                    } }) })] }));
+};
+const AgentMonitoringInner = ({ 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 runtime and alert monitoring signals',
+        },
+    });
+    const [snapshots, setSnapshots] = useState([]);
+    const [alerts, setAlerts] = useState([]);
+    const agentBaseUrl = runtime?.agentBaseUrl || '';
+    const agentId = runtime?.agentId || AGENT_NAME;
+    const podName = runtime?.podName || '(launching…)';
+    const authFetch = useCallback((url, opts = {}) => fetch(url, {
+        ...opts,
+        headers: {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            ...(opts.headers ?? {}),
+        },
+    }), [token]);
+    useEffect(() => {
+        if (!isReady || !agentBaseUrl)
+            return;
+        const poll = async () => {
+            let nextSnapshot = null;
+            let nextAlerts = null;
+            try {
+                const res = await authFetch(`${agentBaseUrl}/api/v1/agents/${agentId}/monitoring`);
+                if (res.ok) {
+                    const data = await res.json();
+                    const rawSnapshot = data?.snapshot ?? data?.metrics ?? data;
+                    nextAlerts = Array.isArray(data?.alerts)
+                        ? data.alerts
+                            .map((a, i) => normalizeAlert(a, i))
+                            .filter((a) => !!a)
+                            .slice(0, 25)
+                        : [];
+                    setSnapshots(prev => {
+                        nextSnapshot = normalizeSnapshot(rawSnapshot, prev[0]);
+                        return [nextSnapshot, ...prev].slice(0, 40);
+                    });
+                    if (nextAlerts) {
+                        setAlerts(nextAlerts);
+                    }
+                    return;
+                }
+            }
+            catch {
+                // Keep UI responsive with synthetic values when endpoint is unavailable.
+            }
+            setSnapshots(prev => {
+                if (prev.length > 0) {
+                    return prev;
+                }
+                return [createSyntheticSnapshot()];
+            });
+        };
+        poll();
+        const interval = window.setInterval(poll, 10_000);
+        return () => window.clearInterval(interval);
+    }, [isReady, agentBaseUrl, agentId, authFetch]);
+    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 monitoring agent…'
+                        : 'Creating monitoring demo agent…' })] }));
+    }
+    if (runtimeStatus === 'error' || hookError) {
+        return _jsx(ErrorView, { error: hookError, onLogout: onLogout });
+    }
+    const latest = snapshots[0] ?? createSyntheticSnapshot();
+    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(GraphIcon, { size: 16 }), _jsxs(Heading, { as: "h3", sx: { fontSize: 2, flex: 1 }, children: ["Monitoring \u2014 ", podName] }), _jsx(Label, { variant: statusVariant(latest.status), size: "small", children: latest.status }), 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: "Monitoring Agent", placeholder: "Ask about performance, latency, and alert trends\u2026", description: `${alerts.length} active alert${alerts.length !== 1 ? 's' : ''}`, showHeader: true, autoFocus: true, height: "100%", runtimeId: podName, historyEndpoint: `${agentBaseUrl}/api/v1/history`, suggestions: [
+                                {
+                                    title: 'Health summary',
+                                    message: 'Summarize current agent health and key bottlenecks',
+                                },
+                                {
+                                    title: 'Alert triage',
+                                    message: 'List critical alerts first and suggest immediate mitigations',
+                                },
+                            ], submitOnSuggestionClick: true }) }), _jsxs(Box, { sx: {
+                            width: 380,
+                            borderLeft: '1px solid',
+                            borderColor: 'border.default',
+                            display: 'flex',
+                            flexDirection: 'column',
+                            overflow: 'auto',
+                        }, children: [_jsxs(Box, { sx: {
+                                    p: 3,
+                                    borderBottom: '1px solid',
+                                    borderColor: 'border.default',
+                                }, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: "Live Metrics" }), _jsx(MetricRow, { label: "CPU", value: `${latest.cpuPercent.toFixed(1)}%`, percent: latest.cpuPercent }), _jsx(MetricRow, { label: "Memory", value: `${latest.memoryPercent.toFixed(1)}%`, percent: latest.memoryPercent }), _jsx(MetricRow, { label: "Latency", value: `${Math.round(latest.latencyMs)} ms`, percent: (latest.latencyMs / 2000) * 100 }), _jsx(MetricRow, { label: "Error Rate", value: `${latest.errorRatePercent.toFixed(2)}%`, percent: latest.errorRatePercent * 20 }), _jsx(MetricRow, { label: "Queue Depth", value: `${latest.queueDepth}`, percent: latest.queueDepth })] }), _jsxs(Box, { sx: { p: 3, flex: 1, overflow: 'auto' }, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: "Recent Alerts" }), alerts.length === 0 ? (_jsxs(Box, { sx: {
+                                            p: 2,
+                                            border: '1px solid',
+                                            borderColor: 'border.default',
+                                            borderRadius: 2,
+                                            display: 'flex',
+                                            alignItems: 'center',
+                                            gap: 2,
+                                        }, children: [_jsx(CheckCircleIcon, { size: 16 }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "No active alerts." })] })) : (alerts.map(alert => (_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: alert.title }), _jsx(Label, { size: "small", variant: alertVariant(alert.severity), children: alert.severity })] }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: new Date(alert.timestamp).toLocaleString() })] }, alert.id))))] })] })] })] }));
+};
+const syncTokenToIamStore = (token) => {
+    import('@datalayer/core/lib/state').then(({ iamStore }) => {
+        iamStore.setState({ token });
+    });
+};
+const AgentMonitoringExample = () => {
+    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 Monitoring", description: "Sign in to monitor runtime health and alerts.", leadingIcon: _jsx(GraphIcon, { size: 24 }) }) }));
+    }
+    return (_jsx(QueryClientProvider, { client: queryClient, children: _jsx(ThemedProvider, { children: _jsx(AgentMonitoringInner, { onLogout: handleLogout }) }) }));
+};
+export default AgentMonitoringExample;

package/lib/examples/AgentNotificationsExample.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AgentNotificationsExample
+ *
+ * Demonstrates notification channels for agents: in-app toasts, email digests,
+ * Slack webhook integrations, and notification preference management.
+ *
+ * - Creates a cloud agent runtime (environment: 'ai-agents-env') via the Datalayer
+ *   Runtimes API and deploys an agent on its sidecar
+ * - Shows a notification center alongside the chat where users can configure
+ *   channels and review recent notifications
+ */
+import React from 'react';
+declare const AgentNotificationsExample: React.FC;
+export default AgentNotificationsExample;

package/lib/examples/AgentNotificationsExample.js

@@ -0,0 +1,267 @@
+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.
+ */
+/**
+ * AgentNotificationsExample
+ *
+ * Demonstrates notification channels for agents: in-app toasts, email digests,
+ * Slack webhook integrations, and notification preference management.
+ *
+ * - Creates a cloud agent runtime (environment: 'ai-agents-env') via the Datalayer
+ *   Runtimes API and deploys an agent on its sidecar
+ * - Shows a notification center alongside the chat where users can configure
+ *   channels and review recent notifications
+ */
+/// <reference types="vite/client" />
+import { useEffect, useState, useCallback, useRef } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { Text, Button, Spinner, Heading, Label, TextInput, Flash, Timeline, } from '@primer/react';
+import { AlertIcon, BellIcon, MailIcon, CheckCircleIcon, MuteIcon, SignOutIcon, } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+import { ErrorView } from './components';
+import { ThemedProvider } from './utils/themedProvider';
+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 { Chat } from '../chat';
+import { useAgents } from '../hooks/useAgents';
+const queryClient = new QueryClient();
+// ─── Constants ─────────────────────────────────────────────────────────────
+const AGENT_NAME = 'notification-demo-agent';
+const AGENT_SPEC_ID = 'monitor-sales-kpis';
+// ─── Inner component (rendered after auth) ─────────────────────────────────
+const AgentNotificationsInner = ({ 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 multi-channel notification support',
+        },
+    });
+    const [notifications, setNotifications] = useState([]);
+    const [channels, setChannels] = useState([
+        { channel: 'in-app', enabled: true },
+        { channel: 'email', enabled: false, target: '' },
+        { channel: 'slack', enabled: false, target: '' },
+    ]);
+    const [editTargets, setEditTargets] = useState({});
+    const [isSaving, setIsSaving] = useState(false);
+    const [flash, setFlash] = useState(null);
+    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 notifications ────────────────────────────────────────────────
+    useEffect(() => {
+        if (!isReady || !agentBaseUrl)
+            return;
+        const poll = async () => {
+            try {
+                const res = await authFetch(`${agentBaseUrl}/api/v1/agents/${agentId}/notifications`);
+                if (res.ok) {
+                    const d = await res.json();
+                    setNotifications(Array.isArray(d) ? d : (d.notifications ?? []));
+                }
+            }
+            catch {
+                /* ok */
+            }
+            try {
+                const res = await authFetch(`${agentBaseUrl}/api/v1/agents/${agentId}/notifications/channels`);
+                if (res.ok) {
+                    const d = await res.json();
+                    if (Array.isArray(d))
+                        setChannels(d);
+                }
+            }
+            catch {
+                /* ok */
+            }
+        };
+        poll();
+        const interval = setInterval(poll, 10_000);
+        return () => clearInterval(interval);
+    }, [isReady, agentBaseUrl, agentId, authFetch]);
+    // ── Toggle / save channel ─────────────────────────────────────────────
+    const handleToggleChannel = useCallback(async (ch) => {
+        if (!agentBaseUrl)
+            return;
+        const current = channels.find(c => c.channel === ch);
+        if (!current)
+            return;
+        setIsSaving(true);
+        try {
+            const res = await authFetch(`${agentBaseUrl}/api/v1/agents/${agentId}/notifications/channels`, {
+                method: 'PUT',
+                body: JSON.stringify({
+                    channel: ch,
+                    enabled: !current.enabled,
+                    target: editTargets[ch] ?? current.target,
+                }),
+            });
+            if (res.ok) {
+                setChannels(prev => prev.map(c => c.channel === ch
+                    ? {
+                        ...c,
+                        enabled: !c.enabled,
+                        target: editTargets[ch] ?? c.target,
+                    }
+                    : c));
+            }
+        }
+        catch {
+            /* ok */
+        }
+        finally {
+            setIsSaving(false);
+        }
+    }, [agentBaseUrl, agentId, channels, editTargets, authFetch]);
+    // ── Send test notification ────────────────────────────────────────────
+    const handleTestNotification = useCallback(async () => {
+        if (!agentBaseUrl)
+            return;
+        setFlash(null);
+        try {
+            const res = await authFetch(`${agentBaseUrl}/api/v1/agents/${agentId}/notifications/test`, { method: 'POST' });
+            if (res.ok) {
+                setFlash('Test notification sent');
+            }
+            else {
+                setFlash(`Failed (${res.status})`);
+            }
+        }
+        catch {
+            setFlash('Network error');
+        }
+    }, [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 notification agent…'
+                        : 'Creating notification demo agent…' })] }));
+    }
+    if (runtimeStatus === 'error' || hookError) {
+        return _jsx(ErrorView, { error: hookError, onLogout: onLogout });
+    }
+    const unreadCount = notifications.filter(n => !n.read).length;
+    const channelIcon = (ch) => {
+        switch (ch) {
+            case 'in-app':
+                return BellIcon;
+            case 'email':
+                return MailIcon;
+            case 'slack':
+                return AlertIcon; // placeholder for Slack icon
+        }
+    };
+    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(BellIcon, { size: 16 }), _jsxs(Heading, { as: "h3", sx: { fontSize: 2, flex: 1 }, children: ["Notifications \u2014 ", podName] }), unreadCount > 0 && (_jsxs(Label, { variant: "accent", size: "small", children: [unreadCount, " unread"] })), 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: "Notification Agent", placeholder: "Ask the agent to send you notifications\u2026", description: `${unreadCount} unread notification${unreadCount !== 1 ? 's' : ''}`, showHeader: true, autoFocus: true, height: "100%", runtimeId: podName, historyEndpoint: `${agentBaseUrl}/api/v1/history`, suggestions: [
+                                {
+                                    title: 'Alert me',
+                                    message: 'Notify me when KPIs drop below threshold',
+                                },
+                                {
+                                    title: 'Daily digest',
+                                    message: 'Set up a daily email digest of KPI summaries',
+                                },
+                            ], submitOnSuggestionClick: true }) }), _jsxs(Box, { sx: {
+                            width: 380,
+                            borderLeft: '1px solid',
+                            borderColor: 'border.default',
+                            display: 'flex',
+                            flexDirection: 'column',
+                            overflow: 'auto',
+                        }, children: [_jsxs(Box, { sx: {
+                                    p: 3,
+                                    borderBottom: '1px solid',
+                                    borderColor: 'border.default',
+                                }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, mb: 2 }, children: [_jsx(BellIcon, { size: 16 }), _jsx(Heading, { as: "h3", sx: { fontSize: 2 }, children: "Channels" })] }), channels.map(ch => {
+                                        const Icon = channelIcon(ch.channel);
+                                        return (_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: ch.channel !== 'in-app' ? 1 : 0,
+                                                    }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1 }, children: [_jsx(Icon, { size: 14 }), _jsx(Text, { sx: { fontWeight: 'bold', fontSize: 1 }, children: ch.channel })] }), _jsx(Button, { size: "small", variant: ch.enabled ? 'danger' : 'primary', leadingVisual: ch.enabled ? MuteIcon : BellIcon, onClick: () => handleToggleChannel(ch.channel), disabled: isSaving, children: ch.enabled ? 'Disable' : 'Enable' })] }), ch.channel !== 'in-app' && (_jsx(TextInput, { value: editTargets[ch.channel] ?? ch.target ?? '', onChange: e => setEditTargets(prev => ({
+                                                        ...prev,
+                                                        [ch.channel]: e.target.value,
+                                                    })), placeholder: ch.channel === 'email'
+                                                        ? 'user@example.com'
+                                                        : 'https://hooks.slack.com/…', size: "small", sx: { width: '100%' } }))] }, ch.channel));
+                                    }), _jsx(Button, { size: "small", leadingVisual: BellIcon, onClick: handleTestNotification, sx: { width: '100%' }, children: "Send Test Notification" }), flash && (_jsx(Flash, { variant: flash.includes('sent') ? 'success' : 'danger', sx: { mt: 2, fontSize: 0 }, children: flash }))] }), _jsxs(Box, { sx: { p: 3, flex: 1, overflow: 'auto' }, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: "Recent Notifications" }), notifications.length === 0 ? (_jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: "No notifications yet." })) : (_jsx(Timeline, { children: notifications.slice(0, 25).map(n => (_jsxs(Timeline.Item, { children: [_jsx(Timeline.Badge, { children: n.read ? _jsx(CheckCircleIcon, {}) : _jsx(BellIcon, {}) }), _jsxs(Timeline.Body, { children: [_jsx(Text, { sx: {
+                                                                fontSize: 0,
+                                                                fontWeight: n.read ? 'normal' : 'bold',
+                                                            }, children: n.title }), _jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 1 }, children: n.body }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: [new Date(n.timestamp).toLocaleString(), " via", ' ', _jsx(Label, { size: "small", variant: "secondary", children: n.channel })] })] })] }, n.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 AgentNotificationsExample = () => {
+    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 Notifications", description: "Sign in to configure and monitor agent notifications.", leadingIcon: _jsx(BellIcon, { size: 24 }) }) }));
+    }
+    return (_jsx(QueryClientProvider, { client: queryClient, children: _jsx(ThemedProvider, { children: _jsx(AgentNotificationsInner, { onLogout: handleLogout }) }) }));
+};
+export default AgentNotificationsExample;

package/lib/examples/AgentOtelExample.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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")
+ */
+import React from 'react';
+/**
+ * AgentOtelExample – themed root with auth gate.
+ */
+declare const AgentOtelExample: React.FC;
+export default AgentOtelExample;