@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/tools/adapters/agent-runtimes/lexicalHooks.js

@@ -8,8 +8,18 @@
  *
  * @module tools/adapters/agent-runtimes/lexicalHooks
  */
+/*
+ * First, before anything lexical: `@datalayer/jupyter-lexical` pulls
+ * `@lexical/code`, whose Prism language components read the bare global
+ * `Prism` the moment they evaluate — and PrismCss is what defines it. This
+ * module is now loaded *eagerly by the document plugin's build* (to
+ * contribute the document tools), so it can be the first lexical import in
+ * the page; without this line the whole document chunk died on "Prism is
+ * not defined".
+ */
+import '@datalayer/jupyter-react/lib/css/PrismCss';
 import { useMemo } from 'react';
-import { lexicalStore, DefaultExecutor as LexicalDefaultExecutor, lexicalToolDefinitions, lexicalToolOperations, } from '@datalayer/jupyter-lexical';
+import { lexicalStore, DefaultExecutor as LexicalDefaultExecutor, getLexicalTools, useLexicalToolBundle, } from '@datalayer/jupyter-lexical';
 import { createAllAgentRuntimesTools } from './AgentRuntimesToolAdapter';
 /**
  * Hook that creates agent-runtimes tools for lexical operations.
@@ -41,6 +51,25 @@ import { createAllAgentRuntimesTools } from './AgentRuntimesToolAdapter';
  * />
  * ```
  */
+/**
+ * The document's frontend tools, built without React.
+ *
+ * The plain twin of `useLexicalTools`, for the document plugin contributing
+ * to the chat's `LoopFrontendTool` point. The executor reads the lexical
+ * store's live state through its methods; no reactivity needed.
+ */
+export function createLexicalTools(documentId, contextOverrides) {
+    const executor = new LexicalDefaultExecutor(documentId, lexicalStore.getState());
+    // A snapshot: whichever plugins have mounted by now. The React hook below
+    // is the one that keeps up as they come and go.
+    const { definitions, operations } = getLexicalTools(documentId);
+    return createAllAgentRuntimesTools(definitions, operations, {
+        documentId,
+        executor,
+        format: 'toon',
+        ...contextOverrides,
+    });
+}
 export function useLexicalTools(documentId, contextOverrides) {
     // Create DefaultExecutor — stable reference, only recreate when documentId changes.
     // lexicalStore is a module-level Zustand store singleton; getState() returns
@@ -54,6 +83,18 @@ export function useLexicalTools(documentId, contextOverrides) {
         format: 'toon',
         ...contextOverrides,
     }), [documentId, executor, contextOverrides]);
+    /*
+     * The tools a document offers are not a constant.
+     *
+     * The block tools are — every Lexical document has blocks — but a plugin
+     * brings its own, and which plugins are mounted is the editor's business,
+     * not this hook's. `useLexicalToolBundle` watches the set of mounted
+     * plugins by name, so this recomputes when the editor gains or loses one
+     * and at no other time: the stability the comment above is about is
+     * preserved, because a block insertion does not change which plugins are
+     * mounted.
+     */
+    const bundle = useLexicalToolBundle(documentId);
     // Create and return tools (stable reference)
-    return useMemo(() => createAllAgentRuntimesTools(lexicalToolDefinitions, lexicalToolOperations, context), [context]);
+    return useMemo(() => createAllAgentRuntimesTools(bundle.definitions, bundle.operations, context), [bundle, context]);
 }

package/lib/tools/adapters/agent-runtimes/notebookHooks.d.ts

@@ -1,5 +1,14 @@
 import type { ToolExecutionContext } from '@datalayer/jupyter-react';
 import type { FrontendToolDefinition } from '../../../types/tools';
