@datalayer/agent-runtimes 1.0.3 → 1.0.5

package/lib/hooks/{useAgents.js → useAgentRuntimes.js}

@@ -3,13 +3,13 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Unified hook for managing agents.
+ * Unified hook for managing agent runtimes.
  *
  * Combines agent lifecycle management (ephemeral/durable),
  * runtime catalog (React Query CRUD), lifecycle/catalog stores,
- * and the AI Agents REST API.
+ * the AI Agents REST API, and the agent-runtime WebSocket stream.
  *
- * @module hooks/useAgents
+ * @module hooks/useAgentRuntimes
  */
 import { useState, useCallback, useMemo, useEffect, useRef } from 'react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
@@ -17,7 +17,8 @@ import { create } from 'zustand';
 import { persist, createJSONStorage } from 'zustand/middleware';
 import { useCoreStore, useDatalayer } from '@datalayer/core';
 import { useIAMStore } from '@datalayer/core/lib/state';
-import { useAgentStore, useAgentRuntime, useAgentStatus, useAgentError, useIsLaunching, } from '../stores/agentsStore';
+import { agentRuntimeStore, useAgentRuntimeStore, useAgentRuntimeConnection, useAgentRuntimeStatus, useAgentRuntimeError, useAgentRuntimeIsLaunching, } from '../stores/agentRuntimeStore';
+import { parseAgentStreamMessage, } from '../types/stream';
 import { DEFAULT_AGENT_CONFIG } from '../types/config';
 // ═══════════════════════════════════════════════════════════════════════════
 // Constants
