@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/hooks/useBrowserAgent.d.ts

@@ -0,0 +1,26 @@
+import { type UseChatHelpers, type UIMessage } from '@ai-sdk/react';
+import { type CreateBrowserAgentOptions } from '../runtimes/browser';
+export type UseBrowserAgentOptions = CreateBrowserAgentOptions & {
+    /**
+     * Chat id, so two agents on one page keep separate histories.
+     *
+     * Defaults to the spec id, which is right whenever a page runs one agent.
+     */
+    chatId?: string;
+};
+/**
+ * A chat backed by an agent loop running in this page.
+ *
+ * ```tsx
+ * const frontendTools = useNotebookTools(notebookId);
+ * const { messages, sendMessage, status } = useBrowserAgent({
+ *   spec: JUPYTER_NOTEBOOK_COMPACTOR_AGENTSPEC_0_0_1,
+ *   frontendTools,
+ *   inference: { inferenceUrl, token },
+ * });
+ * ```
+ *
+ * The tools are the same array the AG-UI path takes, and they behave the same
+ * way — see {@link frontendToolsToVercelAI}.
+ */
+export declare function useBrowserAgent(options: UseBrowserAgentOptions): UseChatHelpers<UIMessage>;

package/lib/hooks/useBrowserAgent.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * Run an agent in the browser.
+ *
+ * The counterpart to {@link useVercelAI}, and the difference between them is
+ * the whole of the harness split. `useVercelAI` speaks the AI SDK *protocol*
+ * to a runtime that turns the loop somewhere else; this turns the loop here,
+ * with the AI SDK itself, and reaches a server only to ask a model a question.
+ *
+ * Both return the same `useChat` helpers, so every chat component, message
+ * renderer and tool part downstream is shared. The branch is one transport:
+ *
+ * ```
+ *   useVercelAI       →  DefaultChatTransport  →  POST /api/v1/vercel-ai/chat
+ *   useBrowserAgent   →  DirectChatTransport   →  the loop, in this page
+ * ```
+ *
+ * @module hooks/useBrowserAgent
+ */
+import { useMemo } from 'react';
+import { useChat } from '@ai-sdk/react';
+import { DirectChatTransport } from 'ai';
+import { createBrowserAgent, } from '../runtimes/browser';
+/**
+ * A chat backed by an agent loop running in this page.
+ *
+ * ```tsx
+ * const frontendTools = useNotebookTools(notebookId);
+ * const { messages, sendMessage, status } = useBrowserAgent({
+ *   spec: JUPYTER_NOTEBOOK_COMPACTOR_AGENTSPEC_0_0_1,
+ *   frontendTools,
+ *   inference: { inferenceUrl, token },
+ * });
+ * ```
+ *
+ * The tools are the same array the AG-UI path takes, and they behave the same
+ * way — see {@link frontendToolsToVercelAI}.
+ */
+export function useBrowserAgent(options) {
+    const { chatId, spec, frontendTools, inference, model, maxSteps, onHitlRequired, onStatusChange, } = options;
+    // Rebuilt only when something the loop is made of changes. A new agent
+    // identity would reset the transport mid-conversation, so the dependencies
+    // are the primitives rather than the option object a caller re-creates on
+    // every render.
+    const agent = useMemo(() => createBrowserAgent({
+        spec,
+        frontendTools,
+        inference,
+        model,
+        maxSteps,
+        onHitlRequired,
+        onStatusChange,
+    }), [
+        spec,
+        frontendTools,
+        inference,
+        model,
+        maxSteps,
+        onHitlRequired,
+        onStatusChange,
+    ]);
+    const transport = useMemo(() => new DirectChatTransport({ agent }), [agent]);
+    return useChat({
+        id: chatId ?? `browser-agent-${spec.id}`,
+        transport,
+    });
+}

package/lib/hooks/useBrowserInference.d.ts