+/**
+ * The notebook's frontend tools, built without React.
+ *
+ * What `useNotebookTools` memoises, as a plain function — for callers that
+ * are not components: a reactor plugin contributing the tools to the chat's
+ * `LoopFrontendTool` point builds them here. The executor reads the store's
+ * live state through its methods, so nothing here needs reactivity.
+ */
+export declare function createNotebookTools(documentId: string, contextOverrides?: Partial<Omit<ToolExecutionContext, 'executor' | 'documentId'>>): FrontendToolDefinition[];
 /**
  * Hook that creates agent-runtimes tools for notebook operations.
  * Returns stable tools array that won't cause re-renders.

package/lib/tools/adapters/agent-runtimes/notebookHooks.js

@@ -13,6 +13,18 @@ import { notebookStore, DefaultExecutor, notebookToolDefinitions, notebookToolOp
 import { createAllAgentRuntimesTools } from './AgentRuntimesToolAdapter';
 // Hook wrapper to get notebook store state
 const useNotebookStore = () => notebookStore.getState();
+/**
+ * The notebook's frontend tools, built without React.
+ *
+ * What `useNotebookTools` memoises, as a plain function — for callers that
+ * are not components: a reactor plugin contributing the tools to the chat's
+ * `LoopFrontendTool` point builds them here. The executor reads the store's
+ * live state through its methods, so nothing here needs reactivity.
+ */
+export function createNotebookTools(documentId, contextOverrides) {
+    const executor = new DefaultExecutor(documentId, notebookStore.getState());
+    return createAllAgentRuntimesTools(notebookToolDefinitions, notebookToolOperations, { documentId, executor, format: 'toon', ...contextOverrides });
+}
 /**
  * Hook that creates agent-runtimes tools for notebook operations.
  * Returns stable tools array that won't cause re-renders.

package/lib/tools/adapters/commands/frontendCommandTools.d.ts

@@ -0,0 +1,11 @@
+import type { AgentToolBundle, ReactorPlatform } from '@datalayer/reactor';
+import type { FrontendToolDefinition } from '../../../types';
+/** One bundle's commands, executed on a reactor. Only the `toolset` is offered. */
+export declare function agentBundleTools(bundle: AgentToolBundle, reactor: ReactorPlatform | null | undefined): FrontendToolDefinition[];
+/** Every command tool of every bundle, in contribution order. */
+export declare function agentBundleToolDefinitions(bundles: AgentToolBundle[], reactor: ReactorPlatform | null | undefined): FrontendToolDefinition[];
+/**
+ * The command tools every mounted plugin declared, bound to this page's
+ * reactor — live, so a plugin switched on later brings its tools with it.
+ */
+export declare function useAgentCommandTools(): FrontendToolDefinition[];