@@ -103,18 +104,18 @@ function toAgentRuntimeData(raw) {
  * });
  * ```
  */
-export function useAgents(options = {}) {
+export function useAgentRuntimes(options = {}) {
     const { agentSpecId, agentConfig, autoCreateAgent = true, autoStart = false, agentSpec, } = options;
     // Base store state
-    const runtime = useAgentRuntime();
-    const baseStatus = useAgentStatus();
-    const storeError = useAgentError();
-    const isLaunching = useIsLaunching();
+    const runtime = useAgentRuntimeConnection();
+    const baseStatus = useAgentRuntimeStatus();
+    const storeError = useAgentRuntimeError();
+    const isLaunching = useAgentRuntimeIsLaunching();
     // Store actions
-    const storeLaunchAgent = useAgentStore(state => state.launchAgent);
-    const storeConnectAgent = useAgentStore(state => state.connectAgent);
-    const storeCreateAgent = useAgentStore(state => state.createAgent);
-    const storeDisconnect = useAgentStore(state => state.disconnect);
+    const storeLaunchAgent = useAgentRuntimeStore(state => state.launchAgent);
+    const storeConnectAgent = useAgentRuntimeStore(state => state.connectAgent);
+    const storeCreateAgent = useAgentRuntimeStore(state => state.createAgent);
+    const storeDisconnect = useAgentRuntimeStore(state => state.disconnect);
     // Lifecycle local state
     const [lifecycleStatus, setLifecycleStatus] = useState('idle');
     const [lifecycleError, setLifecycleError] = useState(null);
@@ -408,7 +409,7 @@ export function useAgents(options = {}) {
  * The backend returns active runtimes from the operator **plus** paused
  * runtimes synthesised from Solr checkpoint records (with ``status="paused"``).
  */
-export function useAgentRuntimes() {
+export function useAgentRuntimesQuery() {
     const { configuration } = useCoreStore();
     const { requestDatalayer } = useDatalayer({ notifyOnError: false });
     const { user } = useIAMStore();
@@ -607,7 +608,7 @@ export const useAgentLifecycleStore = create()(persist((set, get) => ({
  * Consolidated runtime list and mutations.
  */
 export function useAgentsRuntimes() {
-    const runtimesQuery = useAgentRuntimes();
+    const runtimesQuery = useAgentRuntimesQuery();
     const createRuntimeMutation = useCreateAgentRuntime();
     const deleteRuntimeMutation = useDeleteAgentRuntime();
     const refreshRuntimes = useRefreshAgentRuntimes();
@@ -631,3 +632,112 @@ export function useAgentsRuntimes() {
         deleteRuntimeMutation,
     ]);
 }
+const DEFAULT_WS_PATH = '/api/v1/tool-approvals/ws';
+const DEFAULT_RECONNECT_DELAY_MS = 3_000;
+/**
+ * Connect to the agent-runtime monitoring WebSocket.
+ *
+ * The hook writes all incoming data into the `useAgentRuntimeStore` Zustand
+ * store. Components that need approvals, MCP status, context snapshots, or
+ * full-context data simply read from the store.
+ *
+ * Mount this hook **once** near the top of your component tree (e.g. in
+ * the example root or in `ChatBase`). All other components read from the
+ * store — no extra WebSocket connections needed.
+ */
+export function useAgentRuntimeWebSocket(options) {
+    const { enabled = true, baseUrl, authToken, agentId, autoReconnect = true, reconnectDelayMs = DEFAULT_RECONNECT_DELAY_MS, maxReconnectAttempts, } = options;
+    const onMessageRef = useRef(options.onMessage);
+    onMessageRef.current = options.onMessage;
+    useEffect(() => {
+        if (!enabled || !baseUrl) {
+            agentRuntimeStore.getState().setWsState('closed');
+            return;
+        }
+        let disposed = false;
+        let reconnectAttempts = 0;
+        let reconnectTimer = null;
+        function buildWsUrl() {
+            const httpUrl = `${baseUrl}${DEFAULT_WS_PATH}`;
+            const url = new URL(httpUrl.replace(/^http/, 'ws'));
+            if (authToken) {
+                url.searchParams.set('token', authToken);
+            }
+            if (agentId) {
+                url.searchParams.set('agent_id', agentId);
+            }
+            return url.toString();
+        }
+        function connect() {
+            if (disposed)
+                return;
+            const wsUrl = buildWsUrl();
+            agentRuntimeStore.getState().setWsState('connecting');
+            const ws = new WebSocket(wsUrl);
+            agentRuntimeStore.getState().setWs(ws, agentId);
+            ws.onopen = () => {
+                reconnectAttempts = 0;
+                agentRuntimeStore.getState().setWsState('connected');
+            };
+            ws.onmessage = (ev) => {
+                let raw;
+                try {
+                    raw = JSON.parse(String(ev.data));
+                }
+                catch {
+                    return;
+                }
+                const parsed = parseAgentStreamMessage(raw);
+                onMessageRef.current?.({
+                    type: parsed?.type,
+                    payload: parsed?.payload,
+                    raw,
+                });
+                if (!parsed)
+                    return;
+                const state = agentRuntimeStore.getState();
+                if (parsed.type === 'agent.snapshot') {
+                    state.applySnapshot(parsed.payload);
+                    return;
+                }
+            };
+            ws.onclose = () => {
+                agentRuntimeStore.getState().setWs(null, agentId);
+                agentRuntimeStore.getState().setWsState('closed');
+                if (disposed || !autoReconnect)
+                    return;
+                reconnectAttempts += 1;
+                if (typeof maxReconnectAttempts === 'number' &&
+                    reconnectAttempts > maxReconnectAttempts) {
+                    return;
+                }
+                const delay = typeof reconnectDelayMs === 'function'
+                    ? reconnectDelayMs(reconnectAttempts)
+                    : reconnectDelayMs;
+                reconnectTimer = setTimeout(connect, Math.max(0, delay));
+            };
+            ws.onerror = () => {
+                if (ws.readyState === WebSocket.CONNECTING ||
+                    ws.readyState === WebSocket.OPEN) {
+                    ws.close();
+                }
+            };
+        }
+        connect();
+        return () => {
+            disposed = true;
+            if (reconnectTimer)
+                clearTimeout(reconnectTimer);
+            agentRuntimeStore.getState().setWs(null, agentId);
+            agentRuntimeStore.getState().resetWs();
+        };
+    }, [
+        enabled,
+        baseUrl,
+        authToken,
+        agentId,
+        autoReconnect,
+        reconnectDelayMs,
+        maxReconnectAttempts,
+    ]);
+}

package/lib/hooks/useAgentsCatalog.js

@@ -3,7 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Agent catalog hooks.
+ * Agents catalog hooks.
  *
  * Includes the Zustand catalog store and the agent registry hook.
  *

package/lib/hooks/useAgentsService.d.ts

@@ -4,7 +4,7 @@ export type RequestOptions = {
 };
 export type RoomType = 'notebook_persist' | 'notebook_memory' | 'doc_memory';
 /**
- * @deprecated Use useAgents instead
+ * @deprecated Use useAgentRuntimes instead
  */
 export declare const useAgentsService: (baseUrlOverride?: string) => {
     createAgent: (documentId: string, documentType: RoomType, ingress?: string, token?: string, kernelId?: string, { signal, baseUrl }?: RequestOptions) => Promise<any>;
@@ -17,6 +17,6 @@ export declare const useAgentsService: (baseUrlOverride?: string) => {
  * Get the notebook AI agent if any.
  *
  * This performs a periodic liveness check and keeps the local store in sync.
- * @deprecated Use useAgents instead
+ * @deprecated Use useAgentRuntimes instead
  */
 export declare function useNotebookAgents(notebookId: string): import("..").AgentRegistryEntry | undefined;

package/lib/hooks/useAgentsService.js

@@ -11,12 +11,12 @@
 import { useEffect } from 'react';
 import { useCoreStore, useDatalayer } from '@datalayer/core';
 import { URLExt } from '@jupyterlab/coreutils';
-import { useAgentStore } from '../stores/agentsStore';
+import { useAgentRuntimeStore } from '../stores/agentRuntimeStore';
 // ═══════════════════════════════════════════════════════════════════════════
 // Agents Service REST API hook.
 // ═══════════════════════════════════════════════════════════════════════════
 /**
- * @deprecated Use useAgents instead
+ * @deprecated Use useAgentRuntimes instead
  */
 export const useAgentsService = (baseUrlOverride = 'api/ai-agents/v1') => {
     const { configuration } = useCoreStore();
@@ -86,14 +86,14 @@ export const useAgentsService = (baseUrlOverride = 'api/ai-agents/v1') => {
  * Get the notebook AI agent if any.
  *
  * This performs a periodic liveness check and keeps the local store in sync.
- * @deprecated Use useAgents instead
+ * @deprecated Use useAgentRuntimes instead
  */
 export function useNotebookAgents(notebookId) {
     const { getAgent } = useAgentsService();
-    const agents = useAgentStore(state => state.agents);
-    const upsertAgent = useAgentStore(state => state.upsertAgent);
-    const deleteAgent = useAgentStore(state => state.deleteAgent);
-    const getAgentById = useAgentStore(state => state.getAgentById);
+    const agents = useAgentRuntimeStore(state => state.agents);
+    const upsertAgent = useAgentRuntimeStore(state => state.upsertAgent);
+    const deleteAgent = useAgentRuntimeStore(state => state.deleteAgent);
+    const getAgentById = useAgentRuntimeStore(state => state.getAgentById);
     useEffect(() => {
         let abortController;
         const refreshAIAgent = async () => {

package/lib/hooks/useCheckpoints.js

@@ -14,7 +14,7 @@ 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 './useAgents';
+import { agentQueryKeys, AGENT_QUERY_OPTIONS } from './useAgentRuntimes';
 // ═══════════════════════════════════════════════════════════════════════════
 // Query hooks
 // ═══════════════════════════════════════════════════════════════════════════

package/lib/hooks/useConfig.d.ts

@@ -3,9 +3,12 @@ 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): 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<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;
     error: null;
+    refetch: () => Promise<{
+        data: undefined;
+    }>;
 };

package/lib/hooks/useConfig.js

@@ -9,7 +9,7 @@ import { requestAPI } from '../api/handler';
  * Hook to safely use query when QueryClient is available.
  * Returns a mock result if no QueryClientProvider is present.
  */
-export function useConfig(enabled, configEndpoint, authToken) {
+export function useConfig(enabled, configEndpoint, authToken, agentId) {
     const queryClient = useContext(QueryClientContext);
     if (!queryClient) {
         return {
@@ -17,6 +17,7 @@ export function useConfig(enabled, configEndpoint, authToken) {
             isLoading: false,
             isError: false,
             error: null,
+            refetch: () => Promise.resolve({ data: undefined }),
         };
     }
     // eslint-disable-next-line react-hooks/rules-of-hooks
@@ -30,7 +31,13 @@ export function useConfig(enabled, configEndpoint, authToken) {
                 if (authToken) {
                     headers['Authorization'] = `Bearer ${authToken}`;
                 }
-                const response = await fetch(configEndpoint, { headers });
+                let endpoint = configEndpoint;
+                if (agentId) {
+                    const url = new URL(configEndpoint, window.location.origin);
+                    url.searchParams.set('agent_id', agentId);
+                    endpoint = url.toString();
+                }
+                const response = await fetch(endpoint, { headers });
                 if (!response.ok) {
                     throw new Error(`Config fetch failed: ${response.statusText}`);
                 }
@@ -39,7 +46,7 @@ export function useConfig(enabled, configEndpoint, authToken) {
             // Otherwise use Jupyter requestAPI.
             return requestAPI('configure');
         },
-        queryKey: ['models', configEndpoint || 'jupyter'],
+        queryKey: ['models', configEndpoint || 'jupyter', agentId || 'global'],
         enabled,
         retry: 1,
     });

package/lib/hooks/useContextSnapshot.d.ts

@@ -1,10 +1,15 @@
 import type { ContextSnapshotData } from '../types/context';
 /**
- * Hook to poll agent context-snapshot from the backend.
- * Returns cumulative token usage (input/output breakdown) tracked by the agent server.
+ * 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.
  */
-export declare function useContextSnapshot(enabled: boolean, configEndpoint?: string, agentId?: string, authToken?: string): import("@tanstack/query-core").QueryObserverRefetchErrorResult<ContextSnapshotData, Error> | import("@tanstack/query-core").QueryObserverSuccessResult<ContextSnapshotData, Error> | import("@tanstack/query-core").QueryObserverLoadingErrorResult<ContextSnapshotData, Error> | import("@tanstack/query-core").QueryObserverPendingResult<ContextSnapshotData, Error> | import("@tanstack/query-core").QueryObserverPlaceholderResult<ContextSnapshotData, Error> | {
-    data: undefined;
+export declare function useContextSnapshot(_enabled: boolean, _configEndpoint?: string, _agentId?: string, _authToken?: string): {
+    data: ContextSnapshotData | undefined;
     isLoading: boolean;
     isError: boolean;
     error: null;

package/lib/hooks/useContextSnapshot.js

@@ -2,43 +2,15 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { useContext } from 'react';
-import { useQuery, QueryClientContext } from '@tanstack/react-query';
-import { getApiBaseFromConfig } from '../utils';
 /**
- * Hook to poll agent context-snapshot from the backend.
- * Returns cumulative token usage (input/output breakdown) tracked by the agent server.
+ * 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.
  */
-export function useContextSnapshot(enabled, configEndpoint, agentId, authToken) {
-    const queryClient = useContext(QueryClientContext);
-    if (!queryClient) {
-        return { data: undefined, isLoading: false, isError: false, error: null };
-    }
-    const snapshotUrl = configEndpoint && agentId
-        ? `${getApiBaseFromConfig(configEndpoint)}/configure/agents/${encodeURIComponent(agentId)}/context-snapshot`
-        : undefined;
-    // eslint-disable-next-line react-hooks/rules-of-hooks
-    return useQuery({
-        queryKey: ['context-snapshot-header', agentId, snapshotUrl],
-        queryFn: async () => {
-            if (!snapshotUrl) {
-                throw new Error('No context-snapshot URL available');
-            }
-            const headers = { 'Content-Type': 'application/json' };
-            if (authToken) {
-                headers['Authorization'] = `Bearer ${authToken}`;
-            }
-            const response = await fetch(snapshotUrl, { headers });
-            if (!response.ok) {
-                throw new Error(`Context snapshot fetch failed: ${response.statusText}`);
-            }
-            return response.json();
-        },
-        enabled: enabled && !!snapshotUrl,
-        // Poll every 10s, but stop after an error (e.g. runtime terminated).
-        refetchInterval: query => (query.state.status === 'error' ? false : 10_000),
-        refetchOnMount: 'always',
-        staleTime: 0,
-        retry: 1,
-    });
+export function useContextSnapshot(_enabled, _configEndpoint, _agentId, _authToken) {
+    return { data: undefined, isLoading: false, isError: false, error: null };
 }

package/lib/hooks/useMonitoring.js

@@ -25,6 +25,9 @@ export function toMetricValue(row) {
     return 0;
 }
 export async function fetchOtelMetricRows({ metric, serviceName, runUrl, apiKey, limit = 500, }) {
+    if (!runUrl || !apiKey) {
+        return [];
+    }
     const client = createOtelClient({
         baseUrl: runUrl,
         token: apiKey,

package/lib/hooks/useSandbox.d.ts

@@ -1,12 +1,24 @@
 import type { SandboxStatusData } from '../types/context';
 /**
- * Hook to poll sandbox execution status from the backend.
- * Returns whether a sandbox is available and if code is currently executing.
+ * Subscribe to the sandbox execution status via the
+ * `/api/v1/configure/sandbox/ws` WebSocket.
+ *
+ * This hook replaces the previous REST-polling implementation — the server
+ * now pushes status updates in real time and accepts interrupt requests over
+ * the same connection.
+ *
+ * @param enabled         Whether to open the WebSocket connection.
+ * @param configEndpoint  Base `configEndpoint` used by other chat hooks
+ *                        (e.g. `http://localhost:8765/api/v1/configure/config`).
+ * @param authToken       Optional bearer token (passed as `?token=` query param
+ *                        because browsers cannot set headers on WebSocket).
+ * @param agentId         Optional agent id; the backend returns an
+ *                        agent-scoped status when provided.
+ * @returns `{ data, interrupt }` where `data` is the latest status (or
+ *          `undefined` until the first message) and `interrupt()` sends an
+ *          `{ action: 'interrupt' }` message over the same WebSocket.
  */
