@datalayer/agent-runtimes 1.0.4 → 1.0.6

package/lib/examples/AgentHooksExample.js

@@ -0,0 +1,122 @@
+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.
+ */
+import { useEffect, useState } from 'react';
+import { Text, Spinner } from '@primer/react';
+import { SyncIcon } from '@primer/octicons-react';
+import { Box, setupPrimerPortals } from '@datalayer/primer-addons';
+import { ThemedProvider } from './utils/themedProvider';
+import { uniqueAgentId } from './utils/agentId';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { ErrorView } from './components';
+import { Chat } from '../chat';
+setupPrimerPortals();
+const AGENT_SPEC_ID = 'example-hooks';
+const AGENT_NAME = 'hooks-example-agent';
+const AgentHooksExample = () => {
+    const baseUrl = useExampleAgentRuntimesUrl();
+    const [agentId, setAgentId] = useState(null);
+    const [error, setError] = useState(null);
+    const [isCreating, setIsCreating] = useState(true);
+    useEffect(() => {
+        let cancelled = false;
+        const name = uniqueAgentId(AGENT_NAME);
+        const createAgent = async () => {
+            try {
+                const response = await fetch(`${baseUrl}/api/v1/agents`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        name,
+                        agent_spec_id: AGENT_SPEC_ID,
+                        transport: 'vercel-ai',
+                    }),
+                });
+                if (!response.ok) {
+                    const data = await response
+                        .json()
+                        .catch(() => ({ detail: 'Unknown error' }));
+                    throw new Error(data.detail || `Failed to create agent: ${response.status}`);
+                }
+                const data = await response.json();
+                if (!cancelled) {
+                    setAgentId(data.id);
+                    setIsCreating(false);
+                }
+            }
+            catch (err) {
+                if (!cancelled) {
+                    setError(err instanceof Error ? err.message : 'Failed to create agent');
+                    setIsCreating(false);
+                }
+            }
+        };
+        createAgent();
+        return () => {
+            cancelled = true;
+        };
+    }, [baseUrl]);
+    useEffect(() => {
+        return () => {
+            if (!agentId) {
+                return;
+            }
+            void fetch(`${baseUrl}/api/v1/agents/${encodeURIComponent(agentId)}`, {
+                method: 'DELETE',
+            }).catch(() => {
+                // Ignore teardown failures in example mode.
+            });
+        };
+    }, [agentId, baseUrl]);
+    if (isCreating) {
+        return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
+                    display: 'flex',
+                    flexDirection: 'column',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    height: '100vh',
+                    gap: 3,
+                    bg: 'canvas.default',
+                }, children: [_jsx(Spinner, { size: "large" }), _jsxs(Text, { sx: { color: 'fg.muted' }, children: ["Creating agent from ", AGENT_SPEC_ID, "..."] })] }) }));
+    }
+    if (error || !agentId) {
+        return (_jsx(ThemedProvider, { children: _jsx(ErrorView, { error: "Failed to start hooks agent", detail: error || 'No agent ID returned' }) }));
+    }
+    return (_jsx(Chat, { protocol: "vercel-ai", baseUrl: baseUrl, agentId: agentId, title: "Hooks Agent", brandIcon: _jsx(SyncIcon, { size: 16 }), placeholder: "Ask about lifecycle hooks...", description: "Demonstrates lifecycle hooks and pydantic-style tool hooks: before_tool_execute, after_tool_execute, on_tool_execute_error, deferred_tool_calls", showHeader: true, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, autoFocus: true, height: "100vh", runtimeId: agentId, historyEndpoint: `${baseUrl}/api/v1/history`, suggestions: [
+            {
+                title: 'Read the pre-hook marker file',
+                message: 'Use execute_code to read /tmp/agent_runtimes_pre_hook_demo.txt and show its contents.',
+            },
+            {
+                title: 'Verify hook variables',
+                message: 'Use execute_code to run this verification:\n```python\nassert isinstance(hook_name, str) and hook_name == "example-hooks:pre", f"❌ hook_name wrong: {hook_name!r}"\nassert isinstance(hook_ran_at, str) and len(hook_ran_at) > 0, f"❌ hook_ran_at wrong: {hook_ran_at!r}"\nassert isinstance(hook_env, dict) and len(hook_env) > 0, f"❌ hook_env wrong: {hook_env!r}"\nprint("✅ hook_name =", hook_name)\nprint("✅ hook_ran_at =", hook_ran_at)\nprint("✅ hook_env =", hook_env)\n```\nThrow an exception with a ❌ message if any variable is missing or has the wrong type, print ✅ lines if all pass.',
+            },
+            {
+                title: "Verify 'rich' was installed",
+                message: 'Use execute_code to import rich and print its version — the pre-hook installed it via pip.',
+            },
+            {
+                title: 'Explain the hook lifecycle',
+                message: 'What pre-hooks and post-hooks are configured for this agent, and when does each run?',
+            },
+            {
+                title: 'Trigger function + python tool hooks',
+                message: "Call runtime_sensitive_echo with text 'hello' and reason 'audit', then explain which before_tool_execute hooks ran (function and python).",
+            },
+            {
+                title: 'Trigger deny in python hook',
+                message: "Call runtime_sensitive_echo with text 'danger' and reason 'delete notebook', then explain why local Python policy denied it.",
+            },
+            {
+                title: 'Read tool approval audit log',
+                message: 'Use execute_code to show the latest entries from /tmp/agent_runtimes_tool_approvals_audit.jsonl and summarize decision and execution status.',
+            },
+            {
+                title: 'Explain deferred hook handling',
+                message: 'Explain how deferred_tool_calls works with approval-required tools and when inline resolution is used in this run.',
+            },
+        ], submitOnSuggestionClick: true }));
+};
+export default AgentHooksExample;