@@ -0,0 +1,27 @@
+import { type AnonymousSession, type BrowserModelOptions } from '../runtimes/browser';
+export type BrowserInference = {
+    /** Where to reach the inference service, and with whose token. */
+    inference: Omit<BrowserModelOptions, 'model'>;
+    /** Whether the agent would be refused for want of a sign-in. */
+    needsSignIn: boolean;
+    /**
+     * The visitor's trial key, when they are on one.
+     *
+     * `status: 'idle'` for a signed-in member, which is the answer a caller
+     * wants for "is this person on a clock?" — nobody is. Passed on so the
+     * workspace can draw the time left and say what happens when it runs out.
+     */
+    anonymous: AnonymousSession;
+    /** Where the inference service is, for whoever needs to name it. */
+    inferenceUrl: string;
+};
+/**
+ * The inference endpoint for an in-page agent.
+ *
+ * @param enabled Whether an in-page agent is actually going to ask for
+ *   inference. False for a workspace on a server-backed agent, which
+ *   authenticates itself: minting a visitor's one trial key for an agent that
+ *   will never spend it starts a clock nobody is watching.
+ */
+export declare function useBrowserInference(enabled?: boolean): BrowserInference;
+export default useBrowserInference;

package/lib/hooks/useBrowserInference.js

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * Where an in-page agent asks its model, and as whom.
+ *
+ * A browser agent needs no runtime, but it does need an account: a page cannot
+ * hold an AWS credential, so the model is reached through the Datalayer
+ * inference service, which holds them, routes to Bedrock, and admits signed-in
+ * members only.
+ *
+ * Its own hook because two callers need the identical answer — the examples
+ * shell and the LOOP workspace — and neither should be reading stores to work
+ * out a host.
+ *
+ * @module hooks/useBrowserInference
+ */
+import { useMemo } from 'react';
+import { useCoreStore, useIAMStore } from '../state';
+import { browserModelRequiresSignIn, useAnonymousInferenceSession, } from '../runtimes/browser';
+/** The inference plane used when the host provides no configuration. */
+const DEFAULT_INFERENCE_URL = 'https://r1.datalayer.run';
+/**
+ * The inference endpoint for an in-page agent.
+ *
+ * @param enabled Whether an in-page agent is actually going to ask for
+ *   inference. False for a workspace on a server-backed agent, which
+ *   authenticates itself: minting a visitor's one trial key for an agent that
+ *   will never spend it starts a clock nobody is watching.
+ */
+export function useBrowserInference(enabled = true) {
+    const { configuration } = useCoreStore();
+    const memberToken = useIAMStore(state => state.token);
+    const inferenceUrl = configuration?.aiInferenceUrl || DEFAULT_INFERENCE_URL;
+    /*
+     * A visitor with no account still gets to try the thing.
+     *
+     * The service admits members only, so an anonymous page was refused with a
+     * flat 401 and the agent looked broken rather than gated. It mints the
+     * short-lived token the service offers for exactly this — worth a minute of
+     * inference and nothing else. One of them, not a rolling supply: the trial
+     * ends, and the workspace says so rather than quietly renewing it. A
+     * member's own token is strictly better, so this only runs when there is
+     * not one.
+     */
+    const anonymous = useAnonymousInferenceSession(inferenceUrl, enabled && !memberToken);
+    const token = memberToken || anonymous.token;
+    const inference = useMemo(() => ({
+        inferenceUrl,
+        // The signed-in person's token, forwarded so the completion is made as
+        // them and metered to them — or the anonymous one, which names nobody.
+        token: token || undefined,
+    }), [inferenceUrl, token]);
+    return {
+        inference,
+        needsSignIn: browserModelRequiresSignIn(inference),
+        anonymous,
+        inferenceUrl,
+    };
+}
+export default useBrowserInference;

package/lib/hooks/useCheckpoints.d.ts

