@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/types/stream.d.ts

@@ -30,8 +30,19 @@ export interface AgentStreamCompactionPayload {
     /** Whether history was actually reduced (`end`). */
     reduced?: boolean;
 }
-/** Phase of a streamed subagent interaction. */
-export type AgentSubagentPhase = 'start' | 'text' | 'thinking' | 'tool_call' | 'tool_result' | 'end' | 'error';
+/**
+ * What a delegation's `error` says when the run was stopped rather than
+ * failed — by the person, from either side of the wire.
+ */
+export declare const SUBAGENT_STOPPED = "Stopped.";
+/**
+ * Phase of a streamed subagent interaction.
+ *
+ * `status` is the remote side of a delegation talking: an agent reached over
+ * A2A being launched, its task submitted, working, completed. It renders no
+ * text; it tells a sidebar where the run stands.
+ */
+export type AgentSubagentPhase = 'start' | 'status' | 'text' | 'thinking' | 'tool_call' | 'tool_result' | 'end' | 'error';
 /**
  * Incremental subagent activity pushed on the parent agent's monitoring
  * stream while a `delegate_task` call runs. Consumers key events by
@@ -58,6 +69,40 @@ export interface AgentStreamSubagentPayload {
     output?: string;
     /** Failure message (`error`). */
     error?: string;
