@datalayer/agent-runtimes 1.0.29 → 1.3.10

package/lib/examples/AgUiAgenticExample.js

@@ -19,7 +19,6 @@ import { Spinner, Text } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
-import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { uniqueAgentId } from './utils/agentId';
 import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 /**
@@ -36,9 +35,8 @@ import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 const AGENT_NAME = 'ag-ui-agentic';
 const AGENTSPEC_ID = 'example-agentic-chat';
 const AgUiAgenticExample = () => {
-    const baseUrl = useExampleAgentRuntimesUrl();
     const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
-    const { agentId, status, error, isReady } = useExampleAgentRuntime({
+    const { agentId, baseUrl, status, error, isReady } = useExampleAgentRuntime({
         exampleId: 'AgUiAgenticExample',
         agentName,
         specId: AGENTSPEC_ID,
@@ -60,7 +58,7 @@ const AgUiAgenticExample = () => {
                                 fontSize: 4,
                                 fontWeight: 'bold',
                                 marginBottom: 2,
-                            }, children: "AG-UI: Agentic Example" }), _jsx(Text, { as: "p", sx: {
+                            }, children: "AG-UI Agentic Example" }), _jsx(Text, { as: "p", sx: {
                                 fontSize: 2,
                                 color: 'fg.muted',
                                 marginBottom: 4,

package/lib/examples/AgUiBackendToolRenderingExample.js

@@ -21,7 +21,6 @@ import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider, useThemeBrandColor } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
 import { InlineWeatherCard } from './components/weather';
-import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { uniqueAgentId } from './utils/agentId';
 import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { useSpecRenderToolResult, specRendererClassName, } from './hooks/useSpecRenderToolResult';
@@ -55,9 +54,8 @@ const AGENT_NAME = 'ag-ui-backend-tools';
 const AGENTSPEC_ID = 'example-backend-tool-rendering';
 const AgUiBackendToolRenderingExample = () => {
     const brandColor = useThemeBrandColor();
-    const baseUrl = useExampleAgentRuntimesUrl();
     const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
-    const { agentId } = useExampleAgentRuntime({
+    const { agentId, baseUrl } = useExampleAgentRuntime({
         exampleId: 'AgUiBackendToolRenderingExample',
         agentName,
         specId: AGENTSPEC_ID,
@@ -85,7 +83,7 @@ const AgUiBackendToolRenderingExample = () => {
                                 fontSize: 4,
                                 fontWeight: 'bold',
                                 marginBottom: 2,
-                            }, children: "AG-UI: Backend Tool Rendering (Inline)" }), _jsxs(Text, { as: "p", sx: {
+                            }, children: "AG-UI Backend Tool Rendering (Inline)" }), _jsxs(Text, { as: "p", sx: {
                                 fontSize: 2,
                                 color: 'fg.muted',
                                 marginBottom: 4,
@@ -105,7 +103,7 @@ const AgUiBackendToolRenderingExample = () => {
                                                 marginTop: 1,
                                                 fontSize: 1,
                                                 color: 'fg.muted',
-                                            }, children: [_jsx("li", { children: "\"What's the weather in New York?\"" }), _jsx("li", { children: "\"Weather in London and Paris\"" }), _jsx("li", { children: "\"Is it sunny in Sydney?\"" }), _jsx("li", { children: "\"How's the weather in Tokyo today?\"" })] })] })] })] }), backendToolRenderingEndpoint && (_jsx(ChatFloating, { kernelIndicatorPlacement: "right", protocol: "ag-ui", endpoint: backendToolRenderingEndpoint, title: "Weather Assistant", description: "Ask me about the weather anywhere in the world!", position: "bottom-right", brandColor: brandColor, onStateUpdate: handleStateUpdate, renderToolResult: renderToolResult, suggestions: [
+                                            }, children: [_jsx("li", { children: "\"What's the weather in New York?\"" }), _jsx("li", { children: "\"Weather in London and Paris\"" }), _jsx("li", { children: "\"Is it sunny in Sydney?\"" }), _jsx("li", { children: "\"How's the weather in Tokyo today?\"" })] })] })] })] }), backendToolRenderingEndpoint && (_jsx(ChatFloating, { kernelIndicatorPlacement: "right", protocol: "ag-ui", endpoint: backendToolRenderingEndpoint, title: "Weather Assistant", description: "Ask me about the weather anywhere in the world!", position: "bottom-right", brandColor: brandColor, defaultOpen: true, onStateUpdate: handleStateUpdate, renderToolResult: renderToolResult, suggestions: [
                         {
                             title: 'Paris weather',
                             message: "What's the weather like in Paris?",

package/lib/examples/AgUiHaikuGenUiExample.js

@@ -22,7 +22,6 @@ import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider, useThemeBrandColor } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
 import { InlineHaikuCard, HaikuDisplay, } from './components/haiku';
-import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { uniqueAgentId } from './utils/agentId';
 import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { useSpecRenderToolResult, specRendererClassName, } from './hooks/useSpecRenderToolResult';
@@ -65,9 +64,8 @@ const AGENT_NAME = 'ag-ui-haiku';
 const AGENTSPEC_ID = 'example-haiku-generative-ui';
 const AgUiHaikuGenUiExample = () => {
     const brandColor = useThemeBrandColor();
-    const baseUrl = useExampleAgentRuntimesUrl();
     const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
-    const { agentId } = useExampleAgentRuntime({
+    const { agentId, baseUrl } = useExampleAgentRuntime({
         exampleId: 'AgUiHaikuGenUiExample',
         agentName,
         specId: AGENTSPEC_ID,
@@ -123,7 +121,7 @@ const AgUiHaikuGenUiExample = () => {
                                 fontSize: 4,
                                 fontWeight: 'bold',
                                 marginBottom: 2,
-                            }, children: "AG-UI: Haiku Generative UI" }), _jsx(Text, { as: "p", sx: {
+                            }, children: "AG-UI Haiku Generative UI" }), _jsx(Text, { as: "p", sx: {
                                 fontSize: 2,
                                 color: 'fg.muted',
                                 marginBottom: 4,

package/lib/examples/AgUiHumanInTheLoopExample.js

@@ -20,7 +20,6 @@ import { Text, Checkbox, FormControl, Label, ProgressBar, Button, } from '@prime
 import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider, useThemeBrandColor } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
-import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { uniqueAgentId } from './utils/agentId';
 import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { TasklistIcon, CheckCircleFillIcon, XCircleFillIcon, } from '@primer/octicons-react';
@@ -182,9 +181,8 @@ const AGENT_NAME = 'ag-ui-human-in-the-loop';
 const AGENTSPEC_ID = 'example-human-in-the-loop';
 const AgUiHumanInTheLoopExample = () => {
     const brandColor = useThemeBrandColor();
-    const baseUrl = useExampleAgentRuntimesUrl();
     const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
-    const { agentId } = useExampleAgentRuntime({
+    const { agentId, baseUrl } = useExampleAgentRuntime({
         exampleId: 'AgUiHumanInTheLoopExample',
         agentName,
         specId: AGENTSPEC_ID,
@@ -205,7 +203,7 @@ const AgUiHumanInTheLoopExample = () => {
                                 fontSize: 4,
                                 fontWeight: 'bold',
                                 marginBottom: 2,
-                            }, children: "AG-UI: Human in the Loop Example" }), _jsx(Text, { as: "p", sx: {
+                            }, children: "AG-UI Human in the Loop Example" }), _jsx(Text, { as: "p", sx: {
                                 fontSize: 2,
                                 color: 'fg.muted',
                                 marginBottom: 4,

package/lib/examples/AgUiSharedStateExample.js

@@ -17,7 +17,6 @@ import { Text, Button, TextInput, Label } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider, useThemeBrandColor } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
-import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { uniqueAgentId } from './utils/agentId';
 import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { PlusIcon, XIcon, BeakerIcon, ClockIcon, PersonIcon, } from '@primer/octicons-react';
@@ -108,9 +107,8 @@ const AGENT_NAME = 'ag-ui-shared-state';
 const AGENTSPEC_ID = 'example-shared-state';
 const AgUiSharedStateExample = () => {
     const brandColor = useThemeBrandColor();
-    const baseUrl = useExampleAgentRuntimesUrl();
     const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
-    const { agentId } = useExampleAgentRuntime({
+    const { agentId, baseUrl } = useExampleAgentRuntime({
         exampleId: 'AgUiSharedStateExample',
         agentName,
         specId: AGENTSPEC_ID,
@@ -158,7 +156,7 @@ const AgUiSharedStateExample = () => {
                                                 fontSize: 4,
                                                 fontWeight: 'bold',
                                                 marginBottom: 2,
-                                            }, children: "AG-UI: Shared State Example" }), _jsx(Text, { as: "p", sx: {
+                                            }, children: "AG-UI Shared State Example" }), _jsx(Text, { as: "p", sx: {
                                                 fontSize: 2,
                                                 color: 'fg.muted',
                                             }, children: "Build a recipe together with AI. Both you and the agent can edit the recipe." })] }), _jsx(Button, { variant: "danger", onClick: handleClear, children: "Clear Recipe" })] }), _jsxs(Box, { sx: {

package/lib/examples/AgUiToolsBasedGenUiExample.js

@@ -17,7 +17,6 @@ import { Text, ProgressBar, Button } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider, useThemeBrandColor } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
-import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { uniqueAgentId } from './utils/agentId';
 import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { CheckCircleIcon, CircleIcon, DotFillIcon, CheckIcon, XIcon, } from '@primer/octicons-react';
@@ -175,9 +174,8 @@ const AGENT_NAME = 'ag-ui-generative-ui';
 const AGENTSPEC_ID = 'example-agentic-generative-ui';
 const AgUiToolsBasedGenUiExample = () => {
     const brandColor = useThemeBrandColor();
-    const baseUrl = useExampleAgentRuntimesUrl();
     const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
-    const { agentId } = useExampleAgentRuntime({
+    const { agentId, baseUrl } = useExampleAgentRuntime({
         exampleId: 'AgUiToolsBasedGenUiExample',
         agentName,
         specId: AGENTSPEC_ID,
@@ -238,7 +236,7 @@ const AgUiToolsBasedGenUiExample = () => {
                                 fontSize: 4,
                                 fontWeight: 'bold',
                                 marginBottom: 2,
-                            }, children: "AG-UI: Tool-Based Generative UI Example" }), _jsx(Text, { as: "p", sx: {
+                            }, children: "AG-UI Tool-Based Generative UI Example" }), _jsx(Text, { as: "p", sx: {
                                 fontSize: 2,
                                 color: 'fg.muted',
                                 marginBottom: 4,

package/lib/examples/AgentA2AExample.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AgentA2AExample
+ *
+ * Delegation to separate agents over the A2A protocol. The orchestrator runs
+ * on the local agent-runtimes server, created there by the Loop from the
+ * `example-a2a` blueprint; its researcher and writer are not subagents inside
+ * its process but agents of their own, launched on the first delegation —
+ * beside the orchestrator on the local server, or on Datalayer runtimes when
+ * the orchestrator itself runs in the cloud — and spoken to over A2A.
+ *
+ * - The chat boxes each remote run under its delegation tool card
+ * - The A2A sidebar lists the remote agents, where each runs, its card and
+ *   task, and keeps the live run box in view
+ */
+import React from 'react';
+declare const AgentA2AExample: React.FC;
+export default AgentA2AExample;