@@ -19,20 +19,20 @@ export type CheckpointData = {
     end_date?: string;
 };
 export type PauseAgentParams = {
-    podName: string;
+    runtimeName: string;
     mode?: CheckpointMode;
     agentSpecId?: string;
     agentSpec?: Record<string, any>;
     messages?: string[];
 };
 export type ResumeAgentParams = {
-    podName: string;
+    runtimeName: string;
     agentSpecId?: string;
     mode?: CheckpointMode;
     checkpointId?: string;
 };
 export type CheckpointAgentParams = {
-    podName: string;
+    runtimeName: string;
     name?: string;
     mode?: CheckpointMode;
     agentSpecId?: string;
@@ -40,7 +40,7 @@ export type CheckpointAgentParams = {
     messages?: string[];
 };
 export type TerminateAgentParams = {
-    podName: string;
+    runtimeName: string;
 };
 /**
  * Fetch all runtime checkpoints for the current user.
@@ -48,20 +48,11 @@ export type TerminateAgentParams = {
  * Calls ``GET /api/runtimes/v1/runtime-checkpoints`` and returns
  * the list of checkpoint records in visible states.
  */
-export declare function useCheckpointsQuery(): import("@tanstack/react-query").UseQueryResult<NoInfer<CheckpointData[]>, Error>;
+export declare function useCheckpointsQuery(): import("@tanstack/react-query").UseQueryResult<CheckpointData[], Error>;
 /**
  * Hook to refresh the checkpoints list.
  */
 export declare function useRefreshCheckpoints(): () => void;
-/**
- * Hook to delete a paused agent runtime.
- *
- * Paused agents have no K8s pod — their state lives entirely in Solr
- * checkpoint records. This calls the dedicated
- * ``DELETE /runtimes/{podName}/paused`` endpoint which removes those
- * Solr records.
- */
-export declare function useDeletePausedAgentRuntime(): import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
 /**
  * Hook to resume a paused agent runtime via checkpoint restore.
  */
@@ -109,7 +100,7 @@ export interface AgentLifecycleOptions {
     runtime: AgentConnection | null;
     /** Callback to connect to a new runtime pod */
     connectToRuntime: (opts: {
-        podName: string;
+        runtimeName: string;
         environmentName: string;
         jupyterBaseUrl?: string;
     }) => void;
@@ -130,7 +121,7 @@ export interface AgentLifecycleReturn {
     /** Pause the agent (checkpoint-mode aware) */
     pause: (mode?: CheckpointMode, messages?: string[]) => Promise<void>;
     /** Resume a paused agent (checkpoint restore) */
-    resume: (mode?: CheckpointMode, checkpointId?: string, podName?: string) => Promise<void>;
+    resume: (mode?: CheckpointMode, checkpointId?: string, runtimeName?: string) => Promise<void>;
     /** Terminate the agent (delete runtime) */
     terminate: () => Promise<void>;
     /** Create a named checkpoint (pause → wait → stay paused) */
@@ -163,7 +154,7 @@ export declare function useAgentLifecycle(options: AgentLifecycleOptions): Agent
  * for pause, resume, and checkpoint lifecycle.
  */
 export declare function useCheckpoints(): {
-    checkpointsQuery: import("@tanstack/react-query").UseQueryResult<NoInfer<CheckpointData[]>, Error>;
+    checkpointsQuery: import("@tanstack/react-query").UseQueryResult<CheckpointData[], Error>;
     refresh: () => void;
     pauseAgent: import("@tanstack/react-query").UseMutationResult<import("../api/runtimes/runtimes").PauseResumeResponse, Error, PauseAgentParams, unknown>;
     resumeAgent: import("@tanstack/react-query").UseMutationResult<import("../api/runtimes/runtimes").PauseResumeResponse, Error, ResumeAgentParams, unknown>;

package/lib/hooks/useCheckpoints.js

@@ -14,8 +14,9 @@ import { useMemo, useState, useCallback } from 'react';
 import { useQuery, useQueryClient, useMutation } from '@tanstack/react-query';
 import { useIAMStore } from '@datalayer/core/lib/state';
 import { useCoreStore, useDatalayer } from '@datalayer/core';
-import { agentQueryKeys, AGENT_QUERY_OPTIONS, clearRuntimePodDeleted, } from './useAgentRuntimes';
+import { agentQueryKeys, AGENT_QUERY_OPTIONS, clearRuntimeDeleted, } from './useAgentRuntimes';
 import { disposeSandboxServiceManagers } from '../services/sandboxServiceManagers';
+import { runtimeCheckpointsUrl, runtimeResumeUrl } from '../runtimes/lifecycle';
 // ═══════════════════════════════════════════════════════════════════════════
 // Query hooks
 // ═══════════════════════════════════════════════════════════════════════════
@@ -33,7 +34,7 @@ export function useCheckpointsQuery() {
         queryKey: agentQueryKeys.checkpoints.lists(),
         queryFn: async () => {
             const resp = await requestDatalayer({
-                url: `${configuration.runtimesUrl}/api/runtimes/v1/runtime-checkpoints`,
+                url: runtimeCheckpointsUrl(configuration.runtimesUrl),
                 method: 'GET',
             });
             if (resp.success && resp.checkpoints) {
@@ -57,41 +58,6 @@ export function useRefreshCheckpoints() {
         });
     };
 }
-/**
- * Hook to delete a paused agent runtime.
- *
- * Paused agents have no K8s pod — their state lives entirely in Solr
- * checkpoint records. This calls the dedicated
- * ``DELETE /runtimes/{podName}/paused`` endpoint which removes those
- * Solr records.
- */
-export function useDeletePausedAgentRuntime() {
-    const { configuration } = useCoreStore();
-    const { requestDatalayer } = useDatalayer({ notifyOnError: false });
-    const queryClient = useQueryClient();
-    return useMutation({
-        mutationFn: async (podName) => {
-            return requestDatalayer({
-                url: `${configuration.runtimesUrl}/api/runtimes/v1/runtimes/${podName}/paused`,
-                method: 'DELETE',
-            });
-        },
-        onSuccess: (_data, podName) => {
-            queryClient.cancelQueries({
-                queryKey: agentQueryKeys.agentRuntimes.detail(podName),
-            });
-            queryClient.removeQueries({
-                queryKey: agentQueryKeys.agentRuntimes.detail(podName),
-            });
-            queryClient.invalidateQueries({
-                queryKey: agentQueryKeys.agentRuntimes.lists(),
-            });
-            queryClient.invalidateQueries({
-                queryKey: agentQueryKeys.checkpoints.all(),
-            });
-        },
-    });
-}
 /**
  * Hook to resume a paused agent runtime via checkpoint restore.
  */
@@ -100,16 +66,16 @@ export function useResumePausedAgentRuntime() {
     const { requestDatalayer } = useDatalayer({ notifyOnError: false });
     const queryClient = useQueryClient();
     return useMutation({
-        mutationFn: async (podName) => {
+        mutationFn: async (runtimeName) => {
             return requestDatalayer({
-                url: `${configuration.runtimesUrl}/api/runtimes/v1/runtimes/${podName}/resume`,
+                url: runtimeResumeUrl(configuration.runtimesUrl, runtimeName),
                 method: 'POST',
             });
         },
-        onSuccess: (_data, podName) => {
+        onSuccess: (_data, runtimeName) => {
             // The pod can come back under the same name — drop any delete tombstone
             // so the runtimes queries do not filter the resumed runtime out.
-            clearRuntimePodDeleted(podName);
+            clearRuntimeDeleted(runtimeName);
             queryClient.invalidateQueries({
                 queryKey: agentQueryKeys.agentRuntimes.all(),
             });
@@ -138,7 +104,7 @@ export function usePauseAgent() {
             const runtimesUrl = coreStore.getState().configuration?.runtimesUrl || '';
             const { pauseRuntime } = await import('../api/runtimes/runtimes');
             const mode = params.mode || 'light';
-            const resp = await pauseRuntime(token, params.podName, runtimesUrl, {
+            const resp = await pauseRuntime(token, params.runtimeName, runtimesUrl, {
                 agent_spec_id: params.agentSpecId,
                 checkpoint_mode: mode,
                 ...(params.messages && mode === 'light'
@@ -148,7 +114,7 @@ export function usePauseAgent() {
             });
             if (resp.checkpoint_id) {
                 const { waitForCheckpointStatus } = await import('../api/runtimes/checkpoints');
-                const ckpt = await waitForCheckpointStatus(token, params.podName, resp.checkpoint_id, ['paused', 'failed'], runtimesUrl);
+                const ckpt = await waitForCheckpointStatus(token, params.runtimeName, resp.checkpoint_id, ['paused', 'failed'], runtimesUrl);
                 if (ckpt.status === 'failed') {
                     throw new Error(`Checkpoint ${resp.checkpoint_id} failed during ${mode.toUpperCase()} pause`);
                 }
@@ -158,7 +124,7 @@ export function usePauseAgent() {
         onSuccess: (_data, params) => {
             // Pausing tears the pod down: dispose every ServiceManager any surface
             // opened against the sandbox so their pollers stop immediately.
-            disposeSandboxServiceManagers(params.podName);
+            disposeSandboxServiceManagers(params.runtimeName);
             queryClient.invalidateQueries({
                 queryKey: agentQueryKeys.agentRuntimes.all(),
             });
@@ -182,7 +148,7 @@ export function useResumeAgent() {
             const token = iamStore.getState().token || '';
             const runtimesUrl = coreStore.getState().configuration?.runtimesUrl || '';
             const { resumeRuntime } = await import('../api/runtimes/runtimes');
-            return resumeRuntime(token, params.podName, runtimesUrl, {
+            return resumeRuntime(token, params.runtimeName, runtimesUrl, {
                 agent_spec_id: params.agentSpecId,
                 ...(params.mode ? { checkpoint_mode: params.mode } : {}),
                 ...(params.checkpointId ? { checkpoint_id: params.checkpointId } : {}),
@@ -191,7 +157,7 @@ export function useResumeAgent() {
         onSuccess: (_data, params) => {
             // The pod can come back under the same name — drop any delete tombstone
             // so the runtimes queries do not filter the resumed runtime out.
-            clearRuntimePodDeleted(params.podName);
+            clearRuntimeDeleted(params.runtimeName);
             queryClient.invalidateQueries({
                 queryKey: agentQueryKeys.agentRuntimes.all(),
             });
@@ -217,7 +183,7 @@ export function useCheckpointAgent() {
             const { pauseRuntime } = await import('../api/runtimes/runtimes');
             const { waitForCheckpointStatus } = await import('../api/runtimes/checkpoints');
             const mode = params.mode || 'criu';
-            const pauseResp = await pauseRuntime(token, params.podName, runtimesUrl, {
+            const pauseResp = await pauseRuntime(token, params.runtimeName, runtimesUrl, {
                 name: params.name || `checkpoint-${Date.now()}`,
                 description: `${mode.toUpperCase()} checkpoint for ${params.agentSpecId}`,
                 checkpoint_mode: mode,
@@ -231,7 +197,7 @@ export function useCheckpointAgent() {
             if (!checkpointId) {
                 throw new Error('Pause did not return a checkpoint_id');
             }
-            const ckpt = await waitForCheckpointStatus(token, params.podName, checkpointId, ['paused', 'failed'], runtimesUrl);
+            const ckpt = await waitForCheckpointStatus(token, params.runtimeName, checkpointId, ['paused', 'failed'], runtimesUrl);
             if (ckpt.status === 'failed') {
                 throw new Error(`Checkpoint ${checkpointId} failed during ${mode.toUpperCase()} pause`);
             }
@@ -261,7 +227,7 @@ export function useTerminateAgent() {
             const token = iamStore.getState().token || '';
             const runtimesUrl = coreStore.getState().configuration?.runtimesUrl || '';
             const { deleteRuntime } = await import('../api/runtimes/runtimes');
-            return deleteRuntime(token, params.podName, runtimesUrl);
+            return deleteRuntime(token, params.runtimeName, runtimesUrl);
         },
         onSuccess: () => {
             queryClient.invalidateQueries({
@@ -304,7 +270,7 @@ export function useAgentLifecycle(options) {
         }
         try {
             await pauseAgentMutation.mutateAsync({
-                podName: runtime.podName,
+                runtimeName: runtime.runtimeName,
                 mode,
                 agentSpecId,
                 agentSpec,
@@ -318,19 +284,19 @@ export function useAgentLifecycle(options) {
         }
     }, [runtime, lifecycleStatus, agentSpecId, agentSpec, pauseAgentMutation]);
     // ─── Resume ─────────────────────────────────────────────────────────
-    const resume = useCallback(async (mode = 'criu', checkpointId, podName) => {
+    const resume = useCallback(async (mode = 'criu', checkpointId, runtimeName) => {
         setLifecycleStatus('resuming');
         setLifecycleError(null);
         try {
             const checkpoints = checkpointsQuery.data || [];
-            const targetPodName = podName ||
-                runtime?.podName ||
+            const targetRuntimeName = runtimeName ||
+                runtime?.runtimeName ||
                 (checkpointId
                     ? checkpoints.find((c) => c.id === checkpointId)?.runtime_uid
                     : undefined);
-            if (targetPodName) {
+            if (targetRuntimeName) {
                 await resumeAgentMutation.mutateAsync({
-                    podName: targetPodName,
+                    runtimeName: targetRuntimeName,
                     agentSpecId,
                     mode,
                     checkpointId,
@@ -360,9 +326,9 @@ export function useAgentLifecycle(options) {
                         const bTs = Number(b.started_at || 0);
                         return bTs - aTs;
                     })[0];
-                    if (latestRuntime?.pod_name && latestRuntime?.ingress) {
+                    if (latestRuntime?.runtime_name && latestRuntime?.ingress) {
                         connectToRuntime({
-                            podName: latestRuntime.pod_name,
+                            runtimeName: latestRuntime.runtime_name,
                             environmentName: latestRuntime.environment.name,
                             jupyterBaseUrl: latestRuntime.ingress,
                         });
@@ -400,7 +366,7 @@ export function useAgentLifecycle(options) {
         }
         try {
             await checkpointAgentMutation.mutateAsync({
-                podName: runtime.podName,
+                runtimeName: runtime.runtimeName,
                 name,
                 mode,
                 agentSpecId,
@@ -423,7 +389,7 @@ export function useAgentLifecycle(options) {
         }
         try {
             await terminateAgentMutation.mutateAsync({
-                podName: runtime.podName,
+                runtimeName: runtime.runtimeName,
             });
             disconnect();
             setLifecycleStatus('idle');

package/lib/hooks/useConfig.d.ts

@@ -3,7 +3,7 @@ import type { RemoteConfig } from '../types/config';
  * Hook to safely use query when QueryClient is available.
  * Returns a mock result if no QueryClientProvider is present.
  */
-export declare function useConfig(enabled: boolean, configEndpoint?: string, authToken?: string, agentId?: string): import("@tanstack/query-core").QueryObserverRefetchErrorResult<NoInfer<RemoteConfig>, Error> | import("@tanstack/query-core").QueryObserverSuccessResult<NoInfer<RemoteConfig>, Error> | import("@tanstack/query-core").QueryObserverLoadingErrorResult<NoInfer<RemoteConfig>, Error> | import("@tanstack/query-core").QueryObserverPendingResult<NoInfer<RemoteConfig>, Error> | import("@tanstack/query-core").QueryObserverPlaceholderResult<NoInfer<RemoteConfig>, Error> | {
+export declare function useConfig(enabled: boolean, configEndpoint?: string, authToken?: string, agentId?: string): import("@tanstack/query-core").QueryObserverRefetchErrorResult<RemoteConfig, Error> | import("@tanstack/query-core").QueryObserverSuccessResult<RemoteConfig, Error> | import("@tanstack/query-core").QueryObserverLoadingErrorResult<RemoteConfig, Error> | import("@tanstack/query-core").QueryObserverPendingResult<RemoteConfig, Error> | import("@tanstack/query-core").QueryObserverPlaceholderResult<RemoteConfig, Error> | {
     data: undefined;
     isLoading: boolean;
     isError: boolean;

package/lib/hooks/useConfig.js

@@ -46,7 +46,11 @@ export function useConfig(enabled, configEndpoint, authToken, agentId) {
             // Otherwise use Jupyter requestAPI.
             return requestAPI('configure');
         },
-        queryKey: ['models', configEndpoint || 'jupyter', agentId || 'global'],
+        queryKey: [
+            'models',
+            configEndpoint || 'jupyter-server',
+            agentId || 'global',
+        ],
         enabled,
         retry: 1,
     });

package/lib/hooks/useContextSnapshot.d.ts

@@ -1,16 +1,27 @@
-import type { ContextSnapshotData } from '../types/context';
 /**
- * Hook that previously polled agent context-snapshot from the backend.
+ * What the agent's context window is holding.
+ *
+ * The REST endpoint this used to poll was removed, and the snapshot moved to
+ * the WebSocket stream — but the hook was left returning `undefined` with a
+ * note that a replacement would be wired in later. It never was, so the
+ * token-usage bar and its context ring stayed hidden for *every* agent, on
+ * every target, however the host configured them. The data had been arriving
+ * the whole time; nothing was reading it.
+ *
+ * It arrives on `agent.snapshot` and the runtime store already keeps it. This
+ * reads that.
  *
- * The REST endpoint has been removed — context snapshot data is now
- * delivered via the WebSocket stream (`agent.snapshot` messages).
- * This hook is kept as a no-op so existing call-sites compile without
- * changes; the token-usage bar simply stays hidden until a WS-based
- * replacement is wired in.
+ * The arguments are the ones the REST version took. They are unused and kept
+ * so the call sites that pass an endpoint and a token still compile — what
+ * they described (where to ask, and as whom) is settled by the socket now.
+ *
+ * @module hooks/useContextSnapshot
  */
+import type { ContextSnapshotData } from '../types/context';
 export declare function useContextSnapshot(_enabled: boolean, _configEndpoint?: string, _agentId?: string, _authToken?: string): {
     data: ContextSnapshotData | undefined;
     isLoading: boolean;
     isError: boolean;
     error: null;
 };
+export default useContextSnapshot;

package/lib/hooks/useContextSnapshot.js

@@ -2,15 +2,19 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/**
- * Hook that previously polled agent context-snapshot from the backend.
- *
- * The REST endpoint has been removed — context snapshot data is now
- * delivered via the WebSocket stream (`agent.snapshot` messages).
- * This hook is kept as a no-op so existing call-sites compile without
- * changes; the token-usage bar simply stays hidden until a WS-based
- * replacement is wired in.
- */
+import { useAgentRuntimeContextSnapshot } from '../stores';
 export function useContextSnapshot(_enabled, _configEndpoint, _agentId, _authToken) {
-    return { data: undefined, isLoading: false, isError: false, error: null };
+    const snapshot = useAgentRuntimeContextSnapshot();
+    /*
+     * Never "loading". There is no request to be in flight — the socket either
+     * has reported a snapshot or has not — and a caller that showed a spinner
+     * for this would show it for as long as the agent stayed quiet.
+     */
+    return {
+        data: snapshot ?? undefined,
+        isLoading: false,
+        isError: false,
+        error: null,
+    };
 }
+export default useContextSnapshot;

package/lib/hooks/useNotifications.d.ts

@@ -1,16 +1,16 @@
 import type { NotificationFilters, ListAgentEventsParams, CreateAgentEventRequest, UpdateAgentEventRequest } from '../types';
-export declare function useFilteredNotifications(filters?: NotificationFilters): import("@tanstack/react-query").UseQueryResult<NoInfer<import("../types").AgentNotification[]>, Error>;
-export declare function useUnreadNotificationCount(): import("@tanstack/react-query").UseQueryResult<NoInfer<{
+export declare function useFilteredNotifications(filters?: NotificationFilters): import("@tanstack/react-query").UseQueryResult<import("../types").AgentNotification[], Error>;
+export declare function useUnreadNotificationCount(): import("@tanstack/react-query").UseQueryResult<{
     count: number;
-}>, Error>;
+}, Error>;
 export declare function useMarkNotificationRead(): import("@tanstack/react-query").UseMutationResult<void, Error, string, unknown>;
 export declare function useMarkAllNotificationsRead(): import("@tanstack/react-query").UseMutationResult<void, Error, void, unknown>;
 /**
  * List events across all agents for the authenticated user.
  */
-export declare function useAllAgentEvents(params?: Omit<ListAgentEventsParams, 'agent_id'>, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<NoInfer<import("../types").ListAgentEventsResponse>, Error>;
-export declare function useAgentEvents(agentId: string, params?: Omit<ListAgentEventsParams, 'agent_id'>, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<NoInfer<import("../types").ListAgentEventsResponse>, Error>;
-export declare function useAgentEvent(agentId: string, eventId?: string): import("@tanstack/react-query").UseQueryResult<NoInfer<import("../types").GetAgentEventResponse>, Error>;
+export declare function useAllAgentEvents(params?: Omit<ListAgentEventsParams, 'agent_id'>, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<import("../types").ListAgentEventsResponse, Error>;
+export declare function useAgentEvents(agentId: string, params?: Omit<ListAgentEventsParams, 'agent_id'>, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<import("../types").ListAgentEventsResponse, Error>;
+export declare function useAgentEvent(agentId: string, eventId?: string): import("@tanstack/react-query").UseQueryResult<import("../types").GetAgentEventResponse, Error>;
 export declare function useCreateAgentEvent(): import("@tanstack/react-query").UseMutationResult<{
     success: boolean;
     event: import("../types").AgentEvent;
@@ -34,14 +34,14 @@ export declare function useMarkEventUnread(agentId: string): import("@tanstack/r
     eventAgentId?: string;
 }, unknown>;
 export declare function useNotifications(agentId: string, filters?: NotificationFilters, eventParams?: Omit<ListAgentEventsParams, 'agent_id'>, eventId?: string): {
-    notificationsQuery: import("@tanstack/react-query").UseQueryResult<NoInfer<import("../types").AgentNotification[]>, Error>;
-    unreadCountQuery: import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    notificationsQuery: import("@tanstack/react-query").UseQueryResult<import("../types").AgentNotification[], Error>;
+    unreadCountQuery: import("@tanstack/react-query").UseQueryResult<{
         count: number;
-    }>, Error>;
+    }, Error>;
     markRead: import("@tanstack/react-query").UseMutationResult<void, Error, string, unknown>;
     markAllRead: import("@tanstack/react-query").UseMutationResult<void, Error, void, unknown>;
-    eventsQuery: import("@tanstack/react-query").UseQueryResult<NoInfer<import("../types").ListAgentEventsResponse>, Error>;
-    eventQuery: import("@tanstack/react-query").UseQueryResult<NoInfer<import("../types").GetAgentEventResponse>, Error>;
+    eventsQuery: import("@tanstack/react-query").UseQueryResult<import("../types").ListAgentEventsResponse, Error>;
+    eventQuery: import("@tanstack/react-query").UseQueryResult<import("../types").GetAgentEventResponse, Error>;
     createEvent: import("@tanstack/react-query").UseMutationResult<{
         success: boolean;
         event: import("../types").AgentEvent;

package/lib/hooks/useNotifications.js

@@ -58,7 +58,7 @@ export function useMarkAllNotificationsRead() {
     const baseUrl = useBaseUrl();
     const queryClient = useQueryClient();
     return useMutation({
-        mutationFn: () => notifications.markAllRead(token, baseUrl),
+        mutationFn: () => notifications.markAllRead(token, undefined, baseUrl),
         onSuccess: () => {
             queryClient.invalidateQueries({ queryKey: ['agent-notifications'] });
         },