@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/protocols/BrowserAgentAdapter.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The browser harness, behind the protocol interface every chat surface uses.
+ *
+ * The other adapters carry messages to somewhere else — AG-UI over SSE, Vercel
+ * AI over SSE, ACP over a socket. This one carries them nowhere: the loop turns
+ * in this page with the Vercel AI SDK, and the adapter exists so that fact
+ * stays invisible to `<Chat>`, `<ChatFloating>` and everything downstream of
+ * them. Suggestions, tool rendering, the panel, the history: all unchanged.
+ *
+ * That is the point of putting it here rather than writing a bespoke chat for
+ * in-browser agents. There is nothing chat-shaped about the browser harness —
+ * only a different answer to "where does the loop turn" — so it belongs at the
+ * one seam the package already has for that question.
+ *
+ * **Who executes the tools.** In every other adapter the runtime asks and the
+ * client answers: a `tool-call` arrives, `ChatBase` runs the frontend tool's
+ * handler and posts the result back with {@link sendToolResult}. Here the SDK
+ * owns the loop and calls the handler itself, so a host must NOT also pass
+ * `frontendTools` to the chat component — the tools go to this adapter, and the
+ * chat is left to render what happened. {@link sendToolResult} is therefore a
+ * no-op: by the time anyone could call it, the tool has already run.
+ *
+ * @module protocols/BrowserAgentAdapter
+ */
+import { type LanguageModel } from 'ai';
+import type { ProtocolAdapterConfig } from '../types/protocol';
+import type { ChatMessage } from '../types/messages';
+import type { FrontendToolDefinition } from '../types/tools';
+import type { AgentStreamSubagentPayload } from '../types/stream';
+import { BaseProtocolAdapter } from './BaseProtocolAdapter';
+import type { TeamContextSharing } from '../types/teams';
+import { type BrowserSubagent, type BrowserModelOptions, type FrontendToolsToVercelAIOptions } from '../runtimes/browser';
+/**
+ * What a browser agent needs that a remote one does not.
+ *
+ * These arrive through `ProtocolConfig.options`, which `createProtocolAdapter`
+ * spreads onto the adapter config. They are live objects — a tool set bound to
+ * this page's notebook — rather than the URLs and tokens the other adapters
+ * take, which is exactly the difference between running a loop and calling one.
+ */
+export interface BrowserAgentAdapterConfig extends ProtocolAdapterConfig, FrontendToolsToVercelAIOptions {
+    /** The agent's instructions. From the spec's `systemPrompt`. */
+    instructions?: string;
+    /** The tools the agent can call in this page. */
+    frontendTools?: FrontendToolDefinition[];
+    /** Where to reach a model, unless one is supplied outright. */
+    inference?: Omit<BrowserModelOptions, 'model'>;
+    /** The model id, as a spec spells it. */
+    model?: string;
+    /** A ready-made model, for a host that resolves models its own way. */
+    languageModel?: LanguageModel;
+    /** Turn ceiling for one request. */
+    maxSteps?: number;
+    /**
+     * Agents this one may hand work to.
+     *
+     * They join the frontend tools as tools of their own, which is how the SDK
+     * models delegation: a subagent is another agent the parent reaches by
+     * calling it.
+     */
+    subagents?: BrowserSubagent[];
+    /** What a subagent is told about the conversation so far. */
+    sharing?: TeamContextSharing;
+    /** Told what a delegated run does, as it does it — see `subagentTools`. */
+    onSubagentEvent?: (event: AgentStreamSubagentPayload) => void;
+}
+/**
+ * An agent loop running in the page, speaking the protocol adapter interface.
+ */
+export declare class BrowserAgentAdapter extends BaseProtocolAdapter {
+    readonly protocol: "browser-vercel-ai";
+    readonly protocolTransport: "http";
+    private browserConfig;
+    private abortController;
+    private tools;
+    constructor(config: BrowserAgentAdapterConfig);
+    /**
+     * Nothing to dial.
+     *
+     * The interface asks for a connection because the other adapters have one.
+     * This reports connected because the loop is already here.
+     */
+    connect(): Promise<void>;
+    disconnect(): void;
+    /**
+     * Stop the run in flight, and stay connected.
+     *
+     * What the chat's stop button calls on an adapter that has it. The other
+     * adapters cut a network stream; this one cuts the model call turning in
+     * the page — and, through the signal every delegation reads, the
+     * subagents that call started. Without this the button stopped the
+     * chat's *display* of the run and nothing else: the parent kept calling
+     * the model and the children kept working.
+     */
+    stopGeneration(): void;
+    supportsFeature(feature: string): boolean;
+    /**
+     * Already done.
+     *
+     * The SDK executed the tool before this adapter reported it, so there is no
+     * result to carry back and nothing to resume. Kept because the interface has
+     * it and a host should not have to know which adapter it is holding.
+     */
+    sendToolResult(): Promise<void>;
+    /**
+     * The model this agent asks, resolved once per request.
+     *
+     * The chat's model menu sends its choice with each message, as it does to
+     * a server-side harness; here it names the model the inference service is
+     * asked for, over the one the agent was built with. A ready-made
+     * `languageModel` is the host's own choice and is not swapped out.
+     */
+    private resolveModel;
+    /**
+     * Run one turn of the loop and report it as it happens.
+     *
+     * The SDK's `fullStream` is already the event stream this interface wants —
+     * text deltas, tool calls, tool results, a finish — so the body of this is a
+     * translation rather than a protocol implementation.
+     */
+    sendMessage(message: ChatMessage, options?: {
+        messages?: ChatMessage[];
+        model?: string;
+    }): Promise<void>;
+}