package/lib/examples/AgentA2AExample.js

@@ -0,0 +1,56 @@
+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.
+ */
+/**
+ * AgentA2AExample
+ *
+ * Delegation to separate agents over the A2A protocol. The orchestrator runs
+ * on the local agent-runtimes server, created there by the Loop from the
+ * `example-a2a` blueprint; its researcher and writer are not subagents inside
+ * its process but agents of their own, launched on the first delegation —
+ * beside the orchestrator on the local server, or on Datalayer runtimes when
+ * the orchestrator itself runs in the cloud — and spoken to over A2A.
+ *
+ * - The chat boxes each remote run under its delegation tool card
+ * - The A2A sidebar lists the remote agents, where each runs, its card and
+ *   task, and keeps the live run box in view
+ */
+/// <reference types="vite/client" />
+import { useMemo } from 'react';
+import { Heading, Label } from '@primer/react';
+import { BroadcastIcon } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+import { ThemedProvider } from './utils/themedProvider';
+import { uniqueAgentId } from './utils/agentId';
+import { resolveExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { LoopEmbed } from '../loop';
+import { AgentA2APlugin } from '../loop/plugins/agent-a2a';
+import { A2ASidebarPlugin } from '../loop/plugins/a2a-sidebar';
+import { getAgentspecs } from '../specs/agents';
+const AGENT_NAME = 'a2a-example-agent';
+const AGENTSPEC_ID = 'example-a2a';
+/** The agents the orchestrator reaches over A2A, from its spec. */
+const remoteAgentCount = () => (getAgentspecs(AGENTSPEC_ID)?.subagents?.subagents ?? []).filter(subagent => subagent.a2a).length;
+const AgentA2AExample = () => {
+    const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
+    const plugins = useMemo(() => [AgentA2APlugin, A2ASidebarPlugin], []);
+    const remoteAgents = remoteAgentCount();
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
+                height: '100%',
+                display: 'flex',
+                flexDirection: 'column',
+                bg: 'canvas.default',
+            }, children: [_jsxs(Box, { sx: {
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: 2,
+                        px: 3,
+                        py: 2,
+                        borderBottom: '1px solid',
+                        borderColor: 'border.default',
+                        flexShrink: 0,
+                    }, children: [_jsx(BroadcastIcon, { size: 16 }), _jsx(Heading, { as: "h3", sx: { fontSize: 2, flex: 1 }, children: "A2A Demo" }), _jsx(Label, { variant: "accent", children: "local" }), _jsxs(Label, { variant: "accent", children: [remoteAgents, " A2A agent", remoteAgents === 1 ? '' : 's'] })] }), _jsx(Box, { sx: { flex: 1, minHeight: 0 }, children: _jsx(LoopEmbed, { serverUrl: resolveExampleAgentRuntimesUrl('local'), target: "local", showAgentVariants: true, agentId: agentName, defaultEditor: "none", showHeader: true, plugins: plugins }) })] }) }));
+};
+export default AgentA2AExample;

