@datalayer/agent-runtimes 1.0.29 → 1.3.10

package/lib/agents/AgentDetails.js

@@ -1,5 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { ArrowLeftIcon, CheckCircleIcon, XCircleIcon, CodeIcon, BriefcaseIcon, DownloadIcon, NoteIcon, ServerIcon, } from '@primer/octicons-react';
+// Copyright (c) 2025-2026 Datalayer, Inc.
+// Distributed under the terms of the Modified BSD License.
+/**
+ * AgentDetails component - Shows detailed information about the agent
+ * including name, protocol, URL, message count, and context details.
+ */
+import { useState } from 'react';
+import { ArrowLeftIcon, CheckCircleIcon, XCircleIcon, CodeIcon, BriefcaseIcon, DownloadIcon, FileCodeIcon, NoteIcon, ServerIcon, } from '@primer/octicons-react';
 import { Button, Heading, IconButton, Text, Label, Spinner, ToggleSwitch, } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { AiAgentIcon } from '@datalayer/icons-react';
@@ -7,6 +14,7 @@ import { useQuery, useMutation } from '@tanstack/react-query';
 import { ContextPanel } from '../context/ContextPanel';
 import { ContextInspector, } from '../context/ContextInspector';
 import { AgentIdentity } from '../identity/AgentIdentity';
+import { SpecPayloadPreview } from '../components/specs/SpecPayloadPreview';
 import { useAgentRuntimeCodemodeStatus, useAgentRuntimeContextSnapshot, useAgentRuntimeFullContext, useAgentRuntimeMcpStatus, useAgentRuntimeWsState, } from '../stores';
 /**
  * Get the API base URL for fetching data.
@@ -15,7 +23,21 @@ import { useAgentRuntimeCodemodeStatus, useAgentRuntimeContextSnapshot, useAgent
  */
 function getApiBase(apiBase) {
     if (apiBase) {
-        return apiBase;
+        /*
+         * The server's root, whatever the caller handed over.
+         *
+         * `apiBase` is a base and every request below appends its own path to it —
+         * but the commonest thing to have on hand is the protocol's
+         * `configEndpoint`, which already ends in `/api/v1/configure`. Passing
+         * that produced
+         * `/api/v1/configure/api/v1/configure/agents/.../spec`, a 404 that reached
+         * the reader as "Loading agent spec" for ever.
+         *
+         * Trimmed here rather than at each call site: this function exists to
+         * answer "where is the server", and a caller that knows an endpoint knows
+         * the server too.
+         */
+        return apiBase.replace(/\/+$/, '').replace(/\/api\/v1\/configure$/, '');
     }
     if (typeof window === 'undefined') {
         return '';
@@ -164,7 +186,7 @@ async function downloadContextSnapshotAsCSV(agentId, _apiBase, preloadedData) {
 /**
  * AgentDetails component displays comprehensive information about the agent.
  */
-export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, messageCount, agentId, apiBase, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, showBackHeader = true, showUsage = true, mcpStatusData, codemodeStatusData, contextSnapshotData, fullContextData, }) {
+export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, messageCount, agentId, apiBase, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, showBackHeader = true, showUsage = true, padded = true, mcpStatusData, codemodeStatusData, contextSnapshotData, fullContextData, }) {
     const wsMcpStatus = useAgentRuntimeMcpStatus();
     const wsCodemodeStatus = useAgentRuntimeCodemodeStatus();
     const wsContextSnapshot = useAgentRuntimeContextSnapshot();
@@ -202,6 +224,9 @@ export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, me
         },
     });
     // Fetch agent spec (original creation request with separated system prompts)