package/lib/protocols/BrowserAgentAdapter.js

@@ -0,0 +1,317 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The browser harness, behind the protocol interface every chat surface uses.
+ *
+ * The other adapters carry messages to somewhere else — AG-UI over SSE, Vercel
+ * AI over SSE, ACP over a socket. This one carries them nowhere: the loop turns
+ * in this page with the Vercel AI SDK, and the adapter exists so that fact
+ * stays invisible to `<Chat>`, `<ChatFloating>` and everything downstream of
+ * them. Suggestions, tool rendering, the panel, the history: all unchanged.
+ *
+ * That is the point of putting it here rather than writing a bespoke chat for
+ * in-browser agents. There is nothing chat-shaped about the browser harness —
+ * only a different answer to "where does the loop turn" — so it belongs at the
+ * one seam the package already has for that question.
+ *
+ * **Who executes the tools.** In every other adapter the runtime asks and the
+ * client answers: a `tool-call` arrives, `ChatBase` runs the frontend tool's
+ * handler and posts the result back with {@link sendToolResult}. Here the SDK
+ * owns the loop and calls the handler itself, so a host must NOT also pass
+ * `frontendTools` to the chat component — the tools go to this adapter, and the
+ * chat is left to render what happened. {@link sendToolResult} is therefore a
+ * no-op: by the time anyone could call it, the tool has already run.
+ *
+ * @module protocols/BrowserAgentAdapter
+ */
+import { streamText, stepCountIs } from 'ai';
+import { createAssistantMessage, generateMessageId } from '../types/messages';
+import { BaseProtocolAdapter } from './BaseProtocolAdapter';
+import { createBrowserModel, frontendToolsToVercelAI, subagentTools, DEFAULT_BROWSER_MAX_STEPS, } from '../runtimes/browser';
+/** The text of a chat message, whatever shape it arrived in. */
+function messageText(message) {
+    if (typeof message.content === 'string') {
+        return message.content;
+    }
+    return message.content
+        .map(part => typeof part === 'string'
+        ? part
+        : (part.text ?? ''))
+        .join('');
+}
+/** The roles a model can be sent. Everything else is presentation. */
+function isModelRole(role) {
+    return role === 'user' || role === 'assistant' || role === 'system';
+}
+/**
+ * An agent loop running in the page, speaking the protocol adapter interface.
+ */
+export class BrowserAgentAdapter extends BaseProtocolAdapter {
+    protocol = 'browser-vercel-ai';
+    protocolTransport = 'http';
+    browserConfig;
+    abortController = null;
+    tools;
+    constructor(config) {
+        super(config);
+        this.browserConfig = config;
+        const page = frontendToolsToVercelAI(config.frontendTools ?? [], {
+            onHitlRequired: config.onHitlRequired,
+            onStatusChange: config.onStatusChange,
+        });
+        // One set: to the model there is no difference between reaching into the
+        // page and reaching another agent — both are tools it may call, and the
+        // names are what it chooses between.
+        this.tools = {
+            ...page,
+            ...(config.subagents?.length && config.inference
+                ? subagentTools({
+                    subagents: config.subagents,
+                    inference: config.inference,
+                    model: config.model,
+                    sharing: config.sharing,
+                    // A member reached by delegation works in this page too, with
+                    // the same tools as the one that delegated.
+                    tools: page,
+                    onEvent: config.onSubagentEvent,
+                    // The run being stopped stops its delegations too.
+                    signal: () => this.abortController?.signal,
+                })
+                : {}),
+        };
+    }
+    /**
+     * Nothing to dial.
+     *
+     * The interface asks for a connection because the other adapters have one.
+     * This reports connected because the loop is already here.
+     */
+    async connect() {
+        this.setConnectionState('connected');
+    }
+    disconnect() {
+        this.abortController?.abort();
+        this.abortController = null;
+        this.setConnectionState('disconnected');
+    }
+    /**
+     * Stop the run in flight, and stay connected.
+     *
+     * What the chat's stop button calls on an adapter that has it. The other
+     * adapters cut a network stream; this one cuts the model call turning in
+     * the page — and, through the signal every delegation reads, the
+     * subagents that call started. Without this the button stopped the
+     * chat's *display* of the run and nothing else: the parent kept calling
+     * the model and the children kept working.
+     */
+    stopGeneration() {
+        this.abortController?.abort();
+    }
+    supportsFeature(feature) {
+        // Tools, yes — they are the whole point. Not the rest: there is no server
+        // to hold a thread, resume a run, or approve anything out of band.
+        return feature === 'tools';
+    }
+    /**
+     * Already done.
+     *
+     * The SDK executed the tool before this adapter reported it, so there is no
+     * result to carry back and nothing to resume. Kept because the interface has
+     * it and a host should not have to know which adapter it is holding.
+     */
+    async sendToolResult() { }
+    /**
+     * The model this agent asks, resolved once per request.
+     *
+     * The chat's model menu sends its choice with each message, as it does to
+     * a server-side harness; here it names the model the inference service is
+     * asked for, over the one the agent was built with. A ready-made
+     * `languageModel` is the host's own choice and is not swapped out.
+     */
+    resolveModel(requested) {
+        const { languageModel, inference, model } = this.browserConfig;
+        if (languageModel) {
+            return languageModel;
+        }
+        if (!inference) {
+            throw new Error('A browser agent needs either a `languageModel` or an `inference` endpoint to reach one.');
+        }
+        return createBrowserModel({ ...inference, model: requested || model });
+    }
+    /**
+     * Run one turn of the loop and report it as it happens.
+     *
+     * The SDK's `fullStream` is already the event stream this interface wants —
+     * text deltas, tool calls, tool results, a finish — so the body of this is a
+     * translation rather than a protocol implementation.
+     */
+    async sendMessage(message, options) {
+        this.abortController?.abort();
+        const abortController = new AbortController();
+        this.abortController = abortController;
+        // The history the chat is showing, minus anything the model has no role
+        // for — tool-call entries and activity items are presentation.
+        const history = (options?.messages ?? [])
+            .filter(entry => isModelRole(entry.role))
+            .map(entry => ({
+            role: entry.role,
+            content: messageText(entry),
+        }))
+            .filter(entry => entry.content.length > 0);
+        const latest = messageText(message);
+        if (latest && history[history.length - 1]?.content !== latest) {
+            history.push({ role: 'user', content: latest });
+        }
+        /*
+         * One message per text block, and an id of our own for each.
+         *
+         * A tool-using turn is several blocks: the model says what it is about to
+         * do, calls a tool, then says what it found. The SDK marks each with
+         * `text-start`, and the chat keys on the message id — same id replaces in
+         * place, a new id appends. Accumulating a whole turn under one id folded
+         * everything said after a tool call back into the sentence before it.
+         *
+         * The id must not be the provider's, either. `text-start` carries a block
+         * id that is unique only *within* a response — commonly "0" — so reusing
+         * it across turns made the second turn's text replace the first turn's
+         * message, which the chat then showed above the question that prompted it.
+         * Ours are unique for the life of the page, which is the scope the chat's
+         * message list actually has.
+         */
+        let messageId = null;
+        let text = '';
+        /** Begin a new assistant message. */
+        const startBlock = () => {
+            messageId = generateMessageId();
+            text = '';
+        };
+        /** Emit the assistant message as it stands, so the chat can stream it. */
+        const emitText = () => {
+            const assistant = createAssistantMessage(text);
+            assistant.id = messageId;
+            this.emit({ type: 'message', message: assistant, timestamp: new Date() });
+        };
+        try {
+            const result = streamText({
+                model: this.resolveModel(options?.model),
+                system: this.browserConfig.instructions,
+                messages: history,
+                tools: this.tools,
+                stopWhen: stepCountIs(this.browserConfig.maxSteps ?? DEFAULT_BROWSER_MAX_STEPS),
+                abortSignal: abortController.signal,
+            });
+            for await (const part of result.fullStream) {
+                if (abortController.signal.aborted) {
+                    break;
+                }
+                switch (part.type) {
+                    case 'text-start':
+                        // A new block: whatever follows belongs to a message of its own,
+                        // after any tool the previous block called.
+                        startBlock();
+                        break;
+                    case 'text-delta':
+                        // Defensively: a provider that streams text without announcing a
+                        // block still gets a message rather than losing its words.
+                        if (messageId === null) {
+                            startBlock();
+                        }
+                        text += part.text;
+                        emitText();
+                        break;
+                    case 'tool-call':
+                        this.emit({
+                            type: 'tool-call',
+                            toolCall: {
+                                toolCallId: part.toolCallId,
+                                toolName: part.toolName,
+                                args: (part.input ?? {}),
+                                // The SDK hands over a whole argument set in one part; unlike
+                                // AG-UI, nothing more is coming.
+                                argsComplete: true,
+                            },
+                            timestamp: new Date(),
+                        });
+                        break;
+                    case 'tool-result':
+                        this.emit({
+                            type: 'tool-result',
+                            toolResult: {
+                                toolCallId: part.toolCallId,
+                                success: true,
+                                result: part.output,
+                            },
+                            timestamp: new Date(),
+                        });
+                        break;
+                    case 'tool-error':
+                        this.emit({
+                            type: 'tool-result',
+                            toolResult: {
+                                toolCallId: part.toolCallId,
+                                success: false,
+                                error: part.error instanceof Error
+                                    ? part.error.message
+                                    : String(part.error),
+                            },
+                            timestamp: new Date(),
+                        });
+                        break;
+                    case 'error':
+                        this.emit({
+                            type: 'error',
+                            error: part.error instanceof Error
+                                ? part.error
+                                : new Error(String(part.error)),
+                            timestamp: new Date(),
+                        });
+                        break;
+                    case 'finish': {
+                        /*
+                         * Whatever the provider counted, summed when it did not total.
+                         *
+                         * The SDK's `totalUsage` fields are all optional, and a
+                         * provider that reports the parts but not the sum used to leave
+                         * `totalTokens` undefined — which is the one field the chat's
+                         * local accounting keys on, so the usage bar read 0 for turns
+                         * that were counted perfectly well.
+                         */
+                        const counted = part.totalUsage;
+                        const promptTokens = counted?.inputTokens ?? 0;
+                        const completionTokens = counted?.outputTokens ?? 0;
+                        const totalTokens = counted?.totalTokens ??
+                            (promptTokens + completionTokens > 0
+                                ? promptTokens + completionTokens
+                                : undefined);
+                        this.emit({
+                            type: 'done',
+                            usage: { promptTokens, completionTokens, totalTokens },
+                            timestamp: new Date(),
+                        });
+                        break;
+                    }
+                    default:
+                        break;
+                }
+            }
+        }
+        catch (error) {
+            if (abortController.signal.aborted) {
+                return;
+            }
+            this.emit({
+                type: 'error',
+                error: error instanceof Error ? error : new Error(String(error)),
+                timestamp: new Date(),
+            });
+            this.emit({ type: 'done', timestamp: new Date() });
+        }
+        finally {
+            if (this.abortController === abortController) {
+                this.abortController = null;
+            }
+        }
+    }
+}