package/lib/examples/AgentInferenceProviderExample.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+declare const AgentInferenceProviderExample: React.FC;
+export default AgentInferenceProviderExample;

package/lib/examples/AgentInferenceProviderExample.js

@@ -0,0 +1,329 @@
+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.
+ */
+/// <reference types="vite/client" />
+import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { Button, Box, Heading, SegmentedControl, Spinner, Text, } from '@primer/react';
+import { ThemedProvider } from './utils/themedProvider';
+import { uniqueAgentId } from './utils/agentId';
+import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
+import { Chat } from '../chat';
+import { useAIAgentsWebSocket } from '../hooks';
+const AGENT_SPEC_ID = 'example-inference';
+const AGENT_NAME = 'inference-provider-example-agent';
+const DEFAULT_LOCAL_BASE_URL = import.meta.env.VITE_BASE_URL || 'http://localhost:8765';
+const queryClient = new QueryClient();
+const nowIso = () => new Date().toISOString();
+const toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+const stringifyPayload = (value) => {
+    if (typeof value === 'string') {
+        return value;
+    }
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+};
+const ProviderBadge = ({ provider, }) => (_jsx(Box, { sx: {
+        px: 2,
+        py: '2px',
+        borderRadius: 999,
+        border: '1px solid',
+        borderColor: 'border.default',
+        fontSize: 0,
+        color: 'fg.muted',
+        bg: 'canvas.inset',
+        textTransform: 'uppercase',
+        letterSpacing: '0.03em',
+    }, children: provider }));
+const AgentInferenceProviderExampleInner = () => {
+    const { token } = useSimpleAuthStore();
+    const [provider, setProvider] = useState('local');
+    const [agentId, setAgentId] = useState(null);
+    const [isLaunching, setIsLaunching] = useState(true);
+    const [error, setError] = useState(null);
+    const [providerEvents, setProviderEvents] = useState([]);
+    const [expandedEventIds, setExpandedEventIds] = useState(() => new Set());
+    const currentAgentRef = useRef(null);
+    const requestEpochRef = useRef(0);
+    const baseUrl = DEFAULT_LOCAL_BASE_URL;
+    const inferenceUrl = useMemo(() => {
+        if (provider === 'local') {
+            return 'local inference';
+        }
+        const env = import.meta.env ?? {};
+        return (env.VITE_DATALAYER_AI_INFERENCE_URL ||
+            env.VITE_DATALAYER_RUN_URL ||
+            'https://prod1.datalayer.run');
+    }, [provider]);
+    const authFetch = useCallback((url, init = {}) => {
+        return fetch(url, {
+            ...init,
+            headers: {
+                'Content-Type': 'application/json',
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                ...(init.headers ?? {}),
+            },
+        });
+    }, [token]);
+    const appendProviderEvent = useCallback((type, summary, payload) => {
+        setProviderEvents(prev => [
+            {
+                id: `${Date.now()}-${Math.random().toString(36).slice(2)}`,
+                type,
+                summary,
+                payload: stringifyPayload(payload),
+                createdAt: nowIso(),
+            },
+            ...prev,
+        ]);
+    }, []);
+    const deleteAgent = useCallback(async (id) => {
+        await authFetch(`${baseUrl}/api/v1/agents/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+        }).catch(() => {
+            // Best-effort cleanup in example mode.
+        });
+    }, [authFetch, baseUrl]);
+    const launchAgentForProvider = useCallback(async (nextProvider) => {
+        requestEpochRef.current += 1;
+        const requestEpoch = requestEpochRef.current;
+        setIsLaunching(true);
+        setError(null);
+        const previousAgentId = currentAgentRef.current;
+        if (previousAgentId) {
+            await deleteAgent(previousAgentId);
+        }
+        try {
+            const configureResponse = await authFetch(`${baseUrl}/api/v1/configure/inference/provider`, {
+                method: 'PUT',
+                body: JSON.stringify({ provider: nextProvider }),
+            });
+            appendProviderEvent('configure.provider', `Configured runtime inference provider to ${nextProvider}`, {
+                status: configureResponse.status,
+                provider: nextProvider,
+            });
+            const name = uniqueAgentId(`${AGENT_NAME}-${nextProvider}`);
+            const createResponse = await authFetch(`${baseUrl}/api/v1/agents`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    name,
+                    transport: 'vercel-ai',
+                    agent_spec_id: AGENT_SPEC_ID,
+                    inferenceProvider: nextProvider,
+                }),
+            });
+            if (!createResponse.ok) {
+                const detail = await createResponse.text();
+                throw new Error(detail || `Failed to create agent (${createResponse.status})`);
+            }
+            const payload = (await createResponse.json());
+            const nextAgentId = payload.id || name;
+            if (requestEpoch !== requestEpochRef.current) {
+                return;
+            }
+            currentAgentRef.current = nextAgentId;
+            setAgentId(nextAgentId);
+            appendProviderEvent('agent.created', 'Launched local agent runtime', {
+                agentId: nextAgentId,
+                agentSpecId: AGENT_SPEC_ID,
+                inferenceProvider: nextProvider,
+                baseUrl,
+            });
+        }
+        catch (launchError) {
+            if (requestEpoch !== requestEpochRef.current) {
+                return;
+            }
+            setAgentId(null);
+            currentAgentRef.current = null;
+            setError(toErrorMessage(launchError));
+            appendProviderEvent('agent.error', 'Failed to launch agent', {
+                provider: nextProvider,
+                error: toErrorMessage(launchError),
+            });
+        }
+        finally {
+            if (requestEpoch === requestEpochRef.current) {
+                setIsLaunching(false);
+            }
+        }
+    }, [appendProviderEvent, authFetch, baseUrl, deleteAgent]);
+    useEffect(() => {
+        void launchAgentForProvider(provider);
+    }, [launchAgentForProvider, provider]);
+    useEffect(() => {
+        return () => {
+            const existing = currentAgentRef.current;
+            if (existing) {
+                void deleteAgent(existing);
+            }
+        };
+    }, [deleteAgent]);
+    const onProviderChange = useCallback((next) => {
+        setProvider(next);
+    }, []);
+    useAIAgentsWebSocket({
+        enabled: Boolean(agentId) && !isLaunching,
+        baseUrl,
+        path: '/api/v1/tool-approvals/ws',
+        queryParams: agentId ? { agent_id: agentId } : undefined,
+        onMessage: message => {
+            const eventType = typeof message.type === 'string'
+                ? message.type
+                : typeof message.event === 'string'
+                    ? message.event
+                    : 'stream.message';
+            appendProviderEvent('provider.stream', `Received ${eventType}`, {
+                provider,
+                agentId,
+                message: message.raw ?? message,
+            });
+        },
+        reconnectDelayMs: attempt => Math.min(1000 * 2 ** Math.max(0, attempt - 1), 10000),
+    });
+    const orderedProviderEvents = useMemo(() => [...providerEvents].sort((a, b) => b.createdAt.localeCompare(a.createdAt)), [providerEvents]);
+    const toggleEventExpanded = useCallback((eventId) => {
+        setExpandedEventIds(prev => {
+            const next = new Set(prev);
+            if (next.has(eventId)) {
+                next.delete(eventId);
+            }
+            else {
+                next.add(eventId);
+            }
+            return next;
+        });
+    }, []);
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
+                height: '100%',
+                minHeight: 0,
+                width: '100%',
+                display: 'grid',
+                gridTemplateColumns: ['1fr', '1fr', 'minmax(680px, 1fr) 420px'],
+                gridTemplateRows: 'minmax(0, 1fr)',
+                overflow: 'hidden',
+                bg: 'canvas.default',
+            }, children: [_jsxs(Box, { sx: {
+                        height: '100%',
+                        borderRight: ['none', 'none', '1px solid'],
+                        borderColor: 'border.default',
+                        p: 3,
+                        display: 'flex',
+                        flexDirection: 'column',
+                        gap: 3,
+                        minHeight: 0,
+                        overflow: 'hidden',
+                    }, children: [_jsxs(Box, { sx: {
+                                display: 'flex',
+                                justifyContent: 'space-between',
+                                alignItems: 'center',
+                                flexWrap: 'wrap',
+                                gap: 2,
+                            }, children: [_jsxs(Box, { children: [_jsx(Heading, { as: "h2", sx: { fontSize: 4, mb: 1 }, children: "Agent Inference Provider Example" }), _jsxs(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: ["Launches a local agent runtime from ", AGENT_SPEC_ID, " and lets you switch between local and datalayer inference."] })] }), _jsx(ProviderBadge, { provider: provider })] }), _jsxs(SegmentedControl, { "aria-label": "Inference provider", fullWidth: true, children: [_jsx(SegmentedControl.Button, { selected: provider === 'local', onClick: () => onProviderChange('local'), children: "local" }), _jsx(SegmentedControl.Button, { selected: provider === 'datalayer', onClick: () => onProviderChange('datalayer'), children: "datalayer" })] }), _jsxs(Box, { sx: {
+                                display: 'flex',
+                                gap: 2,
+                                alignItems: 'center',
+                                flexWrap: 'wrap',
+                            }, children: [isLaunching ? _jsx(Spinner, { size: "small" }) : null, _jsxs(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: ["Runtime URL: ", baseUrl] }), _jsxs(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: ["Inference URL: ", inferenceUrl] }), _jsxs(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: ["Agent ID: ", agentId || 'launching...'] })] }), error ? (_jsx(Box, { sx: {
+                                p: 2,
+                                borderRadius: 2,
+                                border: '1px solid',
+                                borderColor: 'danger.emphasis',
+                                bg: 'danger.subtle',
+                                color: 'danger.fg',
+                                fontSize: 1,
+                            }, children: error })) : null, _jsx(Box, { sx: {
+                                flexGrow: 1,
+                                flexShrink: 1,
+                                flexBasis: 0,
+                                minHeight: 0,
+                                border: '1px solid',
+                                borderColor: 'border.default',
+                                borderRadius: 2,
+                                overflow: 'hidden',
+                                bg: 'canvas.default',
+                            }, children: agentId && !isLaunching ? (_jsx(Chat, { protocol: "vercel-ai", baseUrl: baseUrl, agentId: agentId, authToken: token ?? undefined, title: "Agent Inference Provider Example", subtitle: `Spec: ${AGENT_SPEC_ID}`, placeholder: "Ask the inference provider something...", showHeader: true, showNewChatButton: true, showClearButton: false, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: agentId, historyEndpoint: `${baseUrl}/api/v1/history`, onMessageSent: content => {
+                                    appendProviderEvent('provider.request', `Sent message via ${provider}`, {
+                                        provider,
+                                        agentId,
+                                        content,
+                                    });
+                                }, onMessageReceived: message => {
+                                    appendProviderEvent('provider.message', 'Received stream message', message);
+                                }, suggestions: [
+                                    {
+                                        title: 'Compare providers',
+                                        message: 'Give me a short 3-point comparison between local and datalayer inference providers.',
+                                    },
+                                ], submitOnSuggestionClick: true })) : (_jsxs(Box, { sx: {
+                                    height: '100%',
+                                    display: 'flex',
+                                    alignItems: 'center',
+                                    justifyContent: 'center',
+                                    gap: 2,
+                                    color: 'fg.muted',
+                                }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1 }, children: "Launching provider runtime\u2026" })] })) })] }), _jsxs(Box, { sx: {
+                        p: 3,
+                        display: ['none', 'none', 'flex'],
+                        flexDirection: 'column',
+                        gap: 2,
+                        minHeight: 0,
+                        overflow: 'hidden',
+                        bg: 'canvas.inset',
+                    }, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2 }, children: "Provider Event Stream" }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Low-level request/response events exchanged with the inference provider (newest first)." }), _jsx(Box, { sx: {
+                                flex: 1,
+                                minHeight: 0,
+                                overflowY: 'auto',
+                                display: 'flex',
+                                flexDirection: 'column',
+                                gap: 2,
+                            }, children: providerEvents.length === 0 ? (_jsx(Box, { sx: {
+                                    border: '1px dashed',
+                                    borderColor: 'border.default',
+                                    borderRadius: 2,
+                                    p: 3,
+                                }, children: _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "No provider events yet." }) })) : (orderedProviderEvents.map(event => (_jsxs(Box, { sx: {
+                                    border: '1px solid',
+                                    borderColor: 'border.default',
+                                    borderRadius: 2,
+                                    p: 2,
+                                    bg: 'canvas.default',
+                                }, children: [_jsx(Text, { sx: {
+                                            display: 'block',
+                                            fontSize: 0,
+                                            color: 'fg.muted',
+                                            textTransform: 'uppercase',
+                                            letterSpacing: '0.04em',
+                                        }, children: event.type }), _jsx(Text, { sx: {
+                                            display: 'block',
+                                            fontWeight: 600,
+                                            fontSize: 1,
+                                            mt: 1,
+                                        }, children: event.summary }), _jsx(Text, { sx: {
+                                            display: 'block',
+                                            color: 'fg.muted',
+                                            fontSize: 0,
+                                            mt: 1,
+                                        }, children: new Date(event.createdAt).toLocaleTimeString() }), _jsx(Box, { sx: { mt: 2 }, children: _jsx(Button, { size: "small", variant: "invisible", onClick: () => toggleEventExpanded(event.id), children: expandedEventIds.has(event.id)
+                                                ? 'Hide details'
+                                                : 'Show details' }) }), expandedEventIds.has(event.id) ? (_jsx(Text, { as: "pre", sx: {
+                                            mt: 2,
+                                            mb: 0,
+                                            p: 2,
+                                            borderRadius: 2,
+                                            bg: 'canvas.subtle',
+                                            fontSize: 0,
+                                            whiteSpace: 'pre-wrap',
+                                            fontFamily: 'mono',
+                                        }, children: event.payload })) : null] }, event.id)))) })] })] }) }));
+};
+const AgentInferenceProviderExample = () => {
+    return (_jsx(QueryClientProvider, { client: queryClient, children: _jsx(AgentInferenceProviderExampleInner, {}) }));
+};
+export default AgentInferenceProviderExample;

package/lib/examples/AgentMCPExample.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+declare const AgentMCPExample: React.FC;
+export default AgentMCPExample;