@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/examples2/main.js

@@ -29,16 +29,36 @@ const resolveRuntimesUrl = (configured) => {
     }
     return candidate.replace(/\/$/, '');
 };
-const isProd1JupyterServerUrl = (value) => {
+/**
+ * Whether a URL names a Jupyter server on this machine.
+ *
+ * Asked this way round on purpose. The previous test was "is this prod1?",
+ * which took every host it did not recognise for a local one — so once the
+ * configured server moved to `r1`, Local mode accepted the cloud URL as its
+ * own and the browser dialled it from `localhost`, where CORS refused it.
+ *
+ * The set of remote hosts is open — `prod1`, `r1`, whatever a deployment adds
+ * next — while the set of local ones is not, so the closed set is the one
+ * worth enumerating.
+ */
+const isLocalJupyterServerUrl = (value) => {
     if (!value) {
         return false;
     }
+    let host;
     try {
-        return new URL(value).hostname === 'prod1.datalayer.run';
+        host = new URL(value).hostname.toLowerCase();
     }
     catch {
-        return value.includes('prod1.datalayer.run');
+        return /(^|\/\/)(localhost|127\.0\.0\.1|0\.0\.0\.0|\[?::1\]?)([:/]|$)/.test(value);
     }
+    return (host === 'localhost' ||
+        host === '127.0.0.1' ||
+        host === '0.0.0.0' ||
+        host === '::1' ||
+        host === '[::1]' ||
+        host.endsWith('.localhost') ||
+        host.endsWith('.local'));
 };
 const resolveLocalJupyterServerUrl = () => {
     const envLocalUrl = import.meta.env.VITE_JUPYTER_SERVER_URL?.trim();
@@ -46,7 +66,7 @@ const resolveLocalJupyterServerUrl = () => {
         return envLocalUrl.replace(/\/$/, '');
     }
     const configured = getJupyterServerUrl();
-    if (configured && !isProd1JupyterServerUrl(configured)) {
+    if (configured && isLocalJupyterServerUrl(configured)) {
         return configured;
     }
     return DEFAULT_LOCAL_JUPYTER_SERVER_URL;

package/lib/extensions/A2UIExtension.d.ts

@@ -60,6 +60,6 @@ export declare class A2UIExtensionImpl implements ActivityRendererExtension {
         activityType: string;
         data: unknown;
         message: ChatMessage;
-    }) => React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
+    }) => React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | null;
 }
 export type { A2UIExtensionNamespace };

package/lib/hooks/index.d.ts