-export declare function useSandbox(enabled: boolean, configEndpoint?: string, authToken?: string): import("@tanstack/query-core").QueryObserverRefetchErrorResult<SandboxStatusData, Error> | import("@tanstack/query-core").QueryObserverSuccessResult<SandboxStatusData, Error> | import("@tanstack/query-core").QueryObserverLoadingErrorResult<SandboxStatusData, Error> | import("@tanstack/query-core").QueryObserverPendingResult<SandboxStatusData, Error> | import("@tanstack/query-core").QueryObserverPlaceholderResult<SandboxStatusData, Error> | {
-    data: undefined;
-    isLoading: boolean;
-    isError: boolean;
-    error: null;
-    refetch: () => Promise<any>;
+export declare function useSandbox(enabled: boolean, configEndpoint?: string, authToken?: string, agentId?: string): {
+    data: SandboxStatusData | undefined;
+    interrupt: () => void;
 };

package/lib/hooks/useSandbox.js

@@ -2,48 +2,113 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { useContext } from 'react';
-import { useQuery, QueryClientContext } from '@tanstack/react-query';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { getApiBaseFromConfig } from '../utils';
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_MAX_MS = 30000;
+function isRetryableCloseCode(code) {
+    // Avoid reconnect loops for policy/auth/protocol closures.
+    const nonRetryable = new Set([1002, 1003, 1007, 1008, 4401, 4403]);
+    return !nonRetryable.has(code);
+}
 /**
- * Hook to poll sandbox execution status from the backend.
- * Returns whether a sandbox is available and if code is currently executing.
+ * Subscribe to the sandbox execution status via the
+ * `/api/v1/configure/sandbox/ws` WebSocket.
+ *
+ * This hook replaces the previous REST-polling implementation — the server
+ * now pushes status updates in real time and accepts interrupt requests over
+ * the same connection.
+ *
+ * @param enabled         Whether to open the WebSocket connection.
+ * @param configEndpoint  Base `configEndpoint` used by other chat hooks
+ *                        (e.g. `http://localhost:8765/api/v1/configure/config`).
+ * @param authToken       Optional bearer token (passed as `?token=` query param
+ *                        because browsers cannot set headers on WebSocket).
+ * @param agentId         Optional agent id; the backend returns an
+ *                        agent-scoped status when provided.
+ * @returns `{ data, interrupt }` where `data` is the latest status (or
+ *          `undefined` until the first message) and `interrupt()` sends an
+ *          `{ action: 'interrupt' }` message over the same WebSocket.
  */
-export function useSandbox(enabled, configEndpoint, authToken) {
-    const queryClient = useContext(QueryClientContext);
-    if (!queryClient) {
-        return {
-            data: undefined,
-            isLoading: false,
-            isError: false,
-            error: null,
-            refetch: () => Promise.resolve({}),
+export function useSandbox(enabled, configEndpoint, authToken, agentId) {
+    const [data, setData] = useState(undefined);
+    const wsRef = useRef(null);
+    useEffect(() => {
+        if (!enabled || !configEndpoint) {
+            setData(undefined);
+            return;
+        }
+        const apiBase = getApiBaseFromConfig(configEndpoint);
+        if (!apiBase)
+            return;
+        const wsBase = apiBase.replace(/^http/, 'ws');
+        const params = [];
+        if (agentId) {
+            params.push(`agent_id=${encodeURIComponent(agentId)}`);
+        }
+        if (authToken) {
+            // WebSocket API cannot set custom headers — pass token via query param.
+            params.push(`token=${encodeURIComponent(authToken)}`);
+        }
+        const url = `${wsBase}/configure/sandbox/ws${params.length ? `?${params.join('&')}` : ''}`;
+        let disposed = false;
+        let reconnectTimer;
+        let reconnectAttempts = 0;
+        const scheduleReconnect = (code) => {
+            if (disposed || !isRetryableCloseCode(code))
+                return;
+            const delay = Math.min(RECONNECT_BASE_MS * 2 ** reconnectAttempts, RECONNECT_MAX_MS);
+            reconnectAttempts += 1;
+            reconnectTimer = setTimeout(connect, delay);
+        };
+        const connect = () => {
+            if (disposed)
+                return;
+            const ws = new WebSocket(url);
+            wsRef.current = ws;
+            ws.onopen = () => {
+                reconnectAttempts = 0;
+            };
+            ws.onmessage = event => {
+                try {
+                    const msg = JSON.parse(event.data);
+                    if (msg && msg.action === 'interrupt')
+                        return;
+                    const variant = typeof msg?.variant === 'string' ? msg.variant : '';
+                    setData({
+                        available: variant !== 'unavailable' && variant !== 'error',
+                        sandbox_running: Boolean(msg?.sandbox_running),
+                        is_executing: Boolean(msg?.is_executing),
+                        variant,
+                    });
+                }
+                catch {
+                    // Ignore malformed messages.
+                }
+            };
+            ws.onclose = event => {
+                wsRef.current = null;
+                scheduleReconnect(event.code);
+            };
+            ws.onerror = () => {
+                ws.close();
+            };
+        };
+        connect();
+        return () => {
+            disposed = true;
+            if (reconnectTimer)
+                clearTimeout(reconnectTimer);
+            wsRef.current?.close();
+            wsRef.current = null;
+            setData(undefined);
         };
-    }
-    const statusUrl = configEndpoint
-        ? `${getApiBaseFromConfig(configEndpoint)}/configure/sandbox-status`
-        : undefined;
-    // eslint-disable-next-line react-hooks/rules-of-hooks
-    return useQuery({
-        queryKey: ['sandbox-status', statusUrl],
-        queryFn: async () => {
-            if (!statusUrl) {
-                throw new Error('No sandbox status URL available');
-            }
-            const headers = { 'Content-Type': 'application/json' };
-            if (authToken) {
-                headers['Authorization'] = `Bearer ${authToken}`;
-            }
-            const response = await fetch(statusUrl, { headers });
-            if (!response.ok) {
-                throw new Error(`Sandbox status fetch failed: ${response.statusText}`);
-            }
-            return response.json();
-        },
-        enabled: enabled && !!statusUrl,
-        refetchInterval: query => (query.state.status === 'error' ? false : 2_000),
-        refetchOnMount: 'always',
-        staleTime: 0,
-        retry: 1,
-    });
+    }, [enabled, configEndpoint, authToken, agentId]);
+    const interrupt = useCallback(() => {
+        const ws = wsRef.current;
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ action: 'interrupt' }));
+        }
+    }, []);
+    return { data, interrupt };
 }