package/lib/examples/AgentCheckpointsExample.d.ts

@@ -1,18 +1,17 @@
 /**
  * AgentCheckpointsExample
  *
- * Demonstrates launching a agent in the Datalayer cloud,
- * with pause/resume (checkpoint) and lifecycle controls.
+ * Checkpoints, at the two levels the runtime offers them.
  *
- * Uses the `useAgent` hook which:
- *   1. Creates a cloud agent runtime via the Datalayer Runtimes API
- *      (environment: 'ai-agents-env')
- *   2. Deploys an agent on the runtime's agent-runtimes sidecar
- *   3. Provides pause/resume/terminate lifecycle backed by CRIU
+ * On the Local target (and any sandbox), the capability is the agent's own
+ * conversation checkpoints: the `example-checkpoints` agent snapshots its
+ * conversation after every turn, saves a named checkpoint on request, lists
+ * them and rewinds to one — and the checkpoints sidebar shows them, saves one
+ * between turns and rewinds the chat.
  *
- * Prerequisites:
- *   - Datalayer core configuration (runtimesUrl, aiAgentsUrl)
- *   - Valid IAM token (set via SignInSimple or iamStore)
+ * On the Datalayer target the runtime itself is the thing checkpointed:
+ * the console below launches a cloud agent runtime and pauses and resumes it
+ * (light, or CRIU) with lifecycle controls.
  */
 import React from 'react';
 declare const AgentCheckpointsExample: React.FC;