package/lib/tools/adapters/commands/frontendCommandTools.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The agent tools plugins declared, as tools the browser loop can call.
+ *
+ * A plugin contributes an `AgentTools` bundle to the reactor: its commands,
+ * named and described for a model. Each becomes a `FrontendToolDefinition` —
+ * the shape the notebook tools have, so a host adds them the same way — whose
+ * handler runs `reactor.executeCommand(command, args)` on the reactor the
+ * host is mounted in, which is exactly what the keystroke does. What the
+ * command returns is the tool's result: a command that lists the decks
+ * answers with the list, and a command that returns nothing answers that it
+ * ran. A host with a richer in-page implementation of the same tool
+ * contributes it under the same name, and the chat folds these in after
+ * contributions, so the bundle's version steps aside.
+ *
+ * @module tools/adapters/commands
+ */
+import { useMemo } from 'react';
+import { useAgentToolBundles, useOptionalReactorPlatform, } from '@datalayer/reactor/react';
+const NO_ARGUMENTS = { type: 'object', properties: {} };
+/** One bundle's commands, executed on a reactor. Only the `toolset` is offered. */
+export function agentBundleTools(bundle, reactor) {
+    const granted = new Set(bundle.toolset);
+    return bundle.commands
+        .filter((entry) => granted.has(entry.name))
+        .map((entry) => ({
+        name: entry.name,
+        description: entry.description,
+        parameters: entry.parameters ?? NO_ARGUMENTS,
+        location: 'frontend',
+        handler: async (args) => {
+            if (!reactor) {
+                throw new Error(`${entry.name}: the ${bundle.plugin ?? bundle.id} plugin is not mounted on this page.`);
+            }
+            const argument = Object.keys(args ?? {}).length > 0 ? args : undefined;
+            const result = await reactor.executeCommand(entry.command, argument);
+            // The command's own answer when it gave one; otherwise the fact that
+            // it ran, which is all a keystroke-shaped command has to say.
+            return result === undefined
+                ? { ok: true, command: entry.command, argument }
+                : result;
+        },
+    }));
+}
+/** Every command tool of every bundle, in contribution order. */
+export function agentBundleToolDefinitions(bundles, reactor) {
+    return bundles.flatMap(bundle => agentBundleTools(bundle, reactor));
+}
+/**
+ * The command tools every mounted plugin declared, bound to this page's
+ * reactor — live, so a plugin switched on later brings its tools with it.
+ */
+export function useAgentCommandTools() {
+    const reactor = useOptionalReactorPlatform();
+    const bundles = useAgentToolBundles();
+    return useMemo(() => agentBundleToolDefinitions(bundles, reactor), [bundles, reactor]);
+}

package/lib/tools/adapters/commands/index.d.ts

@@ -0,0 +1 @@
+export * from './frontendCommandTools';

package/lib/tools/adapters/commands/index.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export * from './frontendCommandTools';

package/lib/tools/adapters/copilotkit/lexicalHooks.js

@@ -9,7 +9,7 @@
  * @module tools/adapters/copilotkit/lexicalHooks
  */
 import { useMemo } from 'react';
-import { useLexicalStore, DefaultExecutor as LexicalDefaultExecutor, lexicalToolDefinitions, lexicalToolOperations, } from '@datalayer/jupyter-lexical';
+import { useLexicalStore, DefaultExecutor as LexicalDefaultExecutor, useLexicalToolBundle, } from '@datalayer/jupyter-lexical';
 import { createAllCopilotKitActions } from './CopilotKitToolAdapter';
 /**
  * Hook that creates CopilotKit actions for lexical tools.
@@ -50,8 +50,12 @@ export function useLexicalToolActions(documentId, contextOverrides) {
         format: 'toon', // Default format
         ...contextOverrides, // Override with user-provided values
     }), [documentId, executor, contextOverrides]);
+    // The document's tools: the block ones, plus whatever the plugins mounted
+    // in this editor have contributed. Changes only when a plugin mounts or
+    // unmounts.
+    const bundle = useLexicalToolBundle(documentId);
     // Create and return CopilotKit actions (stable reference)
-    // Only re-create when context changes (i.e., when documentId or contextOverrides change)
-    const actions = useMemo(() => createAllCopilotKitActions(lexicalToolDefinitions, lexicalToolOperations, context), [context]);
+    // Only re-create when the context or the mounted plugins change
+    const actions = useMemo(() => createAllCopilotKitActions(bundle.definitions, bundle.operations, context), [bundle, context]);
     return actions;
 }

package/lib/tools/index.d.ts

@@ -4,4 +4,5 @@
  * @module tools
  */
 export * from './adapters/copilotkit';
+export * from './adapters/commands';
 export { ToolExecutor, createToolExecutor, type ToolExecutionContext, } from './ToolExecutor';

package/lib/tools/index.js

@@ -9,5 +9,6 @@
  */
 // Export adapters
 export * from './adapters/copilotkit';
+export * from './adapters/commands';
 // Tool executor
 export { ToolExecutor, createToolExecutor, } from './ToolExecutor';

package/lib/types/a2a.d.ts

@@ -1,4 +1,18 @@
 import { ChatMessage } from './messages';
