@datalayer/core 1.0.1 → 1.0.3

package/lib/components/avatars/BoringAvatar.js

@@ -7,23 +7,24 @@ import BoringAvatars from 'boring-avatars';
 // export const getRandomBoringAvatarVariant = () => VARIANTS[Math.floor(Math.random() * VARIANTS.length)] as VariantType;
 const getRandomBoringAvatarVariant = () => 'bauhaus';
 const RANDOM_BORING_AVATOR_VARIANT = getRandomBoringAvatarVariant();
-export const BoringAvatar = ({ displayName = '', variant, size = 40, square = false, style, }) => {
+const DEFAULT_COLORS = [
+    '#000000',
+    '#146A7C',
+    '#16A085',
+    '#1ABC9C',
+    '#2ECC71',
+    '#59595C',
+    '#92A1C6',
+    '#C20D90',
+    '#C271B4',
+    '#F0AB3D',
+];
+export const BoringAvatar = ({ displayName = '', variant, size = 40, square = false, style, colors, }) => {
     const resolvedVariant = variant ?? RANDOM_BORING_AVATOR_VARIANT;
     const safeName = String(displayName ?? '');
+    const resolvedColors = colors ?? DEFAULT_COLORS;
     try {
-        return (_jsx("span", { style: { ...(style || {}) }, children: _jsx(BoringAvatars, { size: size, name: safeName, variant: resolvedVariant, square: square, colors: [
-                    '#000000',
-                    '#146A7C',
-                    '#16A085',
-                    '#1ABC9C',
-                    '#2ECC71',
-                    '#59595C',
-                    '#92A1C6',
-                    '#C20D90',
-                    '#C271B4',
-                    '#F0AB3D',
-                    //      '#FFFFFF',
-                ] }) }));
+        return (_jsx("span", { style: { ...(style || {}) }, children: _jsx(BoringAvatars, { size: size, name: safeName, variant: resolvedVariant, square: square, colors: resolvedColors }) }));
     }
     catch (error) {
         console.error('BoringAvatar error:', error);

package/lib/components/avatars/BoringAvatar.stories.d.ts

@@ -1,12 +1,13 @@
 import type { StoryObj } from '@storybook/react-vite';
 declare const meta: {
     title: string;
-    component: ({ displayName, variant, size, square, style, }: {
+    component: ({ displayName, variant, size, square, style, colors, }: {
         displayName?: string;
         variant?: "marble" | "beam" | "pixel" | "sunset" | "ring" | "bauhaus" | undefined;
         size?: number;
         square?: boolean;
         style?: object;
+        colors?: string[];
     }) => import("react/jsx-runtime").JSX.Element;
     tags: string[];
     parameters: {

package/lib/components/storage/ContentsBrowser.d.ts

@@ -1,3 +1,4 @@
+import { type ReactNode } from 'react';
 import { DocumentRegistry } from '@jupyterlab/docregistry';
 import { Contents } from '@jupyterlab/services';
 /**
@@ -24,6 +25,11 @@ export interface IContentsBrowserProps {
      * Document registry.
      */
     documentRegistry?: DocumentRegistry;
+    /**
+     * Optional title for the browser heading.
+     * Defaults to "Contents Browser".
+     */
+    title?: ReactNode;
 }
 /**
  * Storage browser component.

package/lib/components/storage/ContentsBrowser.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useState, } from 'react';
 import { PathExt } from '@jupyterlab/coreutils';
 import { PromiseDelegate } from '@lumino/coreutils';
 import { ActionList, ActionMenu, Heading, IconButton, Spinner, TreeView, } from '@primer/react';
@@ -26,7 +26,11 @@ export const CHUNK_SIZE = 1024 * 1024;
  * Storage browser component.
  */
 export function ContentsBrowser(props) {
-    const { contents, localContents, documentRegistry } = props;
+    const { contents, localContents, documentRegistry, title = (_jsx(Heading, { as: "h4", sx: {
+            fontSize: 'var(--text-title-size-small)',
+            lineHeight: 'var(--text-title-lineHeight-medium)',
+            fontWeight: 'var(--text-title-weight-medium)',
+        }, children: "Contents Browser" })), } = props;
     const isMounted = useIsMounted();
     const { trackAsyncTask } = useToast();
     const [children, setChildren] = useState(null);
@@ -205,12 +209,7 @@ export function ContentsBrowser(props) {
     const onSelect = useCallback((item, refresh) => {
         setSelectedItem(item.path === selectedItem?.path ? null : { ...item, refresh });
     }, [selectedItem]);
-    return (_jsxs(Box, { sx: { display: 'grid', gridTemplateAreas: `"header" "content"` }, children: [_jsxs(Box, { sx: { gridArea: 'header', display: 'flex', alignItems: 'center' }, children: [_jsx(Heading, { as: "h4", sx: {
-                            fontSize: 'var(--text-title-size-small)',
-                            lineHeight: 'var(--text-title-lineHeight-medium)',
-                            fontWeight: 'var(--text-title-weight-medium)',
-                            flex: '1 1 auto',
-                        }, children: "Contents Browser" }), _jsxs(Box, { children: [_jsx(IconButton, { variant: "invisible", "aria-label": 'Refresh contents browser.', title: 'Refresh contents browser.', icon: CounterClockWiseIcon, onClick: refresh }), _jsx(UploadIconButton, { label: 'Upload a file', multiple: true, upload: upload })] })] }), isLoading ? (_jsx(Box, { sx: {
+    return (_jsxs(Box, { sx: { display: 'grid', gridTemplateAreas: `"header" "content"` }, children: [_jsxs(Box, { sx: { gridArea: 'header', display: 'flex', alignItems: 'center' }, children: [_jsx(Box, { sx: { flex: '1 1 auto' }, children: title }), _jsxs(Box, { children: [_jsx(IconButton, { variant: "invisible", "aria-label": 'Refresh contents browser.', title: 'Refresh contents browser.', icon: CounterClockWiseIcon, onClick: refresh }), _jsx(UploadIconButton, { label: 'Upload a file', multiple: true, upload: upload })] })] }), isLoading ? (_jsx(Box, { sx: {
                     gridArea: 'content',
                     display: 'flex',
                     alignItems: 'center',

package/lib/config/Configuration.d.ts

@@ -71,6 +71,10 @@ export type IDatalayerCoreConfig = {
      * MCP Servers API URL.
      */
     mcpserversRunUrl: string;
+    /**
+     * OTEL (OpenTelemetry) API URL.
+     */
+    otelRunUrl: string;
     /**
      * Growth API URL.
      */

package/lib/hooks/index.d.ts

@@ -23,5 +23,7 @@ export * from './useScreencapture';
 export * from './useToast';
 export * from './useUpload';
 export * from './useUser';
+export * from './useProjects';
+export * from './useProjectStore';
 export * from './useVisibilityObserver';
 export * from './useWindowSize';

package/lib/hooks/index.js

@@ -28,5 +28,7 @@ export * from './useScreencapture';
 export * from './useToast';
 export * from './useUpload';
 export * from './useUser';
+export * from './useProjects';
+export * from './useProjectStore';
 export * from './useVisibilityObserver';
 export * from './useWindowSize';

package/lib/hooks/useCache.d.ts

@@ -36,7 +36,6 @@
  */
 import { UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
 import { IAnyOrganization, IAnySpace, IAssignment, ICell, IContact, ICourse, IDataset, IDatasource, IDocument, IEnvironment, IExercise, IIAMToken, ILesson, INotebook, IOrganization, IPage, ISchool, ISecret, ITeam, IUser, IUserOnboarding, IUserSettings } from '../models';
-import type { AgentSpaceData, CreateAgentSpaceRequest, UpdateAgentSpaceRequest } from '../api/spacer/agentSpaces';
 export type CacheProps = {
     loginRoute?: string;
 };
@@ -46,6 +45,18 @@ export type ISearchOpts = {
     max: number;
     public: boolean;
 };
+/** Request payload for creating a new agent runtime. */
+export type CreateAgentRuntimeRequest = {
+    environmentName?: string;
+    givenName?: string;
+    creditsLimit?: number;
+    type?: string;
+    /** 'none', 'notebook', or 'document' */
+    editorVariant?: string;
+    enableCodemode?: boolean;
+    /** ID of the agent spec used to create this runtime */
+    agentSpecId?: string;
+};
 /**
  * Centralized query key factories for all entities
  * Following TanStack Query best practices for key structure
@@ -213,13 +224,6 @@ export declare const queryKeys: {
         readonly bySpace: (spaceId: string) => readonly ["items", "space", string];
         readonly search: (opts: ISearchOpts) => readonly ["items", "search", ISearchOpts];
     };
-    readonly agentSpaces: {
-        readonly all: () => readonly ["agentSpaces"];
-        readonly lists: () => readonly ["agentSpaces", "list"];
-        readonly details: () => readonly ["agentSpaces", "detail"];
-        readonly detail: (id: string) => readonly ["agentSpaces", "detail", string];
-        readonly public: () => readonly ["agentSpaces", "public"];
-    };
     readonly agentRuntimes: {
         readonly all: () => readonly ["agentRuntimes"];
         readonly lists: () => readonly ["agentRuntimes", "list"];
@@ -488,20 +492,6 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
         spaceHandle?: string;
     }, unknown>;
     useExportSpace: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
-    useAgentSpace: (uid: string | undefined) => import("@tanstack/react-query").UseQueryResult<AgentSpaceData, Error>;
-    useAgentSpaces: () => import("@tanstack/react-query").UseQueryResult<AgentSpaceData[], Error>;
-    usePublicAgentSpaces: () => import("@tanstack/react-query").UseQueryResult<AgentSpaceData[], Error>;
-    useCreateAgentSpace: () => import("@tanstack/react-query").UseMutationResult<any, Error, CreateAgentSpaceRequest, unknown>;
-    useUpdateAgentSpace: () => import("@tanstack/react-query").UseMutationResult<any, Error, {
-        uid: string;
-        data: UpdateAgentSpaceRequest;
-    }, unknown>;
-    useDeleteAgentSpace: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
-    useMakeAgentSpacePublic: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
-    useMakeAgentSpacePrivate: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
-    useRefreshAgentSpace: () => (uid: string) => void;
-    useRefreshAgentSpaces: () => () => void;
-    useRefreshPublicAgentSpaces: () => () => void;
     useAgentRuntime: (podName: string | undefined) => import("@tanstack/react-query").UseQueryResult<{
         status: "running" | "paused" | "starting" | "terminated" | "archived";
         name: string;
@@ -520,7 +510,7 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
         burning_rate?: number;
         ingress?: string;
         token?: string;
-        agentSpec?: AgentSpaceData["agentSpec"];
+        agentSpec?: any;
     }, Error>;
     useAgentRuntimes: () => import("@tanstack/react-query").UseQueryResult<{
         status: "running" | "paused" | "starting" | "terminated" | "archived";
@@ -540,17 +530,9 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
         burning_rate?: number;
         ingress?: string;
         token?: string;
-        agentSpec?: AgentSpaceData["agentSpec"];
+        agentSpec?: any;
     }[], Error>;
-    useCreateAgentRuntime: () => import("@tanstack/react-query").UseMutationResult<any, Error, {
-        environmentName?: string;
-        givenName?: string;
-        creditsLimit?: number;
-        type?: string;
-        editorVariant?: string;
-        enableCodemode?: boolean;
-        agentSpecId?: string;
-    }, unknown>;
+    useCreateAgentRuntime: () => import("@tanstack/react-query").UseMutationResult<any, Error, CreateAgentRuntimeRequest, unknown>;
     useDeleteAgentRuntime: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
     useRefreshAgentRuntimes: () => () => void;
     useCourse: (courseId: string) => import("@tanstack/react-query").UseQueryResult<ICourse | undefined, Error>;
@@ -755,6 +737,7 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
     useTokens: () => import("@tanstack/react-query").UseQueryResult<any, Error>;
     useCreateToken: () => import("@tanstack/react-query").UseMutationResult<any, Error, Omit<IIAMToken, "id" | "value">, unknown>;
     useUpdateToken: () => import("@tanstack/react-query").UseMutationResult<any, Error, IIAMToken, unknown>;
+    useDeleteToken: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
     useInvite: (token: string) => import("@tanstack/react-query").UseQueryResult<import("..").IInvite | undefined, Error>;
     useInvitesByUser: (accountId: string) => import("@tanstack/react-query").UseQueryResult<any, Error>;
     usePutInvite: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
@@ -1036,13 +1019,6 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
             readonly bySpace: (spaceId: string) => readonly ["items", "space", string];
             readonly search: (opts: ISearchOpts) => readonly ["items", "search", ISearchOpts];
         };
-        readonly agentSpaces: {
-            readonly all: () => readonly ["agentSpaces"];
-            readonly lists: () => readonly ["agentSpaces", "list"];
-            readonly details: () => readonly ["agentSpaces", "detail"];
-            readonly detail: (id: string) => readonly ["agentSpaces", "detail", string];
-            readonly public: () => readonly ["agentSpaces", "public"];
-        };
         readonly agentRuntimes: {
             readonly all: () => readonly ["agentRuntimes"];
             readonly lists: () => readonly ["agentRuntimes", "list"];

package/lib/hooks/useCache.js

@@ -272,14 +272,6 @@ export const queryKeys = {
         bySpace: (spaceId) => [...queryKeys.items.all(), 'space', spaceId],
         search: (opts) => [...queryKeys.items.all(), 'search', opts],
     },
-    // Agent Spaces
-    agentSpaces: {
-        all: () => ['agentSpaces'],
-        lists: () => [...queryKeys.agentSpaces.all(), 'list'],
-        details: () => [...queryKeys.agentSpaces.all(), 'detail'],
-        detail: (id) => [...queryKeys.agentSpaces.details(), id],
-        public: () => [...queryKeys.agentSpaces.all(), 'public'],
-    },
     // Agent Runtimes (runtimes with ai-agents environment)
     agentRuntimes: {
         all: () => ['agentRuntimes'],
@@ -1370,219 +1362,6 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             },
         });
     };
-    // ============================================================================
-    // Agent Spaces Hooks
-    // ============================================================================
-    /**
-     * Get agent space by ID
-     */
-    const useAgentSpace = (uid) => {
-        return useQuery({
-            queryKey: queryKeys.agentSpaces.detail(uid || ''),
-            queryFn: async () => {
-                const resp = await requestDatalayer({
-                    url: `${configuration.spacerRunUrl}/api/spacer/v1/agent-spaces/${uid}`,
-                    method: 'GET',
-                });
-                if (resp.success && resp.agentSpace) {
-                    return resp.agentSpace;
-                }
-                throw new Error(resp.message || 'Failed to fetch agent space');
-            },
-            ...DEFAULT_QUERY_OPTIONS,
-            enabled: !!uid,
-        });
-    };
-    /**
-     * List user's agent spaces
-     */
-    const useAgentSpaces = () => {
-        return useQuery({
-            queryKey: queryKeys.agentSpaces.lists(),
-            queryFn: async () => {
-                const resp = await requestDatalayer({
-                    url: `${configuration.spacerRunUrl}/api/spacer/v1/agent-spaces`,
-                    method: 'GET',
-                });
-                if (resp.success && resp.agentSpaces) {
-                    const agentSpaces = resp.agentSpaces;
-                    // Set detail cache for each agent space
-                    agentSpaces.forEach((agentSpace) => {
-                        queryClient.setQueryData(queryKeys.agentSpaces.detail(agentSpace.id), agentSpace);
-                    });
-                    return agentSpaces;
-                }
-                return [];
-            },
-            ...DEFAULT_QUERY_OPTIONS,
-            enabled: !!user,
-        });
-    };
-    /**
-     * List public agent spaces (Library)
-     */
-    const usePublicAgentSpaces = () => {
-        return useQuery({
-            queryKey: queryKeys.agentSpaces.public(),
-            queryFn: async () => {
-                const resp = await requestDatalayer({
-                    url: `${configuration.spacerRunUrl}/api/spacer/v1/agent-spaces/public`,
-                    method: 'GET',
-                });
-                if (resp.success && resp.agentSpaces) {
-                    return resp.agentSpaces;
-                }
-                return [];
-            },
-            ...DEFAULT_QUERY_OPTIONS,
-        });
-    };
-    /**
-     * Create agent space
-     */
-    const useCreateAgentSpace = () => {
-        return useMutation({
-            mutationFn: async (data) => {
-                return requestDatalayer({
-                    url: `${configuration.spacerRunUrl}/api/spacer/v1/agent-spaces`,
-                    method: 'POST',
-                    body: data,
-                });
-            },
-            onSuccess: resp => {
-                if (resp.success && resp.agentSpace) {
-                    const agentSpace = resp.agentSpace;
-                    // Set detail cache
-                    queryClient.setQueryData(queryKeys.agentSpaces.detail(agentSpace.id), agentSpace);
-                    // Invalidate all agent space queries
-                    queryClient.invalidateQueries({
-                        queryKey: queryKeys.agentSpaces.all(),
-                    });
-                }
-            },
-        });
-    };
-    /**
-     * Update agent space
-     */
-    const useUpdateAgentSpace = () => {
-        return useMutation({
-            mutationFn: async ({ uid, data, }) => {
-                return requestDatalayer({
-                    url: `${configuration.spacerRunUrl}/api/spacer/v1/agent-spaces/${uid}`,
-                    method: 'PUT',
-                    body: data,
-                });
-            },
-            onSuccess: (resp, { uid }) => {
-                if (resp.success) {
-                    // Invalidate detail cache
-                    queryClient.invalidateQueries({
-                        queryKey: queryKeys.agentSpaces.detail(uid),
-                    });
-                    // Invalidate all agent space queries
-                    queryClient.invalidateQueries({
-                        queryKey: queryKeys.agentSpaces.all(),
-                    });
-                }
-            },
-        });
-    };
-    /**
-     * Delete agent space
-     */
-    const useDeleteAgentSpace = () => {
-        return useMutation({
-            mutationFn: async (uid) => {
-                return requestDatalayer({
-                    url: `${configuration.spacerRunUrl}/api/spacer/v1/agent-spaces/${uid}`,
-                    method: 'DELETE',
-                });
-            },
-            onSuccess: () => {
-                // Invalidate all agent space queries
-                queryClient.invalidateQueries({
-                    queryKey: queryKeys.agentSpaces.all(),
-                });
-            },
-        });
-    };
-    /**
-     * Make agent space public
-     */
-    const useMakeAgentSpacePublic = () => {
-        return useMutation({
-            mutationFn: async (uid) => {
-                return requestDatalayer({
-                    url: `${configuration.spacerRunUrl}/api/spacer/v1/agent-spaces/${uid}/public`,
-                    method: 'POST',
-                });
-            },
-            onSuccess: (resp, uid) => {
-                if (resp.success) {
-                    queryClient.invalidateQueries({
-                        queryKey: queryKeys.agentSpaces.detail(uid),
-                    });
-                    queryClient.invalidateQueries({
-                        queryKey: queryKeys.agentSpaces.all(),
-                    });
-                }
-            },
-        });
-    };
-    /**
-     * Make agent space private
-     */
-    const useMakeAgentSpacePrivate = () => {
-        return useMutation({
-            mutationFn: async (uid) => {
-                return requestDatalayer({
-                    url: `${configuration.spacerRunUrl}/api/spacer/v1/agent-spaces/${uid}/private`,
-                    method: 'POST',
-                });
-            },
-            onSuccess: (resp, uid) => {
-                if (resp.success) {
-                    queryClient.invalidateQueries({
-                        queryKey: queryKeys.agentSpaces.detail(uid),
-                    });
-                    queryClient.invalidateQueries({
-                        queryKey: queryKeys.agentSpaces.all(),
-                    });
-                }
-            },
-        });
-    };
-    /**
-     * Refresh agent space data
-     */
-    const useRefreshAgentSpace = () => {
-        return (uid) => {
-            queryClient.invalidateQueries({
-                queryKey: queryKeys.agentSpaces.detail(uid),
-            });
-        };
-    };
-    /**
-     * Refresh agent spaces list
-     */
-    const useRefreshAgentSpaces = () => {
-        return () => {
-            queryClient.invalidateQueries({
-                queryKey: queryKeys.agentSpaces.all(),
-            });
-        };
-    };
-    /**
-     * Refresh public agent spaces list
-     */
-    const useRefreshPublicAgentSpaces = () => {
-        return () => {
-            queryClient.invalidateQueries({
-                queryKey: queryKeys.agentSpaces.public(),
-            });
-        };
-    };
     /**
      * List agent runtimes (runtimes with ai-agents-env environment)
      */
@@ -1694,6 +1473,14 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             enabled: !!podName,
         });
     };
+    /**
+     * Create a new agent runtime.
+     *
+     * Note on phase/status mapping:
+     * Newly created runtimes are immediately active (the operator assigns a pod from the pool).
+     * The response won't have a 'phase' field, so we default to 'running'.
+     * See useAgentRuntimes JSDoc for full explanation.
+     */
     const useCreateAgentRuntime = () => {
         return useMutation({
             mutationFn: async (data) => {
@@ -2718,6 +2505,25 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             },
         });
     };
+    /**
+     * Delete token by ID
+     */
+    const useDeleteToken = () => {
+        return useMutation({
+            mutationFn: async (tokenId) => {
+                return requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/tokens/${tokenId}`,
+                    method: 'DELETE',
+                });
+            },
+            onSuccess: (_, tokenId) => {
+                queryClient.removeQueries({
+                    queryKey: queryKeys.tokens.detail(tokenId),
+                });
+                queryClient.invalidateQueries({ queryKey: queryKeys.tokens.all() });
+            },
+        });
+    };
     /**
      * Get contact by handle
      */
@@ -6538,18 +6344,6 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useRefreshUserSpace,
         useRefreshLayout,
         useExportSpace,
-        // Agent Spaces
-        useAgentSpace,
-        useAgentSpaces,
-        usePublicAgentSpaces,
-        useCreateAgentSpace,
-        useUpdateAgentSpace,
-        useDeleteAgentSpace,
-        useMakeAgentSpacePublic,
-        useMakeAgentSpacePrivate,
-        useRefreshAgentSpace,
-        useRefreshAgentSpaces,
-        useRefreshPublicAgentSpaces,
         // Agent Runtimes (runtimes with ai-agents environment)
         useAgentRuntime,
         useAgentRuntimes,
@@ -6667,6 +6461,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useTokens,
         useCreateToken,
         useUpdateToken,
+        useDeleteToken,
         // Invites
         useInvite,
         useInvitesByUser,

package/lib/hooks/useProjectStore.d.ts

@@ -0,0 +1,58 @@
+import type { Session } from '@jupyterlab/services';
+import type { IKernelConnection } from '@jupyterlab/services/lib/kernel/kernel';
+/**
+ * Per-project runtime state tracked in memory.
+ *
+ * This is **not** persisted — it represents live runtime objects
+ * (kernel connections, sessions) that only exist while the project
+ * view is mounted.
+ */
+export type ProjectRuntimeEntry = {
+    /** The Jupyter session connection (notebook ↔ kernel bridge). */
+    sessionConnection?: Session.ISessionConnection;
+    /** The assigned agent pod name (mirrors project.attachedAgentPodName). */
+    agentPodName?: string;
+    /** Display name of the assigned agent. */
+    agentName?: string;
+    /** Agent runtime status (running, starting, terminated, etc.). */
+    agentStatus?: string;
+    /** The agent spec ID used to create the runtime. */
+    agentSpecId?: string;
+};
+export type ProjectStoreState = {
+    /** Map of projectId → runtime entry. */
+    projects: Record<string, ProjectRuntimeEntry>;
+    /** The currently active/viewed project ID (for sidebar highlighting). */
+    currentProjectId: string | undefined;
+    /** Set the currently active project (call on mount, clear on unmount). */
+    setCurrentProjectId: (projectId: string | undefined) => void;
+    /** Set or update the session connection for a project. */
+    setSessionConnection: (projectId: string, sessionConnection: Session.ISessionConnection | undefined) => void;
+    /** Set the assigned agent info for a project. */
+    setAgent: (projectId: string, agentPodName: string | undefined, agentName?: string, agentStatus?: string, agentSpecId?: string) => void;
+    /** Remove all runtime state for a project (e.g. on unmount). */
+    clearProject: (projectId: string) => void;
+    /** Get the kernel connection for a project, or undefined. */
+    getKernel: (projectId: string) => IKernelConnection | null | undefined;
+    /** Get the full entry for a project. */
+    getEntry: (projectId: string) => ProjectRuntimeEntry | undefined;
+};
+/**
+ * Zustand store for per-project runtime state (kernel connections, agents).
+ *
+ * Not persisted — the data is ephemeral and only valid while the project
+ * component is mounted and a kernel/agent is active.
+ *
+ * Usage:
+ * ```ts
+ * import { useProjectStore } from '@datalayer/core/lib/hooks';
+ *
+ * // In Project.tsx — store session when Notebook connects:
+ * const setSessionConnection = useProjectStore(s => s.setSessionConnection);
+ * <Notebook onSessionConnection={sc => setSessionConnection(projectId, sc)} />
+ *
+ * // Anywhere — read the kernel for a project:
+ * const kernel = useProjectStore(s => s.getKernel(projectId));
+ * ```
+ */
+export declare const useProjectStore: import("zustand").UseBoundStore<import("zustand").StoreApi<ProjectStoreState>>;

package/lib/hooks/useProjectStore.js

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { create } from 'zustand';
+/**
+ * Zustand store for per-project runtime state (kernel connections, agents).
+ *
+ * Not persisted — the data is ephemeral and only valid while the project
+ * component is mounted and a kernel/agent is active.
+ *
+ * Usage:
+ * ```ts
+ * import { useProjectStore } from '@datalayer/core/lib/hooks';
+ *
+ * // In Project.tsx — store session when Notebook connects:
+ * const setSessionConnection = useProjectStore(s => s.setSessionConnection);
+ * <Notebook onSessionConnection={sc => setSessionConnection(projectId, sc)} />
+ *
+ * // Anywhere — read the kernel for a project:
+ * const kernel = useProjectStore(s => s.getKernel(projectId));
+ * ```
+ */
+export const useProjectStore = create()((set, get) => ({
+    projects: {},
+    currentProjectId: undefined,
+    setCurrentProjectId: projectId => set({ currentProjectId: projectId }),
+    setSessionConnection: (projectId, sessionConnection) => set(state => ({
+        projects: {
+            ...state.projects,
+            [projectId]: {
+                ...state.projects[projectId],
+                sessionConnection,
+            },
+        },
+    })),
+    setAgent: (projectId, agentPodName, agentName, agentStatus, agentSpecId) => set(state => ({
+        projects: {
+            ...state.projects,
+            [projectId]: {
+                ...state.projects[projectId],
+                agentPodName,
+                agentName,
+                // When removing the agent, also clear the status.
+                // When setting, use provided status or preserve existing.
+                agentStatus: agentPodName !== undefined
+                    ? (agentStatus ?? state.projects[projectId]?.agentStatus)
+                    : undefined,
+                agentSpecId: agentPodName !== undefined
+                    ? (agentSpecId ?? state.projects[projectId]?.agentSpecId)
+                    : undefined,
+            },
+        },
+    })),
+    clearProject: projectId => set(state => {
+        const { [projectId]: _, ...rest } = state.projects;
+        return { projects: rest };
+    }),
+    getKernel: projectId => {
+        const entry = get().projects[projectId];
+        return entry?.sessionConnection?.kernel;
+    },
+    getEntry: projectId => get().projects[projectId],
+}));