package/lib/examples/AgentCheckpointsExample.js

@@ -6,34 +6,38 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 /**
  * AgentCheckpointsExample
  *
- * Demonstrates launching a agent in the Datalayer cloud,
- * with pause/resume (checkpoint) and lifecycle controls.
+ * Checkpoints, at the two levels the runtime offers them.
  *
- * Uses the `useAgent` hook which:
- *   1. Creates a cloud agent runtime via the Datalayer Runtimes API
- *      (environment: 'ai-agents-env')
- *   2. Deploys an agent on the runtime's agent-runtimes sidecar
- *   3. Provides pause/resume/terminate lifecycle backed by CRIU
+ * On the Local target (and any sandbox), the capability is the agent's own
+ * conversation checkpoints: the `example-checkpoints` agent snapshots its
+ * conversation after every turn, saves a named checkpoint on request, lists
+ * them and rewinds to one — and the checkpoints sidebar shows them, saves one
+ * between turns and rewinds the chat.
  *
- * Prerequisites:
- *   - Datalayer core configuration (runtimesUrl, aiAgentsUrl)
- *   - Valid IAM token (set via SignInSimple or iamStore)
+ * On the Datalayer target the runtime itself is the thing checkpointed:
+ * the console below launches a cloud agent runtime and pauses and resumes it
+ * (light, or CRIU) with lifecycle controls.
  */
 /// <reference types="vite/client" />
 import { useState, useCallback, useEffect, useRef, useMemo, } from 'react';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { Text, Button, IconButton, Spinner, Label, Flash, Heading, Tooltip, } from '@primer/react';
