@datalayer/agent-runtimes 1.0.9 → 1.0.17

package/lib/hooks/useCheckpoints.js

@@ -14,7 +14,8 @@ 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 } from './useAgentRuntimes';
+import { agentQueryKeys, AGENT_QUERY_OPTIONS, clearRuntimePodDeleted, } from './useAgentRuntimes';
+import { disposeSandboxServiceManagers } from '../services/sandboxServiceManagers';
 // ═══════════════════════════════════════════════════════════════════════════
 // Query hooks
 // ═══════════════════════════════════════════════════════════════════════════
@@ -32,7 +33,7 @@ export function useCheckpointsQuery() {
         queryKey: agentQueryKeys.checkpoints.lists(),
         queryFn: async () => {
             const resp = await requestDatalayer({
-                url: `${configuration.runtimesRunUrl}/api/runtimes/v1/runtime-checkpoints`,
+                url: `${configuration.runtimesUrl}/api/runtimes/v1/runtime-checkpoints`,
                 method: 'GET',
             });
             if (resp.success && resp.checkpoints) {
@@ -71,7 +72,7 @@ export function useDeletePausedAgentRuntime() {
     return useMutation({
         mutationFn: async (podName) => {
             return requestDatalayer({
-                url: `${configuration.runtimesRunUrl}/api/runtimes/v1/runtimes/${podName}/paused`,
+                url: `${configuration.runtimesUrl}/api/runtimes/v1/runtimes/${podName}/paused`,
                 method: 'DELETE',
             });
         },
@@ -101,11 +102,14 @@ export function useResumePausedAgentRuntime() {
     return useMutation({
         mutationFn: async (podName) => {
             return requestDatalayer({
-                url: `${configuration.runtimesRunUrl}/api/runtimes/v1/runtimes/${podName}/resume`,
+                url: `${configuration.runtimesUrl}/api/runtimes/v1/runtimes/${podName}/resume`,
                 method: 'POST',
             });
         },
-        onSuccess: () => {
+        onSuccess: (_data, podName) => {
+            // 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);
             queryClient.invalidateQueries({
                 queryKey: agentQueryKeys.agentRuntimes.all(),
             });
@@ -131,10 +135,10 @@ export function usePauseAgent() {
         mutationFn: async (params) => {
             const { iamStore, coreStore } = await import('@datalayer/core/lib/state');
             const token = iamStore.getState().token || '';
-            const runtimesRunUrl = coreStore.getState().configuration?.runtimesRunUrl || '';
-            const { pauseRuntime } = await import('@datalayer/core/lib/api/runtimes/runtimes');
+            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, runtimesRunUrl, {
+            const resp = await pauseRuntime(token, params.podName, runtimesUrl, {
                 agent_spec_id: params.agentSpecId,
                 checkpoint_mode: mode,
                 ...(params.messages && mode === 'light'
@@ -143,15 +147,18 @@ export function usePauseAgent() {
                 ...(params.agentSpec ? { agentspec: params.agentSpec } : {}),
             });
             if (resp.checkpoint_id) {
-                const { waitForCheckpointStatus } = await import('@datalayer/core/lib/api/runtimes/checkpoints');
-                const ckpt = await waitForCheckpointStatus(token, params.podName, resp.checkpoint_id, ['paused', 'failed'], runtimesRunUrl);
+                const { waitForCheckpointStatus } = await import('../api/runtimes/checkpoints');
+                const ckpt = await waitForCheckpointStatus(token, params.podName, resp.checkpoint_id, ['paused', 'failed'], runtimesUrl);
                 if (ckpt.status === 'failed') {
                     throw new Error(`Checkpoint ${resp.checkpoint_id} failed during ${mode.toUpperCase()} pause`);
                 }
             }
             return resp;
         },
-        onSuccess: () => {
+        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);
             queryClient.invalidateQueries({
                 queryKey: agentQueryKeys.agentRuntimes.all(),
             });
@@ -173,15 +180,18 @@ export function useResumeAgent() {
         mutationFn: async (params) => {
             const { iamStore, coreStore } = await import('@datalayer/core/lib/state');
             const token = iamStore.getState().token || '';
-            const runtimesRunUrl = coreStore.getState().configuration?.runtimesRunUrl || '';
-            const { resumeRuntime } = await import('@datalayer/core/lib/api/runtimes/runtimes');
-            return resumeRuntime(token, params.podName, runtimesRunUrl, {
+            const runtimesUrl = coreStore.getState().configuration?.runtimesUrl || '';
+            const { resumeRuntime } = await import('../api/runtimes/runtimes');
+            return resumeRuntime(token, params.podName, runtimesUrl, {
                 agent_spec_id: params.agentSpecId,
                 ...(params.mode ? { checkpoint_mode: params.mode } : {}),
                 ...(params.checkpointId ? { checkpoint_id: params.checkpointId } : {}),
             });
         },
-        onSuccess: () => {
+        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);
             queryClient.invalidateQueries({
                 queryKey: agentQueryKeys.agentRuntimes.all(),
             });
@@ -203,11 +213,11 @@ export function useCheckpointAgent() {
         mutationFn: async (params) => {
             const { iamStore, coreStore } = await import('@datalayer/core/lib/state');
             const token = iamStore.getState().token || '';
-            const runtimesRunUrl = coreStore.getState().configuration?.runtimesRunUrl || '';
-            const { pauseRuntime } = await import('@datalayer/core/lib/api/runtimes/runtimes');
-            const { waitForCheckpointStatus } = await import('@datalayer/core/lib/api/runtimes/checkpoints');
+            const runtimesUrl = coreStore.getState().configuration?.runtimesUrl || '';
+            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, runtimesRunUrl, {
+            const pauseResp = await pauseRuntime(token, params.podName, runtimesUrl, {
                 name: params.name || `checkpoint-${Date.now()}`,
                 description: `${mode.toUpperCase()} checkpoint for ${params.agentSpecId}`,
                 checkpoint_mode: mode,
@@ -221,7 +231,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'], runtimesRunUrl);
+            const ckpt = await waitForCheckpointStatus(token, params.podName, checkpointId, ['paused', 'failed'], runtimesUrl);
             if (ckpt.status === 'failed') {
                 throw new Error(`Checkpoint ${checkpointId} failed during ${mode.toUpperCase()} pause`);
             }
@@ -249,9 +259,9 @@ export function useTerminateAgent() {
         mutationFn: async (params) => {
             const { iamStore, coreStore } = await import('@datalayer/core/lib/state');
             const token = iamStore.getState().token || '';
-            const runtimesRunUrl = coreStore.getState().configuration?.runtimesRunUrl || '';
-            const { deleteRuntime } = await import('@datalayer/core/lib/api/runtimes/runtimes');
-            return deleteRuntime(token, params.podName, runtimesRunUrl);
+            const runtimesUrl = coreStore.getState().configuration?.runtimesUrl || '';
+            const { deleteRuntime } = await import('../api/runtimes/runtimes');
+            return deleteRuntime(token, params.podName, runtimesUrl);
         },
         onSuccess: () => {
             queryClient.invalidateQueries({
@@ -330,9 +340,9 @@ export function useAgentLifecycle(options) {
                 try {
                     const { iamStore, coreStore } = await import('@datalayer/core/lib/state');
                     const token = iamStore.getState().token || '';
-                    const runtimesRunUrl = coreStore.getState().configuration?.runtimesRunUrl || '';
-                    const { listRuntimes } = await import('@datalayer/core/lib/api/runtimes/runtimes');
-                    const runtimesResponse = await listRuntimes(token, runtimesRunUrl);
+                    const runtimesUrl = coreStore.getState().configuration?.runtimesUrl || '';
+                    const { listRuntimes } = await import('../api/runtimes/runtimes');
+                    const runtimesResponse = await listRuntimes(token, runtimesUrl);
                     const runtimes = runtimesResponse.runtimes || [];
                     const aiAgentRuntimes = runtimes.filter(rt => {
                         if (rt.environment_name !== 'ai-agents-env') {
@@ -341,9 +351,9 @@ export function useAgentLifecycle(options) {
                         if (!agentSpecId) {
                             return true;
                         }
-                        const runtimeAgentSpecId = rt
+                        const runtimeAgentspecId = rt
                             .agent_spec_id;
-                        return runtimeAgentSpecId === agentSpecId;
+                        return runtimeAgentspecId === agentSpecId;
                     });
                     const latestRuntime = aiAgentRuntimes.slice().sort((a, b) => {
                         const aTs = Number(a.started_at || 0);

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<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> | {
+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> | {
     data: undefined;
     isLoading: boolean;
     isError: boolean;

package/lib/hooks/useMonitoring.d.ts

@@ -1,9 +1,10 @@
 export interface OtelQueryOptions {
     metric: string;
     serviceName?: string;
-    runUrl?: string;
+    datalayerUrl?: string;
     apiKey?: string;
     limit?: number;
+    accountUid?: string;
 }
 interface MetricValueRow {
     value?: unknown;
@@ -11,14 +12,15 @@ interface MetricValueRow {
     value_int?: unknown;
 }
 export declare function toMetricValue(row: MetricValueRow): number;
-export declare function fetchOtelMetricRows({ metric, serviceName, runUrl, apiKey, limit, }: OtelQueryOptions): Promise<MetricValueRow[]>;
+export declare function fetchOtelMetricRows({ metric, serviceName, datalayerUrl, apiKey, limit, accountUid, }: OtelQueryOptions): Promise<MetricValueRow[]>;
 export declare function fetchOtelMetricTotal(options: OtelQueryOptions): Promise<number>;
 export interface OtelTotalTokensOptions {
     serviceName?: string;
-    runUrl?: string;
+    datalayerUrl?: string;
     apiKey?: string;
     limit?: number;
+    accountUid?: string;
 }
-export declare function fetchOtelTotalTokens({ serviceName, runUrl, apiKey, limit, }: OtelTotalTokensOptions): Promise<number>;
-export declare function useOtelTotalTokens({ serviceName, runUrl, apiKey, limit, }: OtelTotalTokensOptions): string;
+export declare function fetchOtelTotalTokens({ serviceName, datalayerUrl, apiKey, limit, accountUid, }: OtelTotalTokensOptions): Promise<number>;
+export declare function useOtelTotalTokens({ serviceName, datalayerUrl, apiKey, limit, accountUid, }: OtelTotalTokensOptions): string;
 export {};

package/lib/hooks/useMonitoring.js

@@ -24,18 +24,19 @@ export function toMetricValue(row) {
     }
     return 0;
 }
-export async function fetchOtelMetricRows({ metric, serviceName, runUrl, apiKey, limit = 500, }) {
-    if (!runUrl || !apiKey) {
+export async function fetchOtelMetricRows({ metric, serviceName, datalayerUrl, apiKey, limit = 500, accountUid, }) {
+    if (!datalayerUrl || !apiKey) {
         return [];
     }
     const client = createOtelClient({
-        baseUrl: runUrl,
+        baseUrl: datalayerUrl,
         token: apiKey,
     });
     const filtered = await client.fetchMetrics({
         metricName: metric,
         serviceName,
         limit,
+        accountUid,
     });
     if (filtered.data.length > 0 || !serviceName) {
         return filtered.data;
@@ -43,6 +44,7 @@ export async function fetchOtelMetricRows({ metric, serviceName, runUrl, apiKey,
     const fallback = await client.fetchMetrics({
         metricName: metric,
         limit,
+        accountUid,
     });
     return fallback.data;
 }
@@ -50,13 +52,14 @@ export async function fetchOtelMetricTotal(options) {
     const rows = await fetchOtelMetricRows(options);
     return rows.reduce((sum, row) => sum + toMetricValue(row), 0);
 }
-export async function fetchOtelTotalTokens({ serviceName, runUrl, apiKey, limit = 500, }) {
+export async function fetchOtelTotalTokens({ serviceName, datalayerUrl, apiKey, limit = 500, accountUid, }) {
     const total = await fetchOtelMetricTotal({
         metric: 'agent_runtimes.prompt.turn.total_tokens',
         serviceName,
-        runUrl,
+        datalayerUrl,
         apiKey,
         limit,
+        accountUid,
     });
     if (total > 0) {
         return total;
@@ -64,20 +67,22 @@ export async function fetchOtelTotalTokens({ serviceName, runUrl, apiKey, limit
     const prompt = await fetchOtelMetricTotal({
         metric: 'agent_runtimes.prompt.turn.prompt_tokens',
         serviceName,
-        runUrl,
+        datalayerUrl,
         apiKey,
         limit,
+        accountUid,
     });
     const completion = await fetchOtelMetricTotal({
         metric: 'agent_runtimes.prompt.turn.completion_tokens',
         serviceName,
-        runUrl,
+        datalayerUrl,
         apiKey,
         limit,
+        accountUid,
     });
     return prompt + completion;
 }
-export function useOtelTotalTokens({ serviceName, runUrl, apiKey, limit = 500, }) {
+export function useOtelTotalTokens({ serviceName, datalayerUrl, apiKey, limit = 500, accountUid, }) {
     const [tokensLabel, setTokensLabel] = useState('-');
     useEffect(() => {
         let cancelled = false;
@@ -85,9 +90,10 @@ export function useOtelTotalTokens({ serviceName, runUrl, apiKey, limit = 500, }
             try {
                 const total = await fetchOtelTotalTokens({
                     serviceName,
-                    runUrl,
+                    datalayerUrl,
                     apiKey,
                     limit,
+                    accountUid,
                 });
                 if (cancelled) {
                     return;
@@ -109,6 +115,6 @@ export function useOtelTotalTokens({ serviceName, runUrl, apiKey, limit = 500, }
         return () => {
             cancelled = true;
         };
-    }, [apiKey, limit, runUrl, serviceName]);
+    }, [apiKey, limit, datalayerUrl, serviceName, accountUid]);
     return tokensLabel;
 }

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<import("../types").AgentNotification[], Error>;
-export declare function useUnreadNotificationCount(): import("@tanstack/react-query").UseQueryResult<{
+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<{
     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<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 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 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<import("../types").AgentNotification[], Error>;
-    unreadCountQuery: import("@tanstack/react-query").UseQueryResult<{
+    notificationsQuery: import("@tanstack/react-query").UseQueryResult<NoInfer<import("../types").AgentNotification[]>, Error>;
+    unreadCountQuery: import("@tanstack/react-query").UseQueryResult<NoInfer<{
         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<import("../types").ListAgentEventsResponse, Error>;
-    eventQuery: import("@tanstack/react-query").UseQueryResult<import("../types").GetAgentEventResponse, Error>;
+    eventsQuery: import("@tanstack/react-query").UseQueryResult<NoInfer<import("../types").ListAgentEventsResponse>, Error>;
+    eventQuery: import("@tanstack/react-query").UseQueryResult<NoInfer<import("../types").GetAgentEventResponse>, Error>;
     createEvent: import("@tanstack/react-query").UseMutationResult<{
         success: boolean;
         event: import("../types").AgentEvent;

package/lib/hooks/useNotifications.js

@@ -19,7 +19,7 @@ function useAuthToken() {
 }
 function useBaseUrl() {
     const config = useCoreStore((s) => s.configuration);
-    return config?.aiagentsRunUrl ?? DEFAULT_SERVICE_URLS.AI_AGENTS;
+    return config?.aiAgentsUrl ?? DEFAULT_SERVICE_URLS.AI_AGENTS;
 }
 // ─── Base hooks ──────────────────────────────────────────────────────
 export function useFilteredNotifications(filters) {

package/lib/hooks/useProgressStore.d.ts

@@ -0,0 +1,25 @@
+/**
+ * State shape for the global top progress bar.
+ */
+export type ProgressState = {
+    /** Map of currently-active task ids. */
+    tasks: Record<string, true>;
+    /** True while at least one task is active. */
+    isActive: boolean;
+    /**
+     * Mark a task as active. Returns the task id so callers can stop it later.
+     * When no id is supplied a unique one is generated.
+     */
+    startTask: (id?: string) => string;
+    /** Mark a task as no longer active. */
+    stopTask: (id: string) => void;
+    /**
+     * Bind the bar to a boolean loading flag for a given task id. Convenient
+     * inside effects: `setTaskActive('volumes', volumesLoading)`.
+     */
+    setTaskActive: (id: string, active: boolean) => void;
+    /** Clear every active task (hides the bar). */
+    reset: () => void;
+};
+export declare const useProgressStore: import("zustand").UseBoundStore<import("zustand").StoreApi<ProgressState>>;
+export default useProgressStore;

package/lib/hooks/useProgressStore.js

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Global "top progress bar" store.
+ *
+ * Drives a single, app-wide GitHub-style indeterminate progress bar rendered
+ * at the bottom edge of a view header. Any UI component can signal that
+ * background work is happening without owning its own spinner.
+ *
+ * Concurrency is handled by reference-counting active tasks keyed by an
+ * arbitrary id, so multiple overlapping loads keep the bar visible until the
+ * last one finishes. Use {@link ProgressState.setTaskActive} to bind the bar
+ * to a boolean loading flag, or {@link ProgressState.startTask} /
+ * {@link ProgressState.stopTask} for imperative start/stop pairs. The
+ * {@link useProgressTask} hook wraps this store for the common effect-driven
+ * case.
+ *
+ * @module hooks/useProgressStore
+ */
+import { create } from 'zustand';
+const computeActive = (tasks) => Object.keys(tasks).length > 0;
+export const useProgressStore = create((set, get) => ({
+    tasks: {},
+    isActive: false,
+    startTask: id => {
+        const taskId = id || `progress-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        set(state => {
+            if (state.tasks[taskId]) {
+                return state;
+            }
+            const tasks = { ...state.tasks, [taskId]: true };
+            return { tasks, isActive: computeActive(tasks) };
+        });
+        return taskId;
+    },
+    stopTask: id => {
+        set(state => {
+            if (!state.tasks[id]) {
+                return state;
+            }
+            const tasks = { ...state.tasks };
+            delete tasks[id];
+            return { tasks, isActive: computeActive(tasks) };
+        });
+    },
+    setTaskActive: (id, active) => {
+        if (active) {
+            get().startTask(id);
+        }
+        else {
+            get().stopTask(id);
+        }
+    },
+    reset: () => set({ tasks: {}, isActive: false }),
+}));
+export default useProgressStore;

package/lib/hooks/useProgressTask.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Drive the shared top progress bar from a boolean loading flag.
+ *
+ * @param id - Stable, unique task id (e.g. `'volumes'`). Distinct ids let
+ *   concurrent loads coexist without prematurely hiding the bar.
+ * @param active - Whether the task is currently in progress.
+ */
+export declare function useProgressTask(id: string, active: boolean): void;
+export default useProgressTask;

package/lib/hooks/useProgressTask.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Reusable hook that binds a boolean loading flag to the global top progress
+ * bar ({@link useProgressStore}). While `active` is true the shared bar shows
+ * activity; it is automatically released when `active` turns false or the
+ * component unmounts.
+ *
+ * Because the bar reference-counts tasks by id, multiple overlapping loads
+ * (across any views) keep the single app-wide bar visible until the last one
+ * completes.
+ *
+ * @example
+ * ```tsx
+ * const { isPending } = useVolumes();
+ * useProgressTask('volumes', isPending);
+ * ```
+ *
+ * @module hooks/useProgressTask
+ */
+import { useEffect } from 'react';
+import { useProgressStore } from './useProgressStore';
+/**
+ * Drive the shared top progress bar from a boolean loading flag.
+ *
+ * @param id - Stable, unique task id (e.g. `'volumes'`). Distinct ids let
+ *   concurrent loads coexist without prematurely hiding the bar.
+ * @param active - Whether the task is currently in progress.
+ */
+export function useProgressTask(id, active) {
+    const setTaskActive = useProgressStore(state => state.setTaskActive);
+    useEffect(() => {
+        setTaskActive(id, active);
+        return () => {
+            setTaskActive(id, false);
+        };
+    }, [id, active, setTaskActive]);
+}
+export default useProgressTask;