package/lib/protocols/VercelAIAdapter.d.ts

@@ -36,6 +36,16 @@ export declare class VercelAIAdapter extends BaseProtocolAdapter {
     readonly protocolTransport: "sse";
     private vercelConfig;
     private abortController;
+    /**
+     * Every in-flight request's abort controller, not just the newest.
+     *
+     * `abortController` is a single field that each request overwrites, and each
+     * request's `finally` used to clear it unconditionally — so a request that
+     * finished just after a newer one started would null the newer one's handle,
+     * and a subsequent stop had nothing left to abort. The stream carried on and
+     * the transcript went on typing itself after the reader had asked it not to.
+     */
+    private inFlight;
     private currentRequestId;
     private pendingToolCalls;
     private collectedToolResults;

package/lib/protocols/VercelAIAdapter.js

@@ -14,6 +14,16 @@ export class VercelAIAdapter extends BaseProtocolAdapter {
     protocolTransport = 'sse';
     vercelConfig;
     abortController = null;
+    /**
+     * Every in-flight request's abort controller, not just the newest.
+     *
+     * `abortController` is a single field that each request overwrites, and each
+     * request's `finally` used to clear it unconditionally — so a request that
+     * finished just after a newer one started would null the newer one's handle,
+     * and a subsequent stop had nothing left to abort. The stream carried on and
+     * the transcript went on typing itself after the reader had asked it not to.
+     */
+    inFlight = new Set();
     currentRequestId = null;
     // Frontend tool continuation state (modelled after AGUIAdapter)
     pendingToolCalls = new Map();
@@ -113,10 +123,14 @@ export class VercelAIAdapter extends BaseProtocolAdapter {
      * Send a message using Vercel AI Data Stream Protocol
      */
     async sendMessage(message, options) {
-        if (this.abortController) {
-            this.abortController.abort();
-        }
-        this.abortController = new AbortController();
+        // A new send supersedes what came before it — all of it. Aborting only
+        // the field left any stream it had already lost track of still running.
+        this.stopGeneration();
+        // Held in a local too: by the time the `finally` runs, a later request may
+        // own the field, and this one must only retire its own controller.
+        const controller = new AbortController();
+        this.abortController = controller;
+        this.inFlight.add(controller);
         // Generate request ID for tracking
         const requestId = options?.threadId || generateMessageId();
         this.currentRequestId = requestId;
@@ -238,7 +252,7 @@ export class VercelAIAdapter extends BaseProtocolAdapter {
                 method: 'POST',
                 headers,
                 body: JSON.stringify(requestBody),
-                signal: this.abortController.signal,
+                signal: controller.signal,
                 mode: this.vercelConfig.fetchOptions?.mode,
                 credentials: this.vercelConfig.fetchOptions?.credentials,
             });
@@ -258,7 +272,10 @@ export class VercelAIAdapter extends BaseProtocolAdapter {
             }
         }
         finally {
-            this.abortController = null;
+            this.inFlight.delete(controller);
+            if (this.abortController === controller) {
+                this.abortController = null;
+            }
         }
     }
     /**
@@ -797,7 +814,10 @@ export class VercelAIAdapter extends BaseProtocolAdapter {
      * Stop generation
      */
     stopGeneration() {
-        this.abortController?.abort();
+        for (const controller of this.inFlight) {
+            controller.abort();
+        }
+        this.inFlight.clear();
         this.abortController = null;
     }
 }