+    /**
+     * How the subagent is reached: inside the parent's process, or over A2A as
+     * a separate agent. Absent means in-process.
+     */
+    transport?: 'in-process' | 'a2a';
+    /** Where the A2A agent answers (`transport: 'a2a'`). */
+    url?: string;
+    /**
+     * Where an A2A agent runs: `local` (launched beside the parent), `cloud`
+     * (a Datalayer runtime launched for it), `remote` (given by URL), or the
+     * `auto` a spec asked for before the choice was made.
+     */
+    launch?: string;
+    /** The A2A task id, once the remote agent has one (`status`). */
+    taskId?: string | null;
+    /**
+     * Where a remote run stands (`status`): `launching`, `ready`, then the A2A
+     * task states — `submitted`, `working`, `completed`, `failed`, …
+     */
+    state?: string;
+    /** The remote agent's card, summarised. */
+    agentCard?: {
+        name?: string;
+        description?: string;
+        version?: string;
+        url?: string;
+        skills?: string[];
+    };
+    /** Uid of the runtime launched for a cloud A2A agent. */
+    runtimeUid?: string;
+    /** Delegation depth, `0` for a top-level delegation (server harness). */
+    depth?: number;
+    /** The delegation stack, the running subagent last (server harness). */
+    chain?: string[];
 }
 export interface AgentStreamMessage<TPayload = Record<string, unknown>> {
     version: string;
@@ -71,7 +116,7 @@ export interface AgentStreamMessage<TPayload = Record<string, unknown>> {
 export interface AgentStreamToolApprovalPayload {
     id: string;
     agent_id?: string;
-    pod_name?: string;
+    runtime_name?: string;
     tool_name: string;
     tool_call_id?: string;
     tool_args?: Record<string, unknown>;

package/lib/types/stream.js

@@ -2,6 +2,11 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+/**
+ * What a delegation's `error` says when the run was stopped rather than
+ * failed — by the person, from either side of the wire.
+ */
+export const SUBAGENT_STOPPED = 'Stopped.';
 const isObject = (value) => !!value && typeof value === 'object';
 export function parseAgentStreamMessage(raw) {
     if (!isObject(raw)) {

package/lib/types/teams.d.ts

@@ -1,13 +1,84 @@
 /**
  * Specification for an agent within a team.
  */
+/**
+ * A specialist a team member may hand work to.
+ *
+ * The same shape as a subagent on an agent spec: delegation is one idea, and
+ * it should be written the same way wherever it appears.
+ */
+import type { AgentSuggestion } from './agentspecs';
+export interface TeamSubagentspec {
+    /** How the member addresses it, e.g. `@CellFixer`. */
+    name: string;
+    /** Agent catalogue reference, `id` or `id:version`. */
+    ref?: string;
+    /** What it is for, and when to reach for it. Read by the delegating model. */
+    description?: string;
+    /** System prompt, for a subagent defined only here. */
+    instructions?: string;
+}
+/**
+ * What each member of a team is told about the conversation so far.
+ *
+ * The two things every multi-agent framework does, named rather than assumed —
+ * see {@link TeamContextSpec.sharing}.
+ */
+export type TeamContextSharing = 'shared' | 'isolated' | 'own-turns';
+/** What each member is told about the conversation so far. */
+export interface TeamContextSpec {
+    /**
+     * How much of the conversation each member is given.
+     *
+     * - `shared` — one thread, and every member is sent all of it. What a
+     *   supervisor team wants: routing only makes sense if the member receiving
+     *   the work can see what was already said. AutoGen group chats, LangGraph
+     *   supervisors and OpenAI handoffs all work this way.
+     * - `isolated` — a thread per member, swapped when the person switches. What
+     *   a delegation model wants: the child runs blind and returns a result, as
+     *   Claude Code subagents and CrewAI tasks do. Choose it when members would
+     *   mislead each other more than they would help.
+     * - `own-turns` — one thread on screen, but each member is sent only the
+     *   turns it took part in. Deliberately makes what the reader sees differ
+     *   from what the model sees, which is a cost worth naming.
+     *
+     * A team's property rather than a runtime's setting, because it follows from
+     * what the team *is*.
+     */
+    sharing: TeamContextSharing;
+}
+/** How far members may hand work to each other, and to subagents. */
+export interface TeamDelegationSpec {
+    /** Levels of delegation allowed; 0 forbids it. */
+    maxDepth: number;
+    /** Whether a member may hand work to another member of the same team. */
+    allowPeerDelegation: boolean;
+    /** Whether members also get the general-purpose subagent. */
+    includeGeneralPurpose: boolean;
+}
 export interface TeamAgentspec {
     /** Agent identifier within the team */
     id: string;
     /** Display name for the team agent */
     name: string;
-    /** Role within the team (e.g., 'Primary · Initiator', 'Secondary', 'Final') */
+    /**
+     * Agent catalogue reference, `id` or `id:version`.
+     *
+     * A member that names one inherits its model, tools, prompt and subagents;
+     * the fields below then say what is different about it in this team.
+     */
+    ref?: string;
+    /** Structural role: coordinator, initiator, contributor, reviewer, finalizer. */
     role?: string;
+    /**
+     * Member ids that must finish first.
+     *
+     * What makes the running order computable — it replaced a prose `trigger`
+     * that read well and could not be executed.
+     */
+    dependsOn?: string[];
+    /** Specialists this member may delegate to. */
+    subagents?: TeamSubagentspec[];
     /** Goal or objective for this agent */
     goal?: string;
     /** AI model identifier */
@@ -25,10 +96,23 @@ export interface TeamAgentspec {
  * Supervisor agent configuration for a team.
  */
 export interface TeamSupervisorSpec {
-    /** Supervisor agent name */
+    /** Display name for the supervisor. */
     name: string;
-    /** AI model used by the supervisor */
+    /** Agent catalogue reference, `id` or `id:version`. */
+    ref?: string;
+    /** Model id, overriding the referenced agent's. */
     model?: string;
+    /** What the supervisor is accountable for across the whole run. */
+    goal?: string;
+    /** Supervision prompt, for a supervisor defined only here. */
+    instructions?: string;
+    /** Whether a person signs off the routing decisions. */
+    approval?: string;
+    /**
+     * Whether the supervisor may end the run before every member has gone.
+     * False makes it a router only.
+     */
+    canTerminate?: boolean;
 }
 /**
  * Validation settings for a team.
@@ -115,9 +199,23 @@ export interface TeamSpec {
     /** Execution mode: 'sequential' or 'parallel' */
     executionMode: string;
     /** Supervisor agent configuration */
-    supervisor?: TeamSupervisorSpec;
+    /** Who decides what happens next. Every team has one. */
+    supervisor: TeamSupervisorSpec;
     /** Instructions for routing tasks between agents */
     routingInstructions?: string;
+    /**
+     * Openers shown in an empty chat.
+     *
+     * At the team level because they describe the team's front door: the
+     * supervisor answers first, and what is worth asking is a property of the
+     * whole team rather than of any one member. A person who has just opened a
+     * workspace does not yet know there are two agents behind it.
+     */
+    suggestions?: AgentSuggestion[];
+    /** How far members may hand work to each other, and to subagents. */
+    delegation?: TeamDelegationSpec;
+    /** What each member is told about the conversation so far. */
+    context?: TeamContextSpec;
     /** Validation settings for the team */
     validation?: TeamValidationSpec;
     /** List of agents in the team */

package/lib/types/tool-approvals.d.ts

@@ -4,7 +4,7 @@ export interface ToolApproval {
     /** Agent that requested the tool call */
     agentId: string;
     /** Pod running the agent */
-    podName: string;
+    runtimeName: string;
     /** Tool being requested */
     toolName: string;
     /** Tool call arguments */

package/lib/types/tools.d.ts

@@ -70,8 +70,14 @@ export interface FrontendToolSpec {
     tags: string[];
     /** Whether the frontend tool is enabled */
     enabled: boolean;
-    /** Which tools from the toolset to include ('all' or specific list) */
-    toolset: string;
+    /**
+     * Which tools of the underlying toolset this bundle grants: `'all'`, or an
+     * explicit list of tool names.
+     *
+     * A list is how a specialist takes only what it needs — an agent that may
+     * read and edit a notebook but must never delete from it.
+     */
+    toolset: string | string[];
     /** Icon identifier */
     icon?: string;
     /** Emoji identifier */

package/lib/utils/utils.js

@@ -8,7 +8,7 @@
  * @module chat/utils
  */
 import { QueryClient } from '@tanstack/react-query';
-import { AGUIAdapter, A2AAdapter, VercelAIAdapter, ACPAdapter, } from '../protocols';
+import { AGUIAdapter, A2AAdapter, VercelAIAdapter, ACPAdapter, BrowserAgentAdapter, } from '../protocols';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -202,6 +202,12 @@ export function createProtocolAdapter(config) {
             return new VercelAIAdapter(adapterConfig);
         case 'acp':
             return new ACPAdapter(adapterConfig);
+        case 'browser-vercel-ai':
+            // The live objects a browser agent needs — its tools, its instructions,
+            // where to reach a model — travel in `options`, which is spread onto
+            // `adapterConfig` above. Unlike the other adapters, a URL is not enough:
+            // this one runs the loop rather than calling one.
+            return new BrowserAgentAdapter(adapterConfig);
         default:
             console.warn(`[ChatBase] Unknown protocol type: ${config.type}`);
             return null;