+/**
+ * A protocol extension an agent card advertises supporting
+ * (https://a2a-protocol.org/latest/topics/extensions/): a URI, not the
+ * bare string this codebase's `capabilities.extensions` used to be typed
+ * as. A real card's entries are objects — `{ uri, description?, required?
+ * }` — and a `string[]` type made `.includes(uri)` silently false against
+ * one, even though nothing read the field yet to notice.
+ */
+export interface AgentExtension {
+    uri: string;
+    description?: string;
+    required?: boolean;
+    params?: Record<string, unknown>;
+}
 /**
  * Agent card for A2A protocol
  */
@@ -9,7 +23,7 @@ export interface AgentCard {
     version?: string;
     capabilities?: {
         streaming?: boolean;
-        extensions?: string[];
+        extensions?: AgentExtension[];
     };
     skills?: Array<{
         id: string;

package/lib/types/agents-lifecycle.d.ts

@@ -30,12 +30,17 @@ export type CreateAgentRuntimeRequest = {
     billingSourceOrganizationUid?: string;
     /** Source organization handle for team-billed runtimes. */
     billingSourceOrganizationHandle?: string;
-    /** Mount account home folder into runtime. */
-    mountHomeFolder?: boolean;
-    /** Optional volume UID to mount into runtime. */
-    volumeUid?: string;
-    /** Optional volume UIDs to mount into runtime. */
-    volumeUids?: string[];
+    /**
+     * The runtime's uid (a ULID) the Contents attachments were made for; the
+     * runtime is created under it so the attachments name the right sandbox.
+     */
+    runtimeName?: string;
+    /**
+     * Contents attachments to mount, created for `runtimeName` before the runtime:
+     * a Home Folder attachment mounts the caller's home folders, a Volume
+     * attachment mounts its Volume. There is no other way to ask for a mount.
+     */
+    contentAttachmentUids?: string[];
 };
 export type CreateRuntimeApiResponse = {
     success?: boolean;

package/lib/types/agents.d.ts

@@ -30,13 +30,13 @@ export interface AgentRuntimeState {
 /**
  * Agent Runtime data type (mapped from runtimes service).
  *
- * Backend RuntimePod fields: pod_name, environment{name,title,cpu,memory,gpu,resources}, uid,
+ * Backend RuntimeRecord fields: runtime_name, environment{name,title,cpu,memory,gpu,resources}, uid,
  * type, given_name, token, ingress, reservation_id, started_at, expired_at, burning_rate.
  *
  * We map `ingress` to `url` for consistency with the UI.
  */
 export type AgentRuntimeData = {
-    pod_name: string;
+    runtime_name: string;
     id: string;
     name: string;
     environment: {
@@ -62,15 +62,40 @@ export type AgentRuntimeData = {
     billing_entity_uid?: string;
     billing_entity_type?: 'user' | 'organization' | 'team';
     billing_entity_handle?: string;
-    mount_home_folder?: boolean;
-    volume_uid?: string;
-    volume_uids?: string[];
+    /** Home folders the runtime mounts: the caller's own and their memberships. */
+    home_folder_mounts?: RuntimeHomeFolderMount[];
+    /** Contents attachments the runtime mounts, as recorded on its pod. */
+    content_attachments?: RuntimeContentAttachment[];
+};
+/** One home folder a runtime mounts, at `~/{handle}`. */
+export type RuntimeHomeFolderMount = {
+    type: 'user' | 'organization' | 'team';
+    uid: string;
+    handle?: string;
+    organization_handle?: string;
+};
+/**
+ * A Contents attachment as the runtime reports it.
+ *
+ * `source_kind` is the kind of the attached source — `files` for the Home
+ * Folder, `volume` for a Volume — which is what tells the two mounts apart.
+ */
+export type RuntimeContentAttachment = {
+    uid?: string;
+    source_uid?: string;
+    source_kind?: string;
+    delivery?: 'mount' | 'local-bridge' | 'materialize' | 'client' | 'environment';
+    mount_path?: string | null;
+    mode?: 'ro' | 'rw';
+    required?: boolean;
+    status?: string;
+    provider_resource_id?: string | null;
 };
 export interface RunningAgent {
     /** Unique agent ID within the runtime */
     agentId: string;
     /** Pod name in Kubernetes */
-    podName: string;
+    runtimeName: string;
     /** Agent display name */
     name: string;
     /** Agentspec ID used to create the agent */

package/lib/types/agentspecs.d.ts

@@ -14,6 +14,66 @@ import type { AgentCodemodeConfig, AgentAdvancedConfig } from './config';
  * Defines the configuration for a reusable agent template that can be
  * instantiated as an Agent Runtime.
  */
+/**
+ * An opener offered to somebody arriving at an empty chat.
+ *
+ * Text and, optionally, a mark to show beside it. It was a bare string, which
+ * is enough for a chip in an empty state and not enough for anywhere else a
+ * suggestion is offered — a menu, a launcher, a list of what an agent is for —
+ * where an unmarked row of sentences is hard to scan. Both marks are optional
+ * and independent: an octicon suits chrome already drawn in line art, an emoji
+ * suits a place that has colour.
+ */
+export interface AgentSuggestion {
+    /** What is sent when the suggestion is taken. */
+    text: string;
+    /**
+     * A few words shown as the label where the text is too long to be one — a
+     * chip, a menu row. The text itself is then the tooltip.
+     */
+    summary?: string;
+    /** Octicon name to show beside it. */
+    icon?: string;
+    /** Unicode emoji to show beside it. */
+    emoji?: string;
+}
+/**
+ * Conversation checkpoint configuration.
+ *
+ * Snapshots of the message history the agent (or the person) can rewind to.
+ * Complementary to runtime checkpoints (CRIU), which freeze the whole process.
+ */
+export interface AgentCheckpointsConfig {
+    /** Whether checkpointing is on for this agent. */
+    enabled?: boolean;
+    /** When a checkpoint is taken on its own. */
+    frequency?: 'every_turn' | 'every_tool' | 'manual_only';
+    /** Rolling window: the oldest checkpoint goes when this is exceeded. */
+    max_checkpoints?: number;
+    /** Where checkpoints are kept. */
+    store?: 'in_memory' | 'file';
+}
+/**
+ * One kind of work an agent can be delegated, and what it takes and returns.
+ *
+ * The unit `agents.discover` matches on. It maps onto an A2A agent card's
+ * `skills` entry, so a Datalayer agentspec and a third-party A2A worker are
+ * discoverable through one query rather than two.
+ */
+export interface AgentCapability {
+    /** One of the closed vocabulary in `agent_runtimes.types`. */
+    id: string;
+    /** Display label; the vocabulary's own description when absent. */
+    name?: string;
+    /** What this agent in particular does under that capability. */
+    description?: string;
+    /** Context reference kinds it accepts — notebook, dataset, file, sandbox. */
+    inputs?: string[];
+    /** Artifact types it produces — notebook, report, dataset, file. */
+    outputs?: string[];
+    /** Free text, for humans reading a catalogue; never matched on. */
+    tags?: string[];
+}
 export interface Agentspec {
     /** Unique agent identifier */
     id: string;
@@ -58,17 +118,40 @@ export interface Agentspec {
     /** Theme color for the agent (hex code) */
     color?: string;
     /** Chat suggestions to show users what this agent can do */
-    suggestions?: string[];
+    suggestions?: AgentSuggestion[];
     /** Welcome message shown when agent starts */
     welcomeMessage?: string;
     /** Path to Jupyter notebook to show on agent creation */
     welcomeNotebook?: string;
     /** Path to Lexical document to show on agent creation */
     welcomeDocument?: string;
-    /** Sandbox variant to use for this agent (e.g. 'eval', 'jupyter', 'kaggle'). */
+    /**
+     * Which agent framework runs this agent's loop.
+     *
+     * `pydantic-ai` (the default) runs it server-side in the agent runtime;
+     * `vercel-ai` runs it in the browser with the Vercel AI SDK, for an agent
+     * that has to work with no server behind it. Distinct from `protocol`,
+     * which says how a client and an agent talk rather than what runs the loop.
+     */
+    harness?: string;
+    /** Sandbox variant to use for this agent (e.g. 'eval', 'jupyter-server', 'kaggle'). */
     sandboxVariant?: string;
     /** User-facing objective for the agent */
     goal?: string;
+    /**
+     * What work this agent can be delegated (ORCHESTRATOR.md, O2-07).
+     *
+     * `protocol` below says how a client and an agent talk; this says what it
+     * is worth handing the agent. Ids come from a closed vocabulary, because
+     * `agents.discover --capability notebook.validate` has to match something
+     * and free text does not: two specs saying "analysis" and "analyse"
+     * describe the same work and find each other never.
+     *
+     * Deliberately not called `capabilities`: that name is already taken on
+     * this type for pydantic-ai capability configurations, which are runtime
+     * behaviours attached to an agent rather than work handed to it.
+     */
+    delegable?: AgentCapability[];
     /** Communication protocol (e.g., 'ag-ui', 'acp', 'a2a', 'vercel-ai') */
     protocol?: string;
     /** UI extension type (e.g., 'a2ui', 'mcp-apps') */
@@ -89,6 +172,8 @@ export interface Agentspec {
     output?: AgentOutputConfig;
     /** Advanced settings (cost_limit, time_limit, max_iterations, validation) */
     advanced?: AgentAdvancedConfig;
+    /** Conversation checkpoints: auto-snapshots of the history, with tools to save, list and rewind. */
+    checkpoints?: AgentCheckpointsConfig;
     /** Authorization policy */
     authorizationPolicy?: string;
     /** Notification configuration (email, slack) */
@@ -111,6 +196,22 @@ export interface Agentspec {
     /** Subagent delegation configuration. */
     subagents?: SubAgentsConfig;
 }
+/**
+ * Where a subagent reached over A2A lives, or how to launch it.
+ *
+ * Either `url` names an agent already running, or the subagent's `ref` names
+ * the agentspec to launch one from — on the local agent-runtimes server when
+ * the parent runs locally and on a Datalayer runtime when it runs in the
+ * cloud (`launch: 'auto'`, the default), or on one of those explicitly.
+ */
+export interface A2ASubagentConfig {
+    /** JSON-RPC endpoint of an A2A agent already running. */
+    url?: string;
+    /** Where to launch the agent named by `ref`. */
+    launch?: 'local' | 'cloud' | 'auto';
+    /** Runtime environment for a cloud launch. */
+    environment?: string;
+}
 /**
  * Configuration for a subagent within an agent specification.
  */
@@ -119,8 +220,23 @@ export interface SubAgentspecConfig {
     name: string;
     /** Brief description shown to the parent agent */
     description: string;
-    /** System prompt for the subagent */
-    instructions: string;
+    /**
+     * System prompt for the subagent. Optional when `ref` names an agentspec to
+     * take it from.
+     */
+    instructions?: string;
+    /**
+     * An agentspec this subagent *is*, as `<id>:<version>`.
+     *
+     * A specialist defined once and referenced by many parents, rather than its
+     * instructions copy-pasted into each — which is how they drift apart.
+     */
+    ref?: string;
+    /**
+     * Reach this subagent over A2A, as a separate agent, instead of running it
+     * inside the parent's process.
+     */
+    a2a?: A2ASubagentConfig;
     /** LLM model to use (defaults to parent agent's model) */
     model?: string;
     /** Whether the subagent can ask the parent for clarification */