-import { AlertIcon, PlayIcon, SquareIcon, HistoryIcon, CheckCircleIcon, XCircleIcon, ClockIcon, TagIcon, GlobeIcon, ZapIcon, GraphIcon, AiModelIcon, PeopleIcon, SidebarCollapseIcon, SidebarExpandIcon, SyncIcon, AgentIcon, } from '@primer/octicons-react';
+import { AlertIcon, PlayIcon, SquareIcon, HistoryIcon, CheckCircleIcon, XCircleIcon, ClockIcon, TagIcon, GlobeIcon, ZapIcon, GraphIcon, AiModelIcon, PeopleIcon, SidebarCollapseIcon, SidebarExpandIcon, SyncIcon, AgentIcon, VersionsIcon, } from '@primer/octicons-react';
 import { Box } from '@datalayer/primer-addons';
 import { AuthRequiredView, ErrorView } from './components';
 import { ThemedProvider } from './utils/themedProvider';
 import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
-import { Chat } from '../chat';
+import { LoopEmbed } from '../loop';
+import { AgentCheckpointsPlugin } from '../loop/plugins/agent-checkpoints';
+import { CheckpointsSidebarPlugin } from '../loop/plugins/checkpoints-sidebar';
+import { uniqueAgentId } from './utils/agentId';
+import { resolveExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { useRuntimeTargetStore } from './utils/runtimeTargetStore';
 import { useAgentsRuntimes, useAgentRuntimesQuery, useRefreshAgentRuntimes, } from '../hooks/useAgentRuntimes';
 import { useExampleAgentRuntimes as useAgentRuntimes } from './hooks/useExampleAgentRuntimes';
 import { useAgentLifecycle } from '../hooks/useCheckpoints';
-import { useDeletePausedAgentRuntime } from '../hooks/useCheckpoints';
 import { AGENT_STATUS_COLORS } from '../types/agents';
+const LOOP_PLUGINS_AGENTCHE = [AgentCheckpointsPlugin];
 const queryClient = new QueryClient();
 // ─── Defaults ──────────────────────────────────────────────────────────────
 const AGENTSPEC_ID = 'monitor-sales-kpis';
@@ -53,7 +57,7 @@ const AGENTSPEC = {
     model: 'bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0',
     protocol: 'vercel-ai',
     memory: 'mem0',
-    sandbox_variant: 'jupyter',
+    sandbox_variant: 'jupyter-server',
     environment_name: 'ai-agents-env',
     tags: ['support', 'chatbot', 'sales', 'kpi', 'monitoring'],
     trigger: {
@@ -107,10 +111,8 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
     });
     // Agent runtimes from the focused hook
     const { data: agentRuntimes } = useAgentRuntimesQuery();
-    const { terminateRuntimeByPod } = useAgentsRuntimes();
+    const { stopRuntimeByName } = useAgentsRuntimes();
     const refetchRuntimes = useRefreshAgentRuntimes();
-    const deletePausedRuntimeMutation = useDeletePausedAgentRuntime();
-    const deletePausedRuntimeByPod = deletePausedRuntimeMutation.mutateAsync;
     const [isStarting, setIsStarting] = useState(false);
     const [sidebarOpen, setSidebarOpen] = useState(true);
     const [actionLoading, setActionLoading] = useState(false);
@@ -119,7 +121,7 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
     const [resumeMode, setResumeMode] = useState('light');
     const autoConnectAttemptRef = useRef(null);
     const displayError = hookError || actionError;
-    const podName = runtime?.podName || '(launching…)';
+    const runtimeName = runtime?.runtimeName || '(launching…)';
     const agentId = runtime?.agentId || AGENTSPEC_ID;
     const agentBaseUrl = runtime?.agentBaseUrl || '';
     const handleLaunch = useCallback(async () => {
@@ -156,11 +158,11 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
             setActionLoading(false);
         }
     }, [pause, refreshCheckpoints, refreshAgents, terminate]);
