@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/hooks/useAgentRuntimes.js

@@ -24,11 +24,31 @@ import { parseAgentStreamMessage, } from '../types/stream';
 import { DEFAULT_AGENT_CONFIG } from '../types/config';
 import { ServiceManager } from '@jupyterlab/services/lib/manager';
 import { disposeSandboxServiceManagers } from '../services/sandboxServiceManagers';
+import { runtimeUrl, runtimesUrl } from '../runtimes/lifecycle';
+import { legacyTargetOf, locationOf, runsInBrowser, toAgentRuntimeVariant, } from '../runtimes/variants';
 // ═══════════════════════════════════════════════════════════════════════════
 // Constants
 // ═══════════════════════════════════════════════════════════════════════════
 /** Stable fallback to avoid new-reference on every render. */
 const EMPTY_RUNTIMES = [];
+/**
+ * What a browser agent has instead of a runtime.
+ *
+ * Every field that names a host is empty because there is no host: the loop
+ * runs in this page, so there is no pod, no Jupyter server and no agent
+ * service to address. It is ready because nothing has to happen first.
+ *
+ * Frozen and shared rather than built per call, so a host comparing the value
+ * it got back sees the same object each time.
+ */
+const BROWSER_AGENT_CONNECTION = Object.freeze({
+    runtimeName: '',
+    environmentName: '',
+    jupyterBaseUrl: '',
+    agentBaseUrl: '',
+    status: 'ready',
+    isReady: true,
+});
 /** Default query options for all agent runtime queries. */
 export const AGENT_QUERY_OPTIONS = {
     staleTime: 5 * 60 * 1000, // 5 minutes
@@ -40,7 +60,7 @@ export const agentQueryKeys = {
         all: () => ['agentRuntimes'],
         lists: () => [...agentQueryKeys.agentRuntimes.all(), 'list'],
         details: () => [...agentQueryKeys.agentRuntimes.all(), 'detail'],
-        detail: (podName) => [...agentQueryKeys.agentRuntimes.details(), podName],
+        detail: (runtimeName) => [...agentQueryKeys.agentRuntimes.details(), runtimeName],
     },
     checkpoints: {
         all: () => ['checkpoints'],
@@ -64,12 +84,12 @@ export const agentQueryKeys = {
  * forever; resume/create mutations also clear the tombstone eagerly.
  */
 const DELETED_POD_TOMBSTONE_TTL_MS = 5 * 60 * 1000;
-const deletedRuntimePodTombstones = new Map();
+const deletedRuntimeTombstones = new Map();
 /** Mark a runtime pod as deleted by this client (tombstone). */
-export function markRuntimePodDeleted(podName) {
-    const normalized = String(podName || '').trim();
+export function markRuntimeDeleted(runtimeName) {
+    const normalized = String(runtimeName || '').trim();
     if (normalized) {
-        deletedRuntimePodTombstones.set(normalized, Date.now());
+        deletedRuntimeTombstones.set(normalized, Date.now());
         // Centralized teardown: dispose every ServiceManager any surface opened
         // against this pod's sandbox so their kernelspecs/sessions/users pollers
         // stop immediately instead of waiting for query-cache propagation.
@@ -77,8 +97,8 @@ export function markRuntimePodDeleted(podName) {
     }
 }
 /** Clear a deleted-pod tombstone (pod legitimately exists again). */
-export function clearRuntimePodDeleted(podName) {
-    deletedRuntimePodTombstones.delete(String(podName || '').trim());
+export function clearRuntimeDeleted(runtimeName) {
+    deletedRuntimeTombstones.delete(String(runtimeName || '').trim());
 }
 /** Statuses that imply a live pod the client would connect to. */
 const LIVE_RUNTIME_STATUSES = new Set([
@@ -93,13 +113,13 @@ const LIVE_RUNTIME_STATUSES = new Set([
  * Checkpoint-synthesised `paused` records pass through (no live pod to poll).
  */
 function isStaleDeletedRuntime(runtime) {
-    const podName = String(runtime?.pod_name || '').trim();
-    const deletedAt = deletedRuntimePodTombstones.get(podName);
+    const runtimeName = String(runtime?.runtime_name || '').trim();
+    const deletedAt = deletedRuntimeTombstones.get(runtimeName);
     if (deletedAt === undefined) {
         return false;
     }
     if (Date.now() - deletedAt > DELETED_POD_TOMBSTONE_TTL_MS) {
-        deletedRuntimePodTombstones.delete(podName);
+        deletedRuntimeTombstones.delete(runtimeName);
         return false;
     }
     return LIVE_RUNTIME_STATUSES.has(runtime.status);
@@ -290,14 +310,6 @@ export async function createServiceManagerFromAgentSandbox(info, authToken) {
 function toAgentRuntimeData(raw) {
     const status = typeof raw.status === 'string' ? raw.status.toLowerCase() : '';
     const normalizedStatus = RUNTIME_STATUS_MAP[status] ?? 'running';
-    const rawVolumeUids = Array.isArray(raw.volume_uids)
-        ? raw.volume_uids
-        : raw.volume_uid
-            ? [raw.volume_uid]
-            : [];
-    const volume_uids = rawVolumeUids
-        .map((uid) => String(uid || '').trim())
-        .filter(Boolean);
     const environment = raw.environment;
     return {
         ...raw,
@@ -310,13 +322,14 @@ function toAgentRuntimeData(raw) {
             resources: environment?.resources,
         },
         status: normalizedStatus,
-        name: raw.given_name || raw.pod_name,
-        id: raw.pod_name,
+        name: raw.given_name || raw.runtime_name,
+        id: raw.runtime_name,
         url: raw.ingress,
         messageCount: 0,
         agent_spec_id: raw.agent_spec_id || undefined,
-        volume_uids,
-        volume_uid: raw.volume_uid || volume_uids[0] || undefined,
+        content_attachments: Array.isArray(raw.content_attachments)
+            ? raw.content_attachments
+            : [],
     };
 }
 // ═══════════════════════════════════════════════════════════════════════════
@@ -349,7 +362,10 @@ function toAgentRuntimeData(raw) {
  * ```
  */
 export function useAgentRuntimes(options = {}) {
-    const { agentSpecId, agentConfig, autoCreateAgent = true, autoStart = false, agentSpec, runtimeCreationTarget = 'backend-services', runtimeCreationBaseUrl, } = options;
+    const { agentSpecId, agentConfig, autoCreateAgent = true, autoStart = false, agentSpec, variant: variantOption, runtimeCreationTarget, runtimeCreationBaseUrl, runtimeConnection, } = options;
+    // Both vocabularies funnel into one value here, so no branch below has to
+    // remember that the old names exist.
+    const variant = toAgentRuntimeVariant(variantOption ?? runtimeCreationTarget);
     const { configuration } = useCoreStore();
     // Base store state
     const runtime = useAgentRuntimeConnection();
@@ -366,29 +382,50 @@ export function useAgentRuntimes(options = {}) {
     const [lifecycleError, setLifecycleError] = useState(null);
     const [isCreating, setIsCreating] = useState(false);
     const hasAutoStarted = useRef(false);
+    /*
+     * Whether the "is one already running?" question has been answered.
+     *
+     * State rather than a ref: the auto-start effect has to re-run when it
+     * flips, and a ref changing does not re-run anything.
+     */
+    const [lookedForExisting, setLookedForExisting] = useState(false);
     const hasCreatedAgentRef = useRef(false);
-    const lastRuntimePodRef = useRef(null);
+    const lastRuntimeRef = useRef(null);
     const creatingRef = useRef(false);
     const agentConfigRef = useRef(agentConfig);
     agentConfigRef.current = agentConfig;
-    // Whether we're managing a full agent lifecycle (agentSpecId provided)
-    const hasSpec = !!agentSpecId;
+    // Specs use the backend lifecycle only when this hook owns a cloud runtime.
+    // A local agent-runtimes server is already running, so it remains connect
+    // mode even when agent creation references a spec — and a browser agent has
+    // no runtime to own at all.
+    const hasSpec = !!agentSpecId && locationOf(variant) === 'cloud';
+    const runtimeConnectionKey = runtimeConnection
+        ? [
+            runtimeConnection.runtimeName,
+            runtimeConnection.environmentName,
+            runtimeConnection.jupyterBaseUrl ||
+                runtimeConnection.serviceManager?.serverSettings.baseUrl ||
+                '',
+            runtimeConnection.kernelId || '',
+        ].join(':')
+        : null;
     const resolvedRuntimeCreationBaseUrl = useMemo(() => {
         if (runtimeCreationBaseUrl) {
             return runtimeCreationBaseUrl;
         }
-        if (runtimeCreationTarget === 'local-agent-runtimes') {
+        // A browser agent reaches no runtime service; the empty string keeps the
+        // return shape without naming a host nothing will call.
+        if (runsInBrowser(variant)) {
+            return '';
+        }
+        if (locationOf(variant) === 'local') {
             return (import.meta.env.VITE_DATALAYER_AGENT_RUNTIMES_URL ||
                 'http://localhost:8765');
         }
         return (configuration?.runtimesUrl ||
             import.meta.env.VITE_DATALAYER_AGENT_RUNTIMES_URL ||
             'https://r1.datalayer.run');
-    }, [
-        configuration?.runtimesUrl,
-        runtimeCreationBaseUrl,
-        runtimeCreationTarget,
-    ]);
+    }, [configuration?.runtimesUrl, runtimeCreationBaseUrl, variant]);
     // ─── Auth helpers ─────────────────────────────────────────────────
     const getAuthHeaders = useCallback(async () => {
         try {
@@ -403,8 +440,34 @@ export function useAgentRuntimes(options = {}) {
             return { token: '', aiAgentsUrl: '', runtimesUrl: '' };
         }
     }, [resolvedRuntimeCreationBaseUrl]);
+    // ─── Connect to a supplied runtime ─────────────────────────────────
+    useEffect(() => {
+        if (!runtimeConnection || !runtimeConnectionKey) {
+            return;
+        }
+        const currentConnectionKey = runtime
+            ? [
+                runtime.runtimeName,
+                runtime.environmentName,
+                runtime.jupyterBaseUrl || '',
+                runtime.kernelId || '',
+            ].join(':')
+            : null;
+        if (currentConnectionKey === runtimeConnectionKey) {
+            return;
+        }
+        hasCreatedAgentRef.current = false;
+        storeConnectAgent(runtimeConnection);
+    }, [runtimeConnection, runtimeConnectionKey, runtime, storeConnectAgent]);
     // ─── Launch Runtime ─────────────────────────────────────────────────
     const launchRuntime = useCallback(async (runtimeOptions) => {
+        if (runsInBrowser(variant)) {
+            // Nothing to launch: the loop runs in this page. Resolving rather than
+            // throwing keeps one launch button correct for every variant — a host
+            // that calls this because a person pressed the button gets a runtime
+            // that is already, truthfully, ready.
+            return BROWSER_AGENT_CONNECTION;
+        }
         if (hasSpec) {
             setLifecycleStatus('launching');
             setLifecycleError(null);
@@ -455,6 +518,7 @@ export function useAgentRuntimes(options = {}) {
         hasSpec,
         resolvedRuntimeCreationBaseUrl,
         storeLaunchAgent,
+        variant,
     ]);
     // ─── Create Agent ───────────────────────────────────────────────────
     const createAgent = useCallback(async (config) => {
@@ -487,7 +551,7 @@ export function useAgentRuntimes(options = {}) {
                 ...config,
                 name: config?.name ||
                     agentConfig?.name ||
-                    (hasSpec && agentSpecId ? agentSpecId : runtime?.podName),
+                    (hasSpec && agentSpecId ? agentSpecId : runtime?.runtimeName),
             };
             return await storeCreateAgent(mergedConfig);
         }
@@ -562,19 +626,32 @@ export function useAgentRuntimes(options = {}) {
     }, [hasSpec, autoCreateAgent, runtime, lifecycleStatus, createAgent]);
     // If runtime pod changes (e.g. after restore), force re-creation on new pod.
     useEffect(() => {
-        const currentPod = runtime?.podName || null;
-        if (!currentPod) {
-            lastRuntimePodRef.current = null;
+        const currentRuntime = runtime?.runtimeName || null;
+        if (!currentRuntime) {
+            lastRuntimeRef.current = null;
             return;
         }
-        if (lastRuntimePodRef.current && lastRuntimePodRef.current !== currentPod) {
+        if (lastRuntimeRef.current && lastRuntimeRef.current !== currentRuntime) {
             hasCreatedAgentRef.current = false;
         }
-        lastRuntimePodRef.current = currentPod;
-    }, [runtime?.podName]);
+        lastRuntimeRef.current = currentRuntime;
+    }, [runtime?.runtimeName]);
     // ─── Bootstrap: connect to existing runtime on initial load ─────────
     useEffect(() => {
-        if (!hasSpec || runtime || autoStart || lifecycleStatus !== 'idle') {
+        /*
+         * Runs whether or not this host asked for an auto-start.
+         *
+         * `autoStart` used to short-circuit it, which made looking and launching
+         * mutually exclusive when they are meant to be sequential: a host that
+         * wanted a runtime always got a *new* one, and an agent for the same spec
+         * already running in the cloud was ignored and paid for twice. Switching
+         * examples showed it as an error — the launch had not landed yet, and
+         * nothing had thought to reuse the runtime that was right there.
+         *
+         * The auto-start below waits for this to finish, so the order is: look,
+         * then launch if there was nothing to find.
+         */
+        if (!hasSpec || runtime || lifecycleStatus !== 'idle') {
             return;
         }
         let cancelled = false;
@@ -603,11 +680,13 @@ export function useAgentRuntimes(options = {}) {
                     const bTs = Number(b.started_at || 0);
                     return bTs - aTs;
                 })[0];
-                if (cancelled || !latestRuntime?.pod_name || !latestRuntime?.ingress) {
+                if (cancelled ||
+                    !latestRuntime?.runtime_name ||
+                    !latestRuntime?.ingress) {
                     return;
                 }
                 storeConnectAgent({
-                    podName: latestRuntime.pod_name,
+                    runtimeName: latestRuntime.runtime_name,
                     environmentName: latestRuntime.environment.name,
                     jupyterBaseUrl: latestRuntime.ingress,
                 });
@@ -637,6 +716,14 @@ export function useAgentRuntimes(options = {}) {
             catch (err) {
                 console.warn('[useAgents] Failed to find existing runtime:', err);
             }
+            finally {
+                // Either way. A lookup that failed must not hold the launch back for
+                // ever — the point of looking is to avoid a second runtime, not to
+                // make the first one conditional on the listing endpoint.
+                if (!cancelled) {
+                    setLookedForExisting(true);
+                }
+            }
         };
         bootstrap();
         return () => {
@@ -661,12 +748,23 @@ export function useAgentRuntimes(options = {}) {
     useEffect(() => {
         if (hasSpec &&
             autoStart &&
+            // Only once the lookup above has reported. Launching in parallel would
+            // race it: two runtimes for one spec, and whichever answered last wins.
+            lookedForExisting &&
+            !runtime &&
             !hasAutoStarted.current &&
             lifecycleStatus === 'idle') {
             hasAutoStarted.current = true;
             launchRuntime();
         }
-    }, [hasSpec, autoStart, lifecycleStatus, launchRuntime]);
+    }, [
+        hasSpec,
+        autoStart,
+        lookedForExisting,
+        runtime,
+        lifecycleStatus,
+        launchRuntime,
+    ]);
     // ─── Sync store errors ─────────────────────────────────────────────
     useEffect(() => {
         if (storeError && hasSpec && lifecycleStatus !== 'error') {
@@ -675,14 +773,26 @@ export function useAgentRuntimes(options = {}) {
         }
     }, [storeError, hasSpec, lifecycleStatus]);
     // ─── Derived state ─────────────────────────────────────────────────
-    const status = hasSpec
-        ? lifecycleStatus
-        : baseStatus;
-    const error = hasSpec ? lifecycleError || storeError : storeError;
-    const isReady = hasSpec
-        ? (lifecycleStatus === 'ready' || lifecycleStatus === 'resumed') &&
-            !!runtime?.isReady
-        : baseStatus === 'ready' && !!runtime?.isReady;
+    // A browser agent is ready the moment the page is: there is no runtime to
+    // start, so a host that waits on `isReady` before showing its chat would
+    // otherwise wait forever for something that is never going to happen.
+    const inBrowser = runsInBrowser(variant);
+    const status = inBrowser
+        ? 'ready'
+        : hasSpec
+            ? lifecycleStatus
+            : baseStatus;
+    const error = inBrowser
+        ? null
+        : hasSpec
+            ? lifecycleError || storeError
+            : storeError;
+    const isReady = inBrowser
+        ? true
+        : hasSpec
+            ? (lifecycleStatus === 'ready' || lifecycleStatus === 'resumed') &&
+                !!runtime?.isReady
+            : baseStatus === 'ready' && !!runtime?.isReady;
     const endpoint = runtime?.endpoint || null;
     const serviceManager = runtime?.serviceManager || null;
     return {
@@ -702,7 +812,11 @@ export function useAgentRuntimes(options = {}) {
         // Status
         isReady,
         error,
-        runtimeCreationTarget,
+        variant,
+        // Derived rather than passed through: a caller that gave neither option
+        // still gets a truthful legacy value, and one that gave a variant gets its
+        // nearest old name instead of `undefined`.
+        runtimeCreationTarget: legacyTargetOf(variant),
         runtimeCreationBaseUrl: resolvedRuntimeCreationBaseUrl,
     };
 }
@@ -744,7 +858,7 @@ export function useAgentRuntimesQuery(scope, queryOptions) {
             }
             const query = params.toString();
             const resp = await requestDatalayer({
-                url: `${configuration.runtimesUrl}/api/runtimes/v1/runtimes${query ? `?${query}` : ''}`,
+                url: `${runtimesUrl(configuration.runtimesUrl)}${query ? `?${query}` : ''}`,
                 method: 'GET',
             });
             if (resp.success && resp.runtimes) {
@@ -755,7 +869,7 @@ export function useAgentRuntimesQuery(scope, queryOptions) {
                     // never reconnect a ServiceManager to a dead ingress (CORS spam).
                     .filter(runtime => !isStaleDeletedRuntime(runtime));
                 agentRuntimes.forEach((runtime) => {
-                    queryClient.setQueryData(agentQueryKeys.agentRuntimes.detail(runtime.pod_name), runtime);
+                    queryClient.setQueryData(agentQueryKeys.agentRuntimes.detail(runtime.runtime_name), runtime);
                 });
                 return agentRuntimes;
             }
@@ -769,16 +883,19 @@ export function useAgentRuntimesQuery(scope, queryOptions) {
     });
 }
 /**
- * Hook to fetch a single agent runtime by pod name.
+ * Hook to fetch a single agent runtime by name.
  */
-export function useAgentRuntimeByPodName(podName) {
+export function useAgentRuntimeByName(runtimeName) {
     const { configuration } = useCoreStore();
     const { requestDatalayer } = useDatalayer({ notifyOnError: false });
+    // The query is disabled without a name, but the URL is built before the
+    // guard runs, so it needs one either way.
+    const name = runtimeName ?? '';
     return useQuery({
-        queryKey: agentQueryKeys.agentRuntimes.detail(podName ?? ''),
+        queryKey: agentQueryKeys.agentRuntimes.detail(name),
         queryFn: async () => {
             const resp = await requestDatalayer({
-                url: `${configuration.runtimesUrl}/api/runtimes/v1/runtimes/${podName}`,
+                url: runtimeUrl(configuration.runtimesUrl, name),
                 method: 'GET',
             });
             if (resp.runtime) {
@@ -799,7 +916,7 @@ export function useAgentRuntimeByPodName(podName) {
             return 5000;
         },
         retry: false,
-        enabled: !!podName,
+        enabled: !!runtimeName,
     });
 }
 /**
@@ -811,13 +928,11 @@ export function useCreateAgentRuntime() {
     const queryClient = useQueryClient();
     return useMutation({
         mutationFn: async (data) => {
-            const normalizedVolumeUids = Array.isArray(data.volumeUids)
-                ? data.volumeUids.map(uid => String(uid || '').trim()).filter(Boolean)
-                : data.volumeUid
-                    ? [String(data.volumeUid).trim()]
-                    : [];
+            const contentAttachmentUids = (data.contentAttachmentUids ?? [])
+                .map(uid => String(uid || '').trim())
+                .filter(Boolean);
             return requestDatalayer({
-                url: `${configuration.runtimesUrl}/api/runtimes/v1/runtimes`,
+                url: runtimesUrl(configuration.runtimesUrl),
                 method: 'POST',
                 body: {
                     environment: {
@@ -836,9 +951,10 @@ export function useCreateAgentRuntime() {
                     billing_entity_handle: data.billingEntityHandle || undefined,
                     billing_source_organization_uid: data.billingSourceOrganizationUid || undefined,
                     billing_source_organization_handle: data.billingSourceOrganizationHandle || undefined,
-                    mount_home_folder: data.mountHomeFolder ?? false,
-                    volume_uids: normalizedVolumeUids.length > 0 ? normalizedVolumeUids : undefined,
-                    volume_uid: normalizedVolumeUids[0] || data.volumeUid || undefined,
+                    runtime_name: data.runtimeName || undefined,
+                    content_attachment_uids: contentAttachmentUids.length
+                        ? contentAttachmentUids
+                        : undefined,
                 },
             });
         },
@@ -846,8 +962,8 @@ export function useCreateAgentRuntime() {
             if (resp.success && resp.runtime) {
                 const mapped = toAgentRuntimeData(resp.runtime);
                 // A fresh runtime legitimately exists — drop any stale tombstone.
-                clearRuntimePodDeleted(mapped.pod_name);
-                queryClient.setQueryData(agentQueryKeys.agentRuntimes.detail(mapped.pod_name), mapped);
+                clearRuntimeDeleted(mapped.runtime_name);
+                queryClient.setQueryData(agentQueryKeys.agentRuntimes.detail(mapped.runtime_name), mapped);
                 queryClient.invalidateQueries({
                     queryKey: agentQueryKeys.agentRuntimes.all(),
                 });
@@ -856,7 +972,11 @@ export function useCreateAgentRuntime() {
     });
 }
 /**
- * Hook to delete an agent runtime.
+ * Hook to stop an agent runtime — running or paused.
+ *
+ * One hook, because there is one endpoint: `DELETE /runtimes/{runtimeName}` reaps
+ * the pod when there is one and the checkpoint records when there is not, so a
+ * caller that wants the runtime gone does not have to know which it is.
  */
 export function useDeleteAgentRuntime() {
     const { configuration } = useCoreStore();
@@ -880,10 +1000,10 @@ export function useDeleteAgentRuntime() {
             '').toLowerCase();
     };
     return useMutation({
-        mutationFn: async (podName) => {
+        mutationFn: async (runtimeName) => {
             try {
                 return await requestDatalayer({
-                    url: `${configuration.runtimesUrl}/api/runtimes/v1/runtimes/${podName}`,
+                    url: runtimeUrl(configuration.runtimesUrl, runtimeName),
                     method: 'DELETE',
                 });
             }
@@ -902,7 +1022,7 @@ export function useDeleteAgentRuntime() {
                 // the runtime detail endpoint still exists.
                 try {
                     await requestDatalayer({
-                        url: `${configuration.runtimesUrl}/api/runtimes/v1/runtimes/${podName}`,
+                        url: runtimeUrl(configuration.runtimesUrl, runtimeName),
                         method: 'GET',
                     });
                     // Runtime still exists: propagate original DELETE failure.
@@ -917,26 +1037,26 @@ export function useDeleteAgentRuntime() {
                 }
             }
         },
-        onSuccess: (_data, podName) => {
+        onSuccess: (_data, runtimeName) => {
             // Tombstone the pod so refetches that still echo it from the control
             // plane (deletion lag) do not re-add it to the caches below.
-            markRuntimePodDeleted(podName);
+            markRuntimeDeleted(runtimeName);
             // Prune the pod from the runtimes store immediately so the remote service
             // managers dispose right away and stop polling the now-dead pod ingress
             // (otherwise `/api/kernels` requests keep firing until the next
-            // `refreshRuntimePods()` poll tick, producing CORS errors).
-            runtimesStore.getState().removeRuntimePod(podName);
+            // `refreshRuntimes()` poll tick, producing CORS errors).
+            runtimesStore.getState().removeRuntime(runtimeName);
             queryClient.setQueriesData({ queryKey: agentQueryKeys.agentRuntimes.lists() }, (current) => {
                 if (!Array.isArray(current)) {
                     return current;
                 }
-                return current.filter(runtime => runtime.pod_name !== podName);
+                return current.filter(runtime => runtime.runtime_name !== runtimeName);
             });
             queryClient.cancelQueries({
-                queryKey: agentQueryKeys.agentRuntimes.detail(podName),
+                queryKey: agentQueryKeys.agentRuntimes.detail(runtimeName),
             });
             queryClient.removeQueries({
-                queryKey: agentQueryKeys.agentRuntimes.detail(podName),
+                queryKey: agentQueryKeys.agentRuntimes.detail(runtimeName),
             });
             queryClient.invalidateQueries({
                 queryKey: agentQueryKeys.agentRuntimes.lists(),
@@ -945,6 +1065,11 @@ export function useDeleteAgentRuntime() {
                 queryKey: agentQueryKeys.agentRuntimes.lists(),
                 type: 'active',
             });
+            // Stopping also removes any checkpoint records, so a paused agent does
+            // not linger in the checkpoint views after it is gone.
+            queryClient.invalidateQueries({
+                queryKey: agentQueryKeys.checkpoints.all(),
+            });
         },
     });
 }
@@ -1033,15 +1158,15 @@ export function useAgentsRuntimes(scope, queryOptions) {
     const createRuntimeMutation = useCreateAgentRuntime();
     const deleteRuntimeMutation = useDeleteAgentRuntime();
     const refreshRuntimes = useRefreshAgentRuntimes();
-    const terminateRuntimeByPod = useCallback(async (podName, options) => {
-        const normalizedPodName = String(podName || '').trim();
-        if (!normalizedPodName) {
+    const stopRuntimeByName = useCallback(async (runtimeName, options) => {
+        const normalizedRuntimeName = String(runtimeName || '').trim();
+        if (!normalizedRuntimeName) {
             return;
         }
-        if (options?.beforeTerminate) {
-            await options.beforeTerminate();
+        if (options?.beforeStop) {
+            await options.beforeStop();
         }
-        return deleteRuntimeMutation.mutateAsync(normalizedPodName);
+        return deleteRuntimeMutation.mutateAsync(normalizedRuntimeName);
     }, [deleteRuntimeMutation]);
     return useMemo(() => ({
         runtimes: runtimesQuery.data ?? EMPTY_RUNTIMES,
@@ -1050,8 +1175,7 @@ export function useAgentsRuntimes(scope, queryOptions) {
         runtimesError: runtimesQuery.error,
         refetchRuntimes: () => runtimesQuery.refetch(),
         refreshRuntimes,
-        terminateRuntimeByPod,
-        deleteRuntimeByPod: async (podName) => terminateRuntimeByPod(podName),
+        stopRuntimeByName,
         createRuntime: async (data) => createRuntimeMutation.mutateAsync(data),
     }), [
         runtimesQuery.data,
@@ -1060,7 +1184,7 @@ export function useAgentsRuntimes(scope, queryOptions) {
         runtimesQuery.error,
         runtimesQuery.refetch,
         refreshRuntimes,
-        terminateRuntimeByPod,
+        stopRuntimeByName,
         createRuntimeMutation,
         deleteRuntimeMutation,
     ]);

package/lib/hooks/useAgentsCatalog.js

@@ -11,18 +11,46 @@
  */
 import { create } from 'zustand';
 import { listAgentspecs } from '../specs';
+/** Whether two agent lists name the same agents, in the same state. */
+const sameAgents = (before, after) => before.length === after.length &&
+    before.every((agent, index) => {
+        const other = after[index];
+        return (agent === other ||
+            (agent.id === other.id &&
+                agent.runtime_name === other.runtime_name &&
+                agent.status === other.status &&
+                agent.agentSpec === other.agentSpec));
+    });
 export const useAgentCatalogStore = create()(set => ({
     agentspecs: listAgentspecs(),
     runningAgents: [],
     refreshSpecs: () => set({ agentspecs: listAgentspecs() }),
-    setRunningAgents: agents => set(state => ({
-        runningAgents: agents.map(agent => {
+    /*
+     * The same agents twice is not a change.
+     *
+     * This is a global store, and the caller is a layout that recomputes its
+     * list whenever the runtimes poll — so `agents` is a fresh array many times
+     * a minute even when nothing about the agents differs. Storing it
+     * unconditionally gave every consumer a new identity each time, which is a
+     * re-render each time for a list that has not moved; and a consumer whose
+     * own effect writes back closes the circle into a render loop.
+     *
+     * So the previous array is kept when the same agents are still there, in
+     * the same order, with the same status. Comparing by that triple rather
+     * than deeply because it is what a reader of this list acts on, and what
+     * the poll actually changes.
+     */
+    setRunningAgents: agents => set(state => {
+        const resolved = agents.map(agent => {
             if (agent.agentSpec)
                 return agent;
             if (!agent.agent_spec_id)
                 return agent;
             const spec = state.agentspecs.find(s => s.id === agent.agent_spec_id);
             return spec ? { ...agent, agentSpec: spec } : agent;
-        }),
-    })),
+        });
+        return sameAgents(state.runningAgents, resolved)
+            ? {}
+            : { runningAgents: resolved };
+    }),
 }));