+    /* Whether the full spec is on screen. Its own state: it is a detour from
+       the summary, not a mode the pane lives in. */
+    const [showSpecPayload, setShowSpecPayload] = useState(false);
     const { data: agentSpec, isLoading: specLoading } = useQuery({
         queryKey: ['agent-spec', agentId, apiBase],
         queryFn: async () => {
@@ -227,7 +252,12 @@ export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, me
                     p: 3,
                     borderBottom: '1px solid',
                     borderColor: 'border.default',
-                }, children: [_jsx(IconButton, { icon: ArrowLeftIcon, "aria-label": "Back to chat", variant: "invisible", onClick: onBack }), _jsx(Heading, { as: "h2", sx: { fontSize: 3, fontWeight: 'semibold' }, children: "Agent Details" })] })), _jsxs(Box, { sx: { p: 3, display: 'flex', flexDirection: 'column', gap: 4 }, children: [_jsxs(Box, { sx: {
+                }, children: [_jsx(IconButton, { icon: ArrowLeftIcon, "aria-label": "Back to chat", variant: "invisible", onClick: onBack }), _jsx(Heading, { as: "h2", sx: { fontSize: 3, fontWeight: 'semibold' }, children: "Agent Details" })] })), _jsxs(Box, { sx: {
+                    p: padded ? 3 : 0,
+                    display: 'flex',
+                    flexDirection: 'column',
+                    gap: 4,
+                }, children: [_jsxs(Box, { sx: {
                             display: 'flex',
                             alignItems: 'center',
                             gap: 3,
@@ -260,13 +290,13 @@ export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, me
                                     fontWeight: 'semibold',
                                     mb: 2,
                                     color: 'fg.muted',
-                                }, children: "Agent Spec" }), _jsx(Box, { sx: {
+                                }, children: "Agentspec" }), _jsx(Box, { sx: {
                                     p: 3,
                                     bg: 'canvas.subtle',
                                     borderRadius: 2,
                                     border: '1px solid',
                                     borderColor: 'border.default',
-                                }, children: specLoading ? (_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Loading agent spec..." })] })) : agentSpec ? (_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 3 }, children: [_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 1 }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', width: 100 }, children: "Model:" }), _jsx(Text, { sx: {
+                                }, children: specLoading ? (_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Loading agent spec..." })] })) : agentSpec ? (_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 3 }, children: [_jsx(Box, { children: _jsx(Button, { size: "small", leadingVisual: FileCodeIcon, onClick: () => setShowSpecPayload(true), children: "View spec payload" }) }), _jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 1 }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', width: 100 }, children: "Model:" }), _jsx(Text, { sx: {
                                                                 fontSize: 0,
                                                                 fontFamily: 'mono',
                                                                 color: 'fg.default',
@@ -317,7 +347,7 @@ export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, me
                                     borderRadius: 2,
                                     border: '1px solid',
                                     borderColor: 'border.default',
-                                }, children: _jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(ServerIcon, { size: 16 }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', width: 100 }, children: "Variant:" }), _jsx(Label, { variant: agentSpec.sandbox.variant === 'jupyter'
+                                }, children: _jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(ServerIcon, { size: 16 }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', width: 100 }, children: "Variant:" }), _jsx(Label, { variant: agentSpec.sandbox.variant === 'jupyter-server'
                                                         ? 'accent'
                                                         : 'secondary', size: "small", children: agentSpec.sandbox.variant })] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', width: 100, pl: 4 }, children: "Running:" }), agentSpec.sandbox.sandbox_running ? (_jsxs(Box, { sx: {
                                                         display: 'flex',
@@ -327,7 +357,7 @@ export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, me
                                                         display: 'flex',
                                                         alignItems: 'center',
                                                         gap: 1,
-                                                    }, children: [_jsx(XCircleIcon, { size: 12, fill: "fg.muted" }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "No" })] }))] }), agentSpec.sandbox.variant === 'jupyter' && (_jsxs(_Fragment, { children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Text, { sx: {
+                                                    }, children: [_jsx(XCircleIcon, { size: 12, fill: "fg.muted" }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "No" })] }))] }), agentSpec.sandbox.variant === 'jupyter-server' && (_jsxs(_Fragment, { children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Text, { sx: {
                                                                 fontSize: 0,
                                                                 color: 'fg.muted',
                                                                 width: 100,
@@ -473,9 +503,9 @@ export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, me
                                                         flexDirection: 'column',
                                                         gap: 1,
                                                         pl: 4,
-                                                    }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', width: 80 }, children: "Variant:" }), _jsx(Label, { variant: codemodeStatus.sandbox.variant === 'jupyter'
+                                                    }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', width: 80 }, children: "Variant:" }), _jsx(Label, { variant: codemodeStatus.sandbox.variant === 'jupyter-server'
                                                                         ? 'accent'
-                                                                        : 'secondary', size: "small", children: codemodeStatus.sandbox.variant })] }), codemodeStatus.sandbox.variant === 'jupyter' && (_jsxs(_Fragment, { children: [_jsxs(Box, { sx: {
+                                                                        : 'secondary', size: "small", children: codemodeStatus.sandbox.variant })] }), codemodeStatus.sandbox.variant === 'jupyter-server' && (_jsxs(_Fragment, { children: [_jsxs(Box, { sx: {
                                                                         display: 'flex',
                                                                         alignItems: 'center',
                                                                         gap: 2,
@@ -575,6 +605,6 @@ export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, me
                                     borderRadius: 2,
                                     border: '1px solid',
                                     borderColor: 'border.default',
-                                }, children: _jsx(ContextInspector, { agentId: agentId, apiBase: apiBase, liveData: resolvedFullContext }) })] })), _jsx(AgentIdentity, { providers: identityProviders, title: "Connected Accounts", showHeader: true, showDescription: true, description: "OAuth identities connected to this agent. Agents can use these to access external services like GitHub repositories on your behalf.", showExpirationDetails: true, allowReconnect: Boolean(identityProviders), onConnect: onIdentityConnect, onDisconnect: onIdentityDisconnect }), showBackHeader && (_jsx(Box, { sx: { mt: 2 }, children: _jsx(Button, { variant: "primary", onClick: onBack, sx: { width: '100%' }, children: "Back to Chat" }) }))] })] }));
+                                }, children: _jsx(ContextInspector, { agentId: agentId, apiBase: apiBase, liveData: resolvedFullContext }) })] })), _jsx(AgentIdentity, { providers: identityProviders, title: "Connected Accounts", showHeader: true, showDescription: true, description: "OAuth identities connected to this agent. Agents can use these to access external services like GitHub repositories on your behalf.", showExpirationDetails: true, allowReconnect: Boolean(identityProviders), onConnect: onIdentityConnect, onDisconnect: onIdentityDisconnect }), showBackHeader && (_jsx(Box, { sx: { mt: 2 }, children: _jsx(Button, { variant: "primary", onClick: onBack, sx: { width: '100%' }, children: "Back to Chat" }) }))] }), showSpecPayload && agentSpec ? (_jsx(SpecPayloadPreview, { spec: agentSpec, onClose: () => setShowSpecPayload(false) })) : null] }));
 }
 export default AgentDetails;