@@ -17,7 +17,8 @@
  * - `useAgUi` - AG-UI protocol (Pydantic AI's native protocol)
  * - `useA2A` - A2A protocol (Agent-to-Agent with JSON-RPC)
  * - `useAcp` - ACP protocol (Agent Client Protocol via WebSocket)
- * - `useVercelAI` - Vercel AI SDK chat protocol
+ * - `useVercelAI` - Vercel AI SDK chat protocol, spoken to a runtime
+ * - `useBrowserAgent` - the loop itself, running in the page
  *
  * ## Datalayer-Specific Hooks
  * Hooks for Datalayer platform integration.
@@ -40,7 +41,8 @@ export { useFrontendTool, useBackendTool, useRegisteredTools, useTool, usePendin
  * ChatBase infrastructure hooks.
  */
 export { useConfig } from './useConfig';
-export { useSkills, useSkillActions, useAgentRuntimeLoadedSkills as useAgentLoadedSkills, } from './useSkills';
+export { useSkills, useSkillActions } from './useSkills';
+export { useAgentRuntimeLoadedSkills as useAgentLoadedSkills } from '../stores';
 export { useContextSnapshot } from './useContextSnapshot';
 export { useSandbox } from './useSandbox';
 /**
@@ -63,14 +65,15 @@ export * from './useAcp';
  * Use for direct Vercel AI communication without the chat component system.
  */
 export { useVercelAI } from './useVercelAI';
+export { useBrowserAgent, type UseBrowserAgentOptions, } from './useBrowserAgent';
 /**
  * Unified hook for managing agents — both ephemeral and durable.
  */
-export { useAgentRuntimes } from './useAgentRuntimes';
+export { useAgentRuntimes, type AgentRuntimeConnectionOptions, type AgentRuntimeVariant, type RuntimeCreationTarget, type UseAgentOptions, type UseAgentReturn, } from './useAgentRuntimes';
 /**
  * Runtime query and mutation hooks.
  */
-export { useAgentsRuntimes, useAgentRuntimesQuery, useAgentRuntimeByPodName, useCreateAgentRuntime, useDeleteAgentRuntime, useRefreshAgentRuntimes, agentQueryKeys, AGENT_QUERY_OPTIONS, useAgentLifecycleStore, getAgentLifecycleKey, markRuntimePodDeleted, clearRuntimePodDeleted, } from './useAgentRuntimes';
+export { useAgentsRuntimes, useAgentRuntimesQuery, useAgentRuntimeByName, useCreateAgentRuntime, useDeleteAgentRuntime, useRefreshAgentRuntimes, agentQueryKeys, AGENT_QUERY_OPTIONS, useAgentLifecycleStore, getAgentLifecycleKey, markRuntimeDeleted, clearRuntimeDeleted, } from './useAgentRuntimes';
 /**
  * Central registry of ServiceManagers connected to agent sandbox pods.
  */
@@ -90,7 +93,7 @@ export { useAgentsService, useNotebookAgents } from './useAgentsService';
 /**
  * Focused hooks split by responsibility.
  */
-export { useCheckpoints, useCheckpointsQuery, useRefreshCheckpoints, useDeletePausedAgentRuntime, useResumePausedAgentRuntime, usePauseAgent, useResumeAgent, useCheckpointAgent, useTerminateAgent, useAgentLifecycle, type CheckpointData, type PauseAgentParams, type ResumeAgentParams, type CheckpointAgentParams, type TerminateAgentParams, type AgentLifecycleOptions, type AgentLifecycleReturn, } from './useCheckpoints';
+export { useCheckpoints, useCheckpointsQuery, useRefreshCheckpoints, useResumePausedAgentRuntime, usePauseAgent, useResumeAgent, useCheckpointAgent, useTerminateAgent, useAgentLifecycle, type CheckpointData, type PauseAgentParams, type ResumeAgentParams, type CheckpointAgentParams, type TerminateAgentParams, type AgentLifecycleOptions, type AgentLifecycleReturn, } from './useCheckpoints';
 export { useToolApprovals, useToolApprovalsQuery, usePendingApprovalCount, useApproveToolRequest, useRejectToolRequest, } from './useToolApprovals';
 export { useNotifications, useFilteredNotifications, useUnreadNotificationCount, useMarkNotificationRead, useMarkAllNotificationsRead, useAllAgentEvents, useAgentEvents, useAgentEvent, useCreateAgentEvent, useUpdateAgentEvent, useDeleteAgentEvent, useMarkEventRead, useMarkEventUnread, } from './useNotifications';
 export { useAIAgentsWebSocket, type UseAIAgentsWebSocketOptions, type UseAIAgentsWebSocketResult, type AIAgentsWebSocketCloseInfo, type AIAgentsWebSocketConnectionState, } from './useAIAgentsWebSocket';

package/lib/hooks/index.js

@@ -21,7 +21,8 @@
  * - `useAgUi` - AG-UI protocol (Pydantic AI's native protocol)
  * - `useA2A` - A2A protocol (Agent-to-Agent with JSON-RPC)
  * - `useAcp` - ACP protocol (Agent Client Protocol via WebSocket)
- * - `useVercelAI` - Vercel AI SDK chat protocol
+ * - `useVercelAI` - Vercel AI SDK chat protocol, spoken to a runtime
+ * - `useBrowserAgent` - the loop itself, running in the page
  *
  * ## Datalayer-Specific Hooks
  * Hooks for Datalayer platform integration.
@@ -47,7 +48,18 @@ export { useFrontendTool, useBackendTool, useRegisteredTools, useTool, usePendin
  * ChatBase infrastructure hooks.
  */
 export { useConfig } from './useConfig';
-export { useSkills, useSkillActions, useAgentRuntimeLoadedSkills as useAgentLoadedSkills, } from './useSkills';
+export { useSkills, useSkillActions } from './useSkills';
+/*
+ * Straight from the store it lives in, not forwarded through `useSkills`.
+ *
+ * `useSkills` only re-exported it, so this barrel was the third hop of a
+ * chain — hooks → useSkills → stores → agentRuntimeStore. Webpack resolves a
+ * re-exported binding by following that chain through the built files, and it
+ * gave up here: "`useAgentRuntimeLoadedSkills` was not found in
+ * `./useSkills`", which is true of the source it reads even though every file
+ * in the chain is correct. One hop cannot be misread.
+ */
+export { useAgentRuntimeLoadedSkills as useAgentLoadedSkills } from '../stores';
 export { useContextSnapshot } from './useContextSnapshot';
 export { useSandbox } from './useSandbox';
 // =============================================================================
@@ -73,17 +85,20 @@ export * from './useAcp';
  * Use for direct Vercel AI communication without the chat component system.
  */
 export { useVercelAI } from './useVercelAI';
+// The browser harness. Same `useChat` helpers as `useVercelAI` — the branch is
+// one transport, so every chat component downstream is shared.
+export { useBrowserAgent, } from './useBrowserAgent';
 // =============================================================================
 // Datalayer Platform Hooks
 // =============================================================================
 /**
  * Unified hook for managing agents — both ephemeral and durable.
  */
-export { useAgentRuntimes } from './useAgentRuntimes';
+export { useAgentRuntimes, } from './useAgentRuntimes';
 /**
  * Runtime query and mutation hooks.
  */
-export { useAgentsRuntimes, useAgentRuntimesQuery, useAgentRuntimeByPodName, useCreateAgentRuntime, useDeleteAgentRuntime, useRefreshAgentRuntimes, agentQueryKeys, AGENT_QUERY_OPTIONS, useAgentLifecycleStore, getAgentLifecycleKey, markRuntimePodDeleted, clearRuntimePodDeleted, } from './useAgentRuntimes';
+export { useAgentsRuntimes, useAgentRuntimesQuery, useAgentRuntimeByName, useCreateAgentRuntime, useDeleteAgentRuntime, useRefreshAgentRuntimes, agentQueryKeys, AGENT_QUERY_OPTIONS, useAgentLifecycleStore, getAgentLifecycleKey, markRuntimeDeleted, clearRuntimeDeleted, } from './useAgentRuntimes';
 /**
  * Central registry of ServiceManagers connected to agent sandbox pods.
  */
@@ -103,7 +118,7 @@ export { useAgentsService, useNotebookAgents } from './useAgentsService';
 /**
  * Focused hooks split by responsibility.
  */
-export { useCheckpoints, useCheckpointsQuery, useRefreshCheckpoints, useDeletePausedAgentRuntime, useResumePausedAgentRuntime, usePauseAgent, useResumeAgent, useCheckpointAgent, useTerminateAgent, useAgentLifecycle, } from './useCheckpoints';
+export { useCheckpoints, useCheckpointsQuery, useRefreshCheckpoints, useResumePausedAgentRuntime, usePauseAgent, useResumeAgent, useCheckpointAgent, useTerminateAgent, useAgentLifecycle, } from './useCheckpoints';
 export { useToolApprovals, useToolApprovalsQuery, usePendingApprovalCount, useApproveToolRequest, useRejectToolRequest, } from './useToolApprovals';
 export { useNotifications, useFilteredNotifications, useUnreadNotificationCount, useMarkNotificationRead, useMarkAllNotificationsRead, useAllAgentEvents, useAgentEvents, useAgentEvent, useCreateAgentEvent, useUpdateAgentEvent, useDeleteAgentEvent, useMarkEventRead, useMarkEventUnread, } from './useNotifications';
 export { useAIAgentsWebSocket, } from './useAIAgentsWebSocket';

package/lib/hooks/useAgentRuntimes.d.ts

@@ -4,7 +4,16 @@ 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';
-export type RuntimeCreationTarget = 'backend-services' | 'local-agent-runtimes';
+import { type AgentRuntimeVariant, type RuntimeCreationTarget } from '../runtimes/variants';
+export type { AgentRuntimeVariant, RuntimeCreationTarget };
+/** Existing runtime connection used by connect-mode consumers. */
+export interface AgentRuntimeConnectionOptions {
+    runtimeName: string;
+    environmentName: string;
+    serviceManager?: ServiceManager.IManager;
+    jupyterBaseUrl?: string;
+    kernelId?: string;
+}
 /**
  * Options for the useAgents hook.
  */
@@ -20,13 +29,26 @@ export interface UseAgentOptions {
     /** Full agent spec object (persisted with checkpoints) */
     agentSpec?: Record<string, any>;
     /**
-     * Where runtime create/list operations should be sent.
-     * - `backend-services`: use backend runtimes service URL
-     * - `local-agent-runtimes`: use local agent-runtimes URL
+     * Where the agent's loop runs, and what runs it.
+     *
+     * - `cloud-pydanticai`: a runtime in the backend runtimes service
+     * - `local-pydanticai`: a local agent-runtimes server
+     * - `browser-vercelai`: the page itself — no runtime is created at all
+     */
+    variant?: AgentRuntimeVariant;
+    /**
+     * @deprecated Pass {@link UseAgentOptions.variant} instead.
+     * `backend-services` is `cloud-pydanticai`, `local-agent-runtimes` is
+     * `local-pydanticai`.
      */
     runtimeCreationTarget?: RuntimeCreationTarget;
     /** Explicit base URL for runtime create/list operations. */
     runtimeCreationBaseUrl?: string;
+    /**
+     * Existing runtime to connect to. When supplied, the hook owns the
+     * connection bootstrap as well as agent creation.
+     */
+    runtimeConnection?: AgentRuntimeConnectionOptions;
 }
 /**
  * Return type for the useAgents hook.
@@ -41,13 +63,7 @@ export interface UseAgentReturn {
     /** 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;
+    connectToRuntime: (options: AgentRuntimeConnectionOptions) => void;
     /** Disconnect from the runtime */
     disconnect: () => void;
     /** Agent endpoint URL (derived from runtime connection) */
@@ -67,7 +83,9 @@ export interface UseAgentReturn {
     isReady: boolean;
     /** Error if any */
     error: string | null;
-    /** Effective runtime creation target mode. */
+    /** Effective variant: where the loop runs, and what runs it. */
+    variant: AgentRuntimeVariant;
+    /** @deprecated Read {@link UseAgentReturn.variant}. */
     runtimeCreationTarget: RuntimeCreationTarget;
     /** Effective base URL used for runtime create/list operations. */
     runtimeCreationBaseUrl: string;
@@ -83,7 +101,7 @@ export declare const agentQueryKeys: {
         readonly all: () => readonly ["agentRuntimes"];
         readonly lists: () => readonly ["agentRuntimes", "list"];
         readonly details: () => readonly ["agentRuntimes", "detail"];
-        readonly detail: (podName: string) => readonly ["agentRuntimes", "detail", string];
+        readonly detail: (runtimeName: string) => readonly ["agentRuntimes", "detail", string];
     };
     readonly checkpoints: {
         readonly all: () => readonly ["checkpoints"];
@@ -91,9 +109,9 @@ export declare const agentQueryKeys: {
     };
 };
 /** Mark a runtime pod as deleted by this client (tombstone). */
-export declare function markRuntimePodDeleted(podName: string): void;
+export declare function markRuntimeDeleted(runtimeName: string): void;
 /** Clear a deleted-pod tombstone (pod legitimately exists again). */
-export declare function clearRuntimePodDeleted(podName: string): void;
+export declare function clearRuntimeDeleted(runtimeName: string): void;
 export interface AgentSandboxConnectionInfo {
     baseUrl: string;
     agentId?: string;
@@ -157,17 +175,21 @@ export declare function useAgentRuntimesQuery(scope?: {
 }, queryOptions?: {
     enabled?: boolean;
     refetchInterval?: number | false;
-}): import("@tanstack/react-query").UseQueryResult<NoInfer<AgentRuntimeData[]>, Error>;
+}): import("@tanstack/react-query").UseQueryResult<AgentRuntimeData[], Error>;
 /**
- * Hook to fetch a single agent runtime by pod name.
+ * Hook to fetch a single agent runtime by name.
  */
-export declare function useAgentRuntimeByPodName(podName: string | undefined): import("@tanstack/react-query").UseQueryResult<NoInfer<AgentRuntimeData>, Error>;
+export declare function useAgentRuntimeByName(runtimeName: 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.
+ * Hook to stop an agent runtime — running or paused.
+ *
+ * One hook, because there is one endpoint: `DELETE /runtimes/{runtimeName}` reaps
+ * the pod when there is one and the checkpoint records when there is not, so a
+ * caller that wants the runtime gone does not have to know which it is.
  */
 export declare function useDeleteAgentRuntime(): import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
 /**
@@ -195,10 +217,15 @@ export interface UseAgentsRuntimesReturn {
         data?: AgentRuntimeData[];
     }>;
     refreshRuntimes: () => void;
-    terminateRuntimeByPod: (podName: string, options?: {
-        beforeTerminate?: () => void | Promise<void>;
+    /**
+     * Stop a runtime, running or paused.
+     *
+     * `beforeStop` runs first, for callers that must tear a connection down
+     * before the pod goes away.
+     */
+    stopRuntimeByName: (runtimeName: string, options?: {
+        beforeStop?: () => void | Promise<void>;
     }) => Promise<unknown>;
-    deleteRuntimeByPod: (podName: string) => Promise<unknown>;
     createRuntime: (data: CreateAgentRuntimeRequest) => Promise<CreateRuntimeApiResponse>;
 }
 /**