-    const handleResume = useCallback(async (mode, checkpointId, podName) => {
+    const handleResume = useCallback(async (mode, checkpointId, runtimeName) => {
         setActionLoading(true);
         setActionError(null);
         try {
-            await resume(mode, checkpointId, podName);
+            await resume(mode, checkpointId, runtimeName);
             await Promise.all([refreshCheckpoints(), refreshAgents()]);
         }
         catch (e) {
@@ -172,11 +174,11 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
     }, [resume, refreshCheckpoints, refreshAgents]);
     // Refresh lists when a runtime connection is established.
     useEffect(() => {
-        if (runtime?.podName) {
+        if (runtime?.runtimeName) {
             refreshCheckpoints();
             refreshAgents();
         }
-    }, [runtime?.podName, refreshCheckpoints, refreshAgents]);
+    }, [runtime?.runtimeName, refreshCheckpoints, refreshAgents]);
     // Clear the manual override once a real runtimes fetch lands.
     useEffect(() => {
         if (runningAgentsOverride && agentRuntimes) {
@@ -188,7 +190,7 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
             return runningAgentsOverride;
         return (agentRuntimes || []).map(rt => ({
             id: rt.id,
-            podName: rt.pod_name,
+            runtimeName: rt.runtime_name,
             name: rt.name,
             description: rt.environment.title || rt.environment.name,
             status: rt.status,
@@ -212,12 +214,12 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
             return;
         }
         // Prevent reconnect loops to the same runtime while status remains idle/disconnected.
-        if (autoConnectAttemptRef.current === candidate.podName) {
+        if (autoConnectAttemptRef.current === candidate.runtimeName) {
             return;
         }
-        autoConnectAttemptRef.current = candidate.podName;
+        autoConnectAttemptRef.current = candidate.runtimeName;
         connectToRuntime({
-            podName: candidate.podName,
+            runtimeName: candidate.runtimeName,
             environmentName: candidate.environmentName,
             jupyterBaseUrl: candidate.jupyterBaseUrl,
         });
@@ -239,34 +241,30 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
         setActionLoading(true);
         setActionError(null);
         try {
-            const isCurrentRuntime = runtime?.podName === agent.podName;
+            const isCurrentRuntime = runtime?.runtimeName === agent.runtimeName;
             const isLastKnownRuntime = runningAgents.length === 1 &&
-                runningAgents[0].podName === agent.podName;
-            if (agent.status === 'paused') {
-                await deletePausedRuntimeByPod(agent.podName);
-            }
-            else {
-                await terminateRuntimeByPod(agent.podName);
-            }
-            // Ensure sidebar terminate resets to the home state like header terminate.
+                runningAgents[0].runtimeName === agent.runtimeName;
+            // One verb for both: stopping reaps the pod when there is one and the
+            // checkpoint records when there is not.
+            await stopRuntimeByName(agent.runtimeName);
+            // Ensure sidebar stop resets to the home state like the header's.
             if (isCurrentRuntime || isLastKnownRuntime) {
                 await terminate();
             }
             await Promise.all([refreshAgents(), refreshCheckpoints()]);
         }
         catch (e) {
-            setActionError(e instanceof Error ? e.message : 'Terminate failed');
+            setActionError(e instanceof Error ? e.message : 'Stop failed');
         }
         finally {
             setActionLoading(false);
         }
     }, [
-        deletePausedRuntimeByPod,
-        terminateRuntimeByPod,
+        stopRuntimeByName,
         refreshAgents,
         refreshCheckpoints,
         runningAgents,
-        runtime?.podName,
+        runtime?.runtimeName,
         terminate,
     ]);
     const pausedAgents = runningAgents.filter(a => a.status === 'paused');
@@ -274,7 +272,7 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
     const checkpointRuntimeIds = new Set(checkpoints
         .map((ckpt) => ckpt.runtime_uid)
         .filter((value) => Boolean(value)));
-    const pausedAgentsWithoutCheckpoint = pausedAgents.filter((a) => !checkpointRuntimeIds.has(a.podName));
+    const pausedAgentsWithoutCheckpoint = pausedAgents.filter((a) => !checkpointRuntimeIds.has(a.runtimeName));
     const showNoAgentRunningView = (runtimeStatus === 'idle' || runtimeStatus === 'disconnected') &&
         !isStarting;
     const showLaunchingView = runtimeStatus === 'launching' ||
@@ -298,7 +296,7 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
                     borderBottom: '1px solid',
                     borderColor: 'border.default',
                     flexShrink: 0,
-                }, children: [_jsx(Button, { size: "small", variant: "invisible", onClick: () => setSidebarOpen(prev => !prev), leadingVisual: sidebarOpen ? SidebarCollapseIcon : SidebarExpandIcon, "aria-label": sidebarOpen ? 'Collapse sidebar' : 'Expand sidebar' }), _jsxs(Heading, { as: "h3", sx: { fontSize: 2, flex: 1 }, children: ["Agent \u2014 ", podName] }), _jsx(Label, { variant: STATUS_COLORS[runtimeStatus], children: runtimeStatus }), (runtimeStatus === 'ready' ||
+                }, children: [_jsx(Button, { size: "small", variant: "invisible", onClick: () => setSidebarOpen(prev => !prev), leadingVisual: sidebarOpen ? SidebarCollapseIcon : SidebarExpandIcon, "aria-label": sidebarOpen ? 'Collapse sidebar' : 'Expand sidebar' }), _jsxs(Heading, { as: "h3", sx: { fontSize: 2, flex: 1 }, children: ["Agent \u2014 ", runtimeName] }), _jsx(Label, { variant: STATUS_COLORS[runtimeStatus], children: runtimeStatus }), (runtimeStatus === 'ready' ||
                         runtimeStatus === 'resumed' ||
                         runtimeStatus === 'resuming' ||
                         runtimeStatus === 'paused') && (_jsxs(_Fragment, { children: [_jsx(Button, { size: "small", leadingVisual: SquareIcon, onClick: () => handlePause('light'), disabled: actionLoading ||
@@ -386,7 +384,7 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
                                                     mt: 2,
                                                     display: 'flex',
                                                     justifyContent: 'flex-end',
-                                                }, children: _jsx(Button, { size: "small", variant: "primary", leadingVisual: PlayIcon, onClick: () => handleResume(resumeMode, undefined, a.podName), disabled: actionLoading, children: "Resume" }) })] }, `paused-${a.id}`))), checkpoints.length === 0 &&
+                                                }, children: _jsx(Button, { size: "small", variant: "primary", leadingVisual: PlayIcon, onClick: () => handleResume(resumeMode, undefined, a.runtimeName), disabled: actionLoading, children: "Resume" }) })] }, `paused-${a.id}`))), checkpoints.length === 0 &&
                                         pausedAgentsWithoutCheckpoint.length === 0 ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', fontStyle: 'italic' }, children: "No checkpoints yet. Use Checkpoint (Light) or Checkpoint create one." })) : (checkpoints.map((ckpt) => (_jsxs(Box, { sx: {
                                             p: 2,
                                             mb: 1,