package/lib/hooks/useSkills.d.ts

@@ -1,13 +1,31 @@
-import type { SkillsResponse } from '../types/skills';
+import type { SkillInfo } from '../types/skills';
 /**
- * Hook to fetch available skills from backend.
+ * Derive the list of skills from the WS-pushed `codemodeStatus`.
+ *
+ * The server-side SkillsArea pushes per-skill status (`available`,
+ * `enabled`, `loaded`) via the monitoring WebSocket inside the
+ * `codemodeStatus.skills` array.  This hook reads from the Zustand
+ * store — no REST call is made.
  */
-export declare function useSkills(enabled: boolean, baseEndpoint?: string, authToken?: string): import("@tanstack/query-core").QueryObserverRefetchErrorResult<SkillsResponse, Error> | import("@tanstack/query-core").QueryObserverSuccessResult<SkillsResponse, Error> | import("@tanstack/query-core").QueryObserverLoadingErrorResult<SkillsResponse, Error> | import("@tanstack/query-core").QueryObserverPendingResult<SkillsResponse, Error> | import("@tanstack/query-core").QueryObserverPlaceholderResult<SkillsResponse, Error> | {
-    data: undefined;
+export declare function useSkills(_enabled: boolean, _baseEndpoint?: string, _authToken?: string): {
+    data: {
+        skills: SkillInfo[];
+        total: number;
+    } | undefined;
     isLoading: boolean;
     isError: boolean;
     error: null;
     refetch: () => Promise<{
-        data: undefined;
+        data: {
+            skills: SkillInfo[];
+            total: number;
+        } | undefined;
     }>;
 };
+export declare function useSkillActions(agentId?: string): {
+    enableSkill: (skillId: string) => boolean;
+    disableSkill: (skillId: string) => boolean;
+    approveSkill: (skillId: string) => boolean;
+    unapproveSkill: (skillId: string) => boolean;
+};
+export { useAgentRuntimeLoadedSkills } from '../stores';