@datalayer/agent-runtimes 1.0.2 → 1.0.4

package/lib/hooks/useAgents.d.ts

@@ -1,13 +1,152 @@
-export type RequestOptions = {
-    signal?: AbortSignal;
-    baseUrl?: string;
+import type { IRuntimeOptions } from '@datalayer/core/lib/stateful/runtimes/apis';
+import type { AgentConfig } from '../types/config';
+import type { AgentConnection } from '../types/connection';
+import type { AgentStatus, AgentRuntimeData } from '../types/agents';
+import type { CreateAgentRuntimeRequest, AgentLifecycleState, CreateRuntimeApiResponse } from '../types/agents-lifecycle';
+import { ServiceManager } from '@jupyterlab/services/lib/manager';
+/**
+ * Options for the useAgents hook.
+ */
+export interface UseAgentOptions {
+    /** Agent spec ID — when provided, enables full lifecycle management (launch, pause, resume, terminate) */
+    agentSpecId?: string;
+    /** Agent configuration */
+    agentConfig?: AgentConfig;
+    /** Auto-create agent when runtime connects (default: true) */
+    autoCreateAgent?: boolean;
+    /** Auto-start runtime on mount (default: false) */
+    autoStart?: boolean;
+    /** Full agent spec object (persisted with checkpoints) */
+    agentSpec?: Record<string, any>;
+}
+/**
+ * Return type for the useAgents hook.
+ */
+export interface UseAgentReturn {
+    /** Current runtime connection (null if not connected) */
+    runtime: AgentConnection | null;
+    /** Combined agent status */
+    status: AgentStatus;
+    /** Whether the runtime is launching */
+    isLaunching: boolean;
+    /** Launch a new runtime */
+    launchRuntime: (options?: IRuntimeOptions) => Promise<AgentConnection>;
+    /** Connect to an existing runtime */
+    connectToRuntime: (options: {
+        podName: string;
+        environmentName: string;
+        serviceManager?: ServiceManager.IManager;
+        jupyterBaseUrl?: string;
+        kernelId?: string;
+    }) => void;
+    /** Disconnect from the runtime */
+    disconnect: () => void;
+    /** Agent endpoint URL (derived from runtime connection) */
+    endpoint: string | null;
+    /** ServiceManager for the runtime */
+    serviceManager: ServiceManager.IManager | null;
+    /** Create an agent on the runtime */
+    createAgent: (config?: AgentConfig) => Promise<Pick<AgentConnection, 'agentId' | 'endpoint' | 'isReady'>>;
+    /** Whether agent creation is currently in progress */
+    isCreating: boolean;
+    /** Whether everything is ready (runtime + agent) */
+    isReady: boolean;
+    /** Error if any */
+    error: string | null;
+}
+/** Default query options for all agent runtime queries. */
+export declare const AGENT_QUERY_OPTIONS: {
+    staleTime: number;
+    gcTime: number;
 };
-export type RoomType = 'notebook_persist' | 'notebook_memory' | 'doc_memory';
-export declare const useAIAgents: (baseUrlOverride?: string) => {
-    createAIAgent: (documentId: string, documentType: RoomType, ingress?: string, token?: string, kernelId?: string, { signal, baseUrl }?: RequestOptions) => Promise<any>;
-    getAIAgents: ({ signal, baseUrl, }?: RequestOptions) => Promise<any>;
-    deleteAIAgent: (documentId: string, { signal, baseUrl }?: RequestOptions) => Promise<any>;
-    getAIAgent: (documentId: string, { signal, baseUrl }?: RequestOptions) => Promise<any>;
-    patchAIAgent: (documentId: string, ingress?: string, token?: string, kernelId?: string, { signal, baseUrl }?: RequestOptions) => Promise<any>;
+/** Query keys for agent runtimes and checkpoints. */
+export declare const agentQueryKeys: {
+    readonly agentRuntimes: {
+        readonly all: () => readonly ["agentRuntimes"];
+        readonly lists: () => readonly ["agentRuntimes", "list"];
+        readonly details: () => readonly ["agentRuntimes", "detail"];
+        readonly detail: (podName: string) => readonly ["agentRuntimes", "detail", string];
+    };
+    readonly checkpoints: {
+        readonly all: () => readonly ["checkpoints"];
+        readonly lists: () => readonly ["checkpoints", "list"];
+    };
 };
-export default useAIAgents;
+/**
+ * Hook for managing agent runtimes.
+ *
+ * Works in two modes:
+ * - **Connect** (no `agentSpecId`): connect to an existing runtime and auto-create agent
+ * - **Lifecycle** (with `agentSpecId`): full lifecycle — launch, pause, resume, terminate
+ *
+ * @param options - Configuration options
+ * @returns Complete agent state and controls
+ *
+ * @example
+ * ```tsx
+ * // Connect mode — attach to an existing runtime
+ * const { isReady, endpoint, connectToRuntime } = useAgents({
+ *   autoCreateAgent: true,
+ *   agentConfig: { model: 'bedrock:us.anthropic.claude-3-5-haiku-20241022-v1:0' },
+ * });
+ *
+ * // Lifecycle mode — full lifecycle with agentSpecId
+ * const { isReady, endpoint, launchRuntime } = useAgents({
+ *   agentSpecId: 'my-agent-spec',
+ *   autoStart: true,
+ *   agentConfig: { name: 'my-agent', transport: 'ag-ui' },
+ * });
+ * ```
+ */
+export declare function useAgents(options?: UseAgentOptions): UseAgentReturn;
+/**
+ * Hook to fetch user's agent runtimes (running agent instances).
+ *
+ * The backend returns active runtimes from the operator **plus** paused
+ * runtimes synthesised from Solr checkpoint records (with ``status="paused"``).
+ */
+export declare function useAgentRuntimes(): import("@tanstack/react-query").UseQueryResult<AgentRuntimeData[], Error>;
+/**
+ * Hook to fetch a single agent runtime by pod name.
+ */
+export declare function useAgentRuntimeByPodName(podName: string | undefined): import("@tanstack/react-query").UseQueryResult<AgentRuntimeData, Error>;
+/**
+ * Hook to create a new agent runtime.
+ */
+export declare function useCreateAgentRuntime(): import("@tanstack/react-query").UseMutationResult<any, Error, CreateAgentRuntimeRequest, unknown>;
+/**
+ * Hook to delete an agent runtime.
+ */
+export declare function useDeleteAgentRuntime(): import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
+/**
+ * Hook to refresh agent runtimes list.
+ */
+export declare function useRefreshAgentRuntimes(): () => void;
+export declare const getAgentLifecycleKey: (runtimeKey: string) => string;
+export declare const useAgentLifecycleStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<AgentLifecycleState>, "persist"> & {
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<AgentLifecycleState, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: AgentLifecycleState) => void) => () => void;
+        onFinishHydration: (fn: (state: AgentLifecycleState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<AgentLifecycleState, unknown>>;
+    };
+}>;
+export interface UseAgentsRuntimesReturn {
+    runtimes: AgentRuntimeData[];
+    isRuntimesLoading: boolean;
+    isRuntimesError: boolean;
+    runtimesError: unknown;
+    refetchRuntimes: () => Promise<{
+        data?: AgentRuntimeData[];
+    }>;
+    refreshRuntimes: () => void;
+    deleteRuntimeByPod: (podName: string) => Promise<unknown>;
+    createRuntime: (data: CreateAgentRuntimeRequest) => Promise<CreateRuntimeApiResponse>;
+}
+/**
+ * Consolidated runtime list and mutations.
+ */
+export declare function useAgentsRuntimes(): UseAgentsRuntimesReturn;