@@ -436,16 +434,7 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
                                 gap: 3,
                                 px: 3,
                             }, children: [_jsx(AgentIcon, { size: 48 }), _jsx(Heading, { as: "h2", sx: { fontSize: 3 }, children: "Checkpoint Agent" }), _jsxs(Text, { sx: { color: 'fg.muted', textAlign: 'center', maxWidth: 560 }, children: ["Launch a cloud agent runtime with pause/resume checkpointing. The agent will be deployed from the", ' ', _jsx("strong", { children: AGENTSPEC_ID }), " spec."] }), displayError && (_jsx(Flash, { variant: "danger", sx: { maxWidth: 560, width: '100%' }, children: displayError })), _jsx(Button, { variant: "primary", size: "large", leadingVisual: PlayIcon, onClick: handleLaunch, children: "Launch Agent" })] })) : (isReady || runtimeStatus === 'resumed') &&
-                            runtimeStatus !== 'paused' ? (_jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, title: "Monitor Sales KPI Agent", brandIcon: _jsx(AgentIcon, { size: 16 }), placeholder: "Ask about sales KPIs\u2026", description: "Monitor Sales KPI agent with pause/resume checkpointing", showHeader: true, kernelIndicatorPlacement: "right", showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: podName, historyEndpoint: `${agentBaseUrl}/api/v1/history`, suggestions: [
-                                {
-                                    title: 'KPIs',
-                                    message: "Show me today's sales KPI dashboard",
-                                },
-                                {
-                                    title: 'Trends',
-                                    message: 'What are the current revenue trends?',
-                                },
-                            ], submitOnSuggestionClick: true })) : (_jsx(Box, { sx: {
+                            runtimeStatus !== 'paused' ? (_jsx(LoopEmbed, { serverUrl: agentBaseUrl, target: "local", agentId: agentId, defaultEditor: "none", showHeader: true, plugins: LOOP_PLUGINS_AGENTCHE })) : (_jsx(Box, { sx: {
                                 display: 'flex',
                                 flexDirection: 'column',
                                 alignItems: 'center',
@@ -456,8 +445,8 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
                             }, children: runtimeStatus === 'paused' ? (_jsx(Text, { sx: { fontSize: 2 }, children: "Agent is paused \u2014 click Resume to continue the conversation." })) : runtimeStatus === 'idle' ||
                                 runtimeStatus === 'disconnected' ? (_jsx(Text, { sx: { fontSize: 2 }, children: "No active runtime connection. Launch an agent or select one in the sidebar." })) : runtimeStatus === 'error' ? (_jsxs(_Fragment, { children: [_jsx(AlertIcon, { size: 32 }), _jsx(Text, { sx: { fontSize: 2, color: 'danger.fg' }, children: "Agent failed to connect" }), displayError && (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: displayError })), _jsx(Button, { variant: "primary", onClick: handleLaunch, children: "Retry Launch" })] })) : (_jsxs(_Fragment, { children: [_jsx(Spinner, { size: "medium" }), _jsxs(Text, { sx: { fontSize: 2 }, children: ["Connecting to agent\u2026 (status: ", runtimeStatus, ")"] })] })) })) })] })] }));
 };