package/lib/agents/AgentRuntimeChat.d.ts

@@ -3,7 +3,7 @@
  *
  * This is the shared component used to render the plain (non-floating) chat
  * view for an agent runtime. It is designed to be reused across the app:
- * - The agent runtime detail page (e.g. `/agents/runtime-...`).
+ * - The agent runtime detail page (`/agents/<uid>`).
  * - Gallery example pages (e.g. `/gallery/agents/analyze-excel-spreadsheet`).
  *
  * Behaviour:
@@ -26,7 +26,7 @@ import type { Protocol, Suggestion } from '../types';
  * Props for {@link AgentRuntimeChat}.
  */
 export interface AgentRuntimeChatProps {
-    /** Agentspec id to launch, e.g. `gallery-analyze-excel-spreadsheet`. */
+    /** Agentspec id to launch, e.g. `example-analyze-excel-spreadsheet`. */
     agentSpecId: string;
     /** Human-friendly title shown in the chat header. */
     title?: string;
@@ -69,5 +69,5 @@ export interface AgentRuntimeChatProps {
  * @param props - Component props.
  * @returns The rendered chat surface.
  */
-export declare function AgentRuntimeChat({ agentSpecId, title, brandIcon, description, protocol, height, suggestions, overlay, launch, showModelSelector, showToolsMenu, showSkillsMenu, showHeader, showPoweredBy, agentConfig, onRuntimeChange, }: AgentRuntimeChatProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AgentRuntimeChat({ agentSpecId, title, brandIcon, description, protocol, height, suggestions, overlay, launch, showModelSelector, showToolsMenu, showSkillsMenu, showHeader, showPoweredBy, agentConfig, onRuntimeChange, }: AgentRuntimeChatProps): import("react").JSX.Element | null;
 export default AgentRuntimeChat;

package/lib/agents/AgentRuntimeChat.js

@@ -6,7 +6,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *
  * This is the shared component used to render the plain (non-floating) chat
  * view for an agent runtime. It is designed to be reused across the app:
- * - The agent runtime detail page (e.g. `/agents/runtime-...`).
+ * - The agent runtime detail page (`/agents/<uid>`).
  * - Gallery example pages (e.g. `/gallery/agents/analyze-excel-spreadsheet`).
  *
  * Behaviour:
@@ -57,29 +57,29 @@ export function AgentRuntimeChat({ agentSpecId, title, brandIcon, description, p
     const launchingError = launch ? error : null;
     const runtimeAgentId = runtime?.agentId || '';
     const hasAssignedAgent = runtimeAgentId.trim().length > 0;
-    const assignmentAttemptedForPodRef = useRef(null);
+    const assignmentAttemptedForRuntimeRef = useRef(null);
     const launchStateLogRef = useRef('');
     const isInteractiveReady = launch && isReady && !!endpoint && hasAssignedAgent;
     useEffect(() => {
-        const podName = String(runtime?.podName || '').trim();
-        if (!podName) {
-            assignmentAttemptedForPodRef.current = null;
+        const runtimeName = String(runtime?.runtimeName || '').trim();
+        if (!runtimeName) {
+            assignmentAttemptedForRuntimeRef.current = null;
             return;
         }
         if (hasAssignedAgent) {
-            assignmentAttemptedForPodRef.current = podName;
+            assignmentAttemptedForRuntimeRef.current = runtimeName;
             return;
         }
         if (!launch || !isReady || !endpoint || !!error || isCreating) {
             return;
         }
-        if (assignmentAttemptedForPodRef.current === podName) {
+        if (assignmentAttemptedForRuntimeRef.current === runtimeName) {
             return;
         }
-        assignmentAttemptedForPodRef.current = podName;
+        assignmentAttemptedForRuntimeRef.current = runtimeName;
         void createAgent();
     }, [
-        runtime?.podName,
+        runtime?.runtimeName,
         hasAssignedAgent,
         launch,
         isReady,
@@ -101,7 +101,7 @@ export function AgentRuntimeChat({ agentSpecId, title, brandIcon, description, p
                     : 'ready';
         const signature = [
             state,
-            String(runtime?.podName || ''),
+            String(runtime?.runtimeName || ''),
             String(endpoint || ''),
         ].join('|');
         if (launchStateLogRef.current === signature) {
@@ -111,7 +111,7 @@ export function AgentRuntimeChat({ agentSpecId, title, brandIcon, description, p
         if (state === 'error') {
             console.error('[AgentRuntimeChat] launch failed', {
                 agentSpecId,
-                podName: runtime?.podName,
+                runtimeName: runtime?.runtimeName,
                 endpoint,
                 error: launchingError,
             });
@@ -120,7 +120,7 @@ export function AgentRuntimeChat({ agentSpecId, title, brandIcon, description, p
         if (state === 'waiting-endpoint') {
             console.info('[AgentRuntimeChat] waiting for runtime endpoint', {
                 agentSpecId,
-                podName: runtime?.podName,
+                runtimeName: runtime?.runtimeName,
                 isReady,
                 endpoint,
             });
@@ -129,14 +129,14 @@ export function AgentRuntimeChat({ agentSpecId, title, brandIcon, description, p
         if (state === 'waiting-assignment') {
             console.info('[AgentRuntimeChat] waiting for agent assignment', {
                 agentSpecId,
-                podName: runtime?.podName,
+                runtimeName: runtime?.runtimeName,
                 endpoint,
             });
             return;
         }
         console.info('[AgentRuntimeChat] runtime ready', {
             agentSpecId,
-            podName: runtime?.podName,
+            runtimeName: runtime?.runtimeName,
             endpoint,
             agentId: runtimeAgentId,
         });
@@ -147,7 +147,7 @@ export function AgentRuntimeChat({ agentSpecId, title, brandIcon, description, p
         isReady,
         endpoint,
         hasAssignedAgent,
-        runtime?.podName,
+        runtime?.runtimeName,
         runtimeAgentId,
         agentSpecId,
     ]);

package/lib/api/agents.d.ts

@@ -9,39 +9,39 @@ export declare const getRunningAgents: (token: string, baseUrl?: string) => Prom
 /**
  * Get detailed status for a specific agent.
  * @param token - Authentication token
- * @param podName - Pod name hosting the agent
+ * @param runtimeName - The uid of the runtime hosting the agent
  * @param agentId - Agent ID within the pod (optional, defaults to primary)
  * @param baseUrl - Base URL
  * @returns Promise resolving to agent status
  */
-export declare const getAgentStatus: (token: string, podName: string, agentId?: string, baseUrl?: string) => Promise<RunningAgent>;
+export declare const getAgentStatus: (token: string, runtimeName: string, agentId?: string, baseUrl?: string) => Promise<RunningAgent>;
 /**
  * Pause a running agent (light checkpoint by default, CRIU optional).
  * @param token - Authentication token
- * @param podName - Pod name
+ * @param runtimeName - The uid of the runtime
  * @param baseUrl - Base URL
  */
-export declare const pauseAgent: (token: string, podName: string, baseUrl?: string) => Promise<void>;
+export declare const pauseAgent: (token: string, runtimeName: string, baseUrl?: string) => Promise<void>;
 /**
  * Resume a paused/checkpointed agent.
  * @param token - Authentication token
- * @param podName - Pod name
+ * @param runtimeName - The uid of the runtime
  * @param baseUrl - Base URL
  */
-export declare const resumeAgent: (token: string, podName: string, baseUrl?: string) => Promise<void>;
+export declare const resumeAgent: (token: string, runtimeName: string, baseUrl?: string) => Promise<void>;
 /**
  * Get conversation checkpoints for an agent.
  * @param token - Authentication token
- * @param podName - Pod name
+ * @param runtimeName - The uid of the runtime
  * @param agentId - Agent ID
  * @param baseUrl - Base URL
  */
-export declare const getAgentCheckpoints: (token: string, podName: string, agentId?: string, baseUrl?: string) => Promise<ConversationCheckpoint[]>;
+export declare const getAgentCheckpoints: (token: string, runtimeName: string, agentId?: string, baseUrl?: string) => Promise<ConversationCheckpoint[]>;
 /**
  * Get usage summary for an agent.
  * @param token - Authentication token
- * @param podName - Pod name
+ * @param runtimeName - The uid of the runtime
  * @param agentId - Agent ID
  * @param baseUrl - Base URL
  */
-export declare const getAgentUsage: (token: string, podName: string, agentId?: string, baseUrl?: string) => Promise<AgentUsageSummary>;
+export declare const getAgentUsage: (token: string, runtimeName: string, agentId?: string, baseUrl?: string) => Promise<AgentUsageSummary>;

package/lib/api/agents.js

@@ -30,16 +30,16 @@ export const getRunningAgents = async (token, baseUrl = DEFAULT_SERVICE_URLS.AI_
 /**
  * Get detailed status for a specific agent.
  * @param token - Authentication token
- * @param podName - Pod name hosting the agent
+ * @param runtimeName - The uid of the runtime hosting the agent
  * @param agentId - Agent ID within the pod (optional, defaults to primary)
  * @param baseUrl - Base URL
  * @returns Promise resolving to agent status
  */
-export const getAgentStatus = async (token, podName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+export const getAgentStatus = async (token, runtimeName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
     validateToken(token);
     const query = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : '';
     return requestDatalayerAPI({
-        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}${query}`,
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(runtimeName)}${query}`,
         method: 'GET',
         token,
     });
@@ -47,13 +47,13 @@ export const getAgentStatus = async (token, podName, agentId, baseUrl = DEFAULT_
 /**
  * Pause a running agent (light checkpoint by default, CRIU optional).
  * @param token - Authentication token
- * @param podName - Pod name
+ * @param runtimeName - The uid of the runtime
  * @param baseUrl - Base URL
  */
-export const pauseAgent = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+export const pauseAgent = async (token, runtimeName, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
     validateToken(token);
     await requestDatalayerAPI({
-        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/pause`,
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(runtimeName)}/pause`,
         method: 'POST',
         token,
     });
@@ -61,13 +61,13 @@ export const pauseAgent = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.
 /**
  * Resume a paused/checkpointed agent.
  * @param token - Authentication token
- * @param podName - Pod name
+ * @param runtimeName - The uid of the runtime
  * @param baseUrl - Base URL
  */
-export const resumeAgent = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+export const resumeAgent = async (token, runtimeName, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
     validateToken(token);
     await requestDatalayerAPI({
-        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/resume`,
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(runtimeName)}/resume`,
         method: 'POST',
         token,
     });
@@ -75,15 +75,15 @@ export const resumeAgent = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS
 /**
  * Get conversation checkpoints for an agent.
  * @param token - Authentication token
- * @param podName - Pod name
+ * @param runtimeName - The uid of the runtime
  * @param agentId - Agent ID
  * @param baseUrl - Base URL
  */
-export const getAgentCheckpoints = async (token, podName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+export const getAgentCheckpoints = async (token, runtimeName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
     validateToken(token);
     const query = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : '';
     return requestDatalayerAPI({
-        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/checkpoints${query}`,
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(runtimeName)}/checkpoints${query}`,
         method: 'GET',
         token,
     });
@@ -91,15 +91,15 @@ export const getAgentCheckpoints = async (token, podName, agentId, baseUrl = DEF
 /**
  * Get usage summary for an agent.
  * @param token - Authentication token
- * @param podName - Pod name
+ * @param runtimeName - The uid of the runtime
  * @param agentId - Agent ID
  * @param baseUrl - Base URL
  */
-export const getAgentUsage = async (token, podName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+export const getAgentUsage = async (token, runtimeName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
     validateToken(token);
     const query = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : '';
     return requestDatalayerAPI({
-        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/usage${query}`,
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(runtimeName)}/usage${query}`,
         method: 'GET',
         token,
     });

package/lib/api/checkpoints.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Conversation checkpoints of an agent on a local agent-runtimes server.
+ *
+ * The agent takes its own checkpoints as it runs; these calls let a page see
+ * them, take one between turns, rewind to one and drop one. They speak to
+ * `/api/v1/agents/{id}/checkpoints` on the server the workspace is backed by,
+ * as the Loop's other local calls do — no token, the local server checks
+ * none.
+ *
+ * @module api/checkpoints
+ */
+import type { ConversationCheckpoint, ConversationCheckpointsState } from '../types/checkpoints';
+type CheckpointWire = {
+    id: string;
+    label: string;
+    turn: number;
+    message_count: number;
+    created_at: string;
+    auto?: boolean;
+    metadata?: Record<string, unknown>;
+};
+/** The server's record, in the shape the rest of the library already uses. */
+export declare function toConversationCheckpoint(wire: CheckpointWire): ConversationCheckpoint;
+/** Whether the checkpoint was taken by the agent on its own. */
+export declare const isAutoCheckpoint: (checkpoint: ConversationCheckpoint) => boolean;
+/** The agent's checkpoint configuration and its checkpoints, newest first. */
+export declare function listConversationCheckpoints(serverUrl: string, agentId: string): Promise<ConversationCheckpointsState>;
+/** Take a checkpoint of the conversation as the last turn left it. */
+export declare function saveConversationCheckpoint(serverUrl: string, agentId: string, label: string): Promise<ConversationCheckpoint>;
+/**
+ * Set the conversation back to a checkpoint. The server pushes a fresh
+ * snapshot; the chat reloads its transcript from it.
+ */
+export declare function rewindConversation(serverUrl: string, agentId: string, checkpointId: string): Promise<{
+    checkpoint: ConversationCheckpoint;
+    messageCount: number;
+}>;
+/** Drop a checkpoint. */
+export declare function deleteConversationCheckpoint(serverUrl: string, agentId: string, checkpointId: string): Promise<void>;
+export {};

package/lib/api/checkpoints.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+const trimSlash = (url) => url.replace(/\/+$/, '');
+const base = (serverUrl, agentId) => `${trimSlash(serverUrl)}/api/v1/agents/${encodeURIComponent(agentId)}/checkpoints`;
+async function call(url, init) {
+    const response = await fetch(url, {
+        ...init,
+        headers: { 'Content-Type': 'application/json', ...(init?.headers ?? {}) },
+    });
+    if (!response.ok) {
+        let detail = '';
+        try {
+            const body = (await response.json());
+            detail = typeof body.detail === 'string' ? body.detail : '';
+        }
+        catch {
+            // The status line is the message then.
+        }
+        throw new Error(detail || `${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+}
+/** The server's record, in the shape the rest of the library already uses. */
+export function toConversationCheckpoint(wire) {
+    return {
+        id: wire.id,
+        label: wire.label,
+        turn: wire.turn,
+        messageCount: wire.message_count,
+        createdAt: wire.created_at,
+        metadata: { ...(wire.metadata ?? {}), auto: wire.auto === true },
+    };
+}
+/** Whether the checkpoint was taken by the agent on its own. */
+export const isAutoCheckpoint = (checkpoint) => checkpoint.metadata?.auto === true;
+/** The agent's checkpoint configuration and its checkpoints, newest first. */
+export async function listConversationCheckpoints(serverUrl, agentId) {
+    const wire = await call(base(serverUrl, agentId));
+    return {
+        agentId: wire.agent_id,
+        enabled: wire.enabled,
+        frequency: wire.frequency,
+        maxCheckpoints: wire.max_checkpoints,
+        store: wire.store,
+        turn: wire.turn ?? 0,
+        checkpoints: (wire.checkpoints ?? []).map(toConversationCheckpoint),
+    };
+}
+/** Take a checkpoint of the conversation as the last turn left it. */
+export async function saveConversationCheckpoint(serverUrl, agentId, label) {
+    const wire = await call(base(serverUrl, agentId), {
+        method: 'POST',
+        body: JSON.stringify({ label }),
+    });
+    return toConversationCheckpoint(wire);
+}
+/**
+ * Set the conversation back to a checkpoint. The server pushes a fresh
+ * snapshot; the chat reloads its transcript from it.
+ */
+export async function rewindConversation(serverUrl, agentId, checkpointId) {
+    const wire = await call(`${base(serverUrl, agentId)}/${encodeURIComponent(checkpointId)}/rewind`, {
+        method: 'POST',
+    });
+    return {
+        checkpoint: toConversationCheckpoint(wire.checkpoint),
+        messageCount: wire.message_count,
+    };
+}
+/** Drop a checkpoint. */
+export async function deleteConversationCheckpoint(serverUrl, agentId, checkpointId) {
+    await call(`${base(serverUrl, agentId)}/${encodeURIComponent(checkpointId)}`, { method: 'DELETE' });
+}

package/lib/api/index.d.ts

@@ -7,6 +7,7 @@
  * @module api
  */
 export * as agents from './agents';
+export * as conversationCheckpoints from './checkpoints';
 export * as context from './context';
 export * as evals from './evals';
 export * as events from './events';

package/lib/api/index.js

@@ -15,6 +15,7 @@
 // approval interactions flow over the websocket stream; see
 // `hooks/useToolApprovals` and `components/ToolApprovalBanner`.
 export * as agents from './agents';
+export * as conversationCheckpoints from './checkpoints';
 export * as context from './context';
 export * as evals from './evals';
 export * as events from './events';
@@ -58,7 +59,7 @@ export async function getSandboxSnapshots(token, baseUrl) {
 export async function createSandboxSnapshot(data, token, baseUrl) {
     // Legacy browser snapshots pass a rich object (connection, metadata, callbacks)
     // that is handled client-side. Keep compatibility by returning early.
-    if (!('pod_name' in data)) {
+    if (!('runtime_name' in data)) {
         return data;
     }
     const response = await createSnapshot(resolveToken(token), data, resolveRuntimesUrl(baseUrl));

package/lib/api/notifications.d.ts

@@ -1,6 +1,20 @@
 import type { AgentNotification, NotificationFilters } from '../types';
+/** One notification as the service answers it. */
+interface NotificationRecord {
+    id: string;
+    agent_id?: string;
+    level?: string;
+    category?: string;
+    title?: string;
+    message?: string;
+    read?: boolean;
+    created_at?: string | null;
+    metadata?: Record<string, unknown>;
+}
+/** A record of the service as the notification this client returns. */
+export declare const toAgentNotification: (record: NotificationRecord) => AgentNotification;
 /**
- * List agent notifications with optional filters.
+ * List the caller's notifications with optional filters.
  * @param token - Authentication token
  * @param filters - Optional filters (agentId, level, unreadOnly, category, limit, offset)
  * @param baseUrl - Base URL
@@ -8,7 +22,7 @@ import type { AgentNotification, NotificationFilters } from '../types';
  */
 export declare const getNotifications: (token: string, filters?: NotificationFilters, baseUrl?: string) => Promise<AgentNotification[]>;
 /**
- * Get a specific notification by ID.
+ * Get one of the caller's notifications by ID.
  * @param token - Authentication token
  * @param id - Notification ID
  * @param baseUrl - Base URL
@@ -22,14 +36,14 @@ export declare const getNotification: (token: string, id: string, baseUrl?: stri
  */
 export declare const markNotificationRead: (token: string, id: string, baseUrl?: string) => Promise<void>;
 /**
- * Mark all notifications as read.
+ * Mark the caller's notifications as read: the ones named, or all of them.
  * @param token - Authentication token
- * @param agentId - Optional: only for a specific agent
+ * @param notificationIds - Optional: only these notifications
  * @param baseUrl - Base URL
  */
-export declare const markAllRead: (token: string, agentId?: string, baseUrl?: string) => Promise<void>;
+export declare const markAllRead: (token: string, notificationIds?: string[], baseUrl?: string) => Promise<void>;
 /**
- * Get count of unread notifications.
+ * Get the count of the caller's unread notifications.
  * @param token - Authentication token
  * @param baseUrl - Base URL
  * @returns Promise resolving to unread count
@@ -37,3 +51,4 @@ export declare const markAllRead: (token: string, agentId?: string, baseUrl?: st
 export declare const getUnreadCount: (token: string, baseUrl?: string) => Promise<{
     count: number;
 }>;
+export {};