package/lib/protocols/index.d.ts

@@ -7,4 +7,5 @@ export { BaseProtocolAdapter } from './BaseProtocolAdapter';
 export { AGUIAdapter, type AGUIAdapterConfig } from './AGUIAdapter';
 export { A2AAdapter, type A2AAdapterConfig } from './A2AAdapter';
 export { VercelAIAdapter, type VercelAIAdapterConfig } from './VercelAIAdapter';
+export { BrowserAgentAdapter, type BrowserAgentAdapterConfig, } from './BrowserAgentAdapter';
 export { ACPAdapter, type ACPAdapterConfig, type ACPSession, type ACPAgent, type ACPPendingPermission, } from './ACPAdapter';

package/lib/protocols/index.js

@@ -11,4 +11,5 @@ export { BaseProtocolAdapter } from './BaseProtocolAdapter';
 export { AGUIAdapter } from './AGUIAdapter';
 export { A2AAdapter } from './A2AAdapter';
 export { VercelAIAdapter } from './VercelAIAdapter';
+export { BrowserAgentAdapter, } from './BrowserAgentAdapter';
 export { ACPAdapter, } from './ACPAdapter';

package/lib/runtimes/actions.d.ts

@@ -1,5 +1,5 @@
 import type { IRuntimeOptions } from './apis';
-import type { ICodeSandboxSnapshot, IDatalayerEnvironment, IRuntimePod } from '../models';
+import type { ICodeSandboxSnapshot, IDatalayerEnvironment, IRuntimeRecord } from '../models';
 /**
  * Get available Environments.
  */
@@ -7,11 +7,16 @@ export declare function getEnvironments(): Promise<IDatalayerEnvironment[]>;
 /**
  * Create a Runtime.
  */
-export declare function createRuntime(options: IRuntimeOptions): Promise<IRuntimePod>;
+export declare function createRuntime(options: IRuntimeOptions): Promise<IRuntimeRecord>;
 /**
  * Get the Runtimes.
  */
-export declare function getRuntimes(): Promise<IRuntimePod[]>;
+export declare function getRuntimes(): Promise<IRuntimeRecord[]>;
+/**
+ * One runtime as the platform answers it now — why its pod waits included —
+ * or `null` when there is none by that uid (E2-19).
+ */
+export declare function getRuntimeRecord(id: string): Promise<IRuntimeRecord | null>;
 /**
  * Delete a Runtime
  */