-// ─── Main component with auth gate ─────────────────────────────────────────
-const AgentCheckpointsExample = () => {
+// ─── Runtime checkpoints: the cloud console, behind its auth gate ─────────
+const RuntimeCheckpointsExample = () => {
     const { token, clearAuth } = useSimpleAuthStore();
     const hasSynced = useRef(false);
     // Sync persisted token (from a previous session) to iamStore on mount
@@ -483,4 +472,33 @@ const AgentCheckpointsExample = () => {
     }
     return (_jsx(ThemedProvider, { children: _jsx(QueryClientProvider, { client: queryClient, children: _jsx(AgentCheckpointsInner, { onLogout: handleLogout }) }) }));
 };
+// ─── Conversation checkpoints: the Loop, the capacity and its sidebar ───────
+const LOCAL_AGENT_NAME = 'checkpoints-example-agent';
+const ConversationCheckpointsExample = () => {
+    const agentName = useMemo(() => uniqueAgentId(LOCAL_AGENT_NAME), []);
+    const plugins = useMemo(() => [AgentCheckpointsPlugin, CheckpointsSidebarPlugin], []);
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
+                height: '100%',
+                display: 'flex',
+                flexDirection: 'column',
+                bg: 'canvas.default',
+            }, children: [_jsxs(Box, { sx: {
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: 2,
+                        px: 3,
+                        py: 2,
+                        borderBottom: '1px solid',
+                        borderColor: 'border.default',
+                        flexShrink: 0,
+                    }, children: [_jsx(VersionsIcon, { size: 16 }), _jsx(Heading, { as: "h3", sx: { fontSize: 2, flex: 1 }, children: "Checkpoints Demo" }), _jsx(Label, { variant: "accent", children: "local" }), _jsx(Label, { variant: "accent", children: "conversation checkpoints" })] }), _jsx(Box, { sx: { flex: 1, minHeight: 0 }, children: _jsx(LoopEmbed, { serverUrl: resolveExampleAgentRuntimesUrl('local'), target: "local", showAgentVariants: true, agentId: agentName, editors: false, showHeader: true, plugins: plugins }) })] }) }));
+};
+// ─── The example: one capability, at the level the target offers it ─────────
+const AgentCheckpointsExample = () => {
+    const target = useRuntimeTargetStore(state => state.target);
+    // Runtime checkpoints exist only where a runtime does — the Datalayer
+    // target. Everywhere else the agent's own conversation checkpoints are
+    // the capability on show.
+    return target === 'datalayer' ? (_jsx(RuntimeCheckpointsExample, {})) : (_jsx(ConversationCheckpointsExample, {}));
+};
 export default AgentCheckpointsExample;

package/lib/examples/AgentCodeSandboxExample.d.ts

@@ -1,14 +1,14 @@
 /**
  * AgentCodeSandboxExample
  *
- * Demonstrates sandbox variant switching (eval / jupyter) with a live
- * sidebar that streams WebSocket messages to and from the
- * `/configure/sandbox/ws` endpoint.
+ * The code sandbox: the agent runs Python through `execute_code` in a sandbox
+ * the server manages, and the page shows that sandbox.
  *
- * - Creates a local agent (spec: example-full) with codemode enabled
- * - SegmentedControl toggles between "eval" and "jupyter" variants
- * - Sidebar shows live sandbox status, WebSocket event log, and an
- *   interrupt button
+ * - The Loop creates the `example-code-sandbox` agent on the Local target
+ * - A control above the chat switches this agent's sandbox variant (eval /
+ *   jupyter) live, through `/agents/{id}/sandbox/ensure`
+ * - A sidebar follows the sandbox over `/configure/sandbox/ws`: its variant,
+ *   whether it runs and executes, the raw messages, and an interrupt button
  *
  * @module examples/AgentCodeSandboxExample
  */