@datalayer/agent-runtimes 1.0.29 → 1.3.10

package/lib/protocols/BrowserAgentAdapter.js

@@ -0,0 +1,310 @@
+/*
+ * 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. */
+    resolveModel() {
+        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 });
+    }
+    /**
+     * 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(),
+                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,11 @@ 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[]>;
 /**
  * Delete a Runtime
  */

package/lib/runtimes/actions.js

@@ -9,6 +9,7 @@ import { URLExt } from '@jupyterlab/coreutils';
 import { PromiseDelegate } from '@lumino/coreutils';
 import { Upload } from 'tus-js-client';
 import { requestDatalayerAPI } from '@datalayer/core/lib/api';
+import { runtimeUrl, runtimesUrl, sandboxSnapshotUrl, sandboxSnapshotsUrl, } from './lifecycle';
 import { asCodeSandboxSnapshot } from '../models';
 import { iamStore, runtimesStore } from '../state/substates';
 /**
@@ -48,10 +49,22 @@ export async function createRuntime(options) {
         throw new Error(`Invalid runtime creditsLimit for environment ${options.environmentName}. ` +
             'A number of zero or more is required.');
     }
+    /*
+     * `environment: {name, version}` — and the version is ADDITIVE.
+     *
+     * Without one this is, byte for byte, the request every runtime has been
+     * launched with since before user environments existed, and the platform
+     * resolves the promoted version itself (PLAN_ENV.md, §7.6, D-2, E1-11).
+     */
+    const environment = {
+        name: options.environmentName,
+    };
+    if (options.environmentVersion !== undefined &&
+        options.environmentVersion !== '') {
+        environment['version'] = options.environmentVersion;
+    }
     const body = {
-        environment: {
-            name: options.environmentName,
-        },
+        environment,
         type: options.type ?? 'notebook',
         given_name: options.givenName,
         credits_limit: options.creditsLimit,
@@ -63,7 +76,7 @@ export async function createRuntime(options) {
         body['from'] = options.snapshot;
     }
     const data = await requestDatalayerAPI({
-        url: URLExt.join(runtimesStore.getState().runtimesUrl, `api/runtimes/v1/runtimes`),
+        url: runtimesUrl(runtimesStore.getState().runtimesUrl),
         method: 'POST',
         body,
         token: token,
@@ -86,7 +99,7 @@ export async function createRuntime(options) {
  */
 export async function getRuntimes() {
     const data = await requestDatalayerAPI({
-        url: URLExt.join(runtimesStore.getState().runtimesUrl, 'api/runtimes/v1/runtimes'),
+        url: runtimesUrl(runtimesStore.getState().runtimesUrl),
         token: iamStore.getState().token,
     });
     if (!data.success) {
@@ -102,7 +115,7 @@ export async function getRuntimes() {
 export async function deleteRuntime(options) {
     const externalToken = iamStore.getState().externalToken;
     await requestDatalayerAPI({
-        url: URLExt.join(runtimesStore.getState().runtimesUrl, `api/runtimes/v1/runtimes/${options.id}`) +
+        url: runtimeUrl(runtimesStore.getState().runtimesUrl, options.id) +
             URLExt.objectToQueryString(options.reason ? { reason: options.reason } : {}),
         method: 'DELETE',
         token: iamStore.getState().token,
@@ -119,10 +132,10 @@ export async function deleteRuntime(options) {
  */
 export async function snapshotRuntime(options) {
     const data = await requestDatalayerAPI({
-        url: URLExt.join(runtimesStore.getState().runtimesUrl, 'api/runtimes/v1/sandbox-snapshots'),
+        url: sandboxSnapshotsUrl(runtimesStore.getState().runtimesUrl),
         method: 'POST',
         body: {
-            pod_name: options.id,
+            runtime_name: options.id,
             name: options.name,
             description: options.description,
             stop: options.stop,
@@ -144,7 +157,7 @@ export async function snapshotRuntime(options) {
  */
 export async function getSandboxSnapshots() {
     const data = await requestDatalayerAPI({
-        url: URLExt.join(runtimesStore.getState().runtimesUrl, 'api/runtimes/v1/sandbox-snapshots'),
+        url: sandboxSnapshotsUrl(runtimesStore.getState().runtimesUrl),
         token: iamStore.getState().token,
     });
     if (!data.success) {
@@ -158,7 +171,7 @@ export async function getSandboxSnapshots() {
  */
 export async function loadSandboxSnapshot(options) {
     const data = await requestDatalayerAPI({
-        url: URLExt.join(runtimesStore.getState().runtimesUrl, 'api/runtimes/v1/runtimes', options.id),
+        url: runtimeUrl(runtimesStore.getState().runtimesUrl, options.id),
         method: 'PUT',
         body: {
             from: options.from,
@@ -176,7 +189,7 @@ export async function loadSandboxSnapshot(options) {
  * @returns The download URL
  */
 export function createSandboxSnapshotDownloadURL(id) {
-    return (URLExt.join(runtimesStore.getState().runtimesUrl, `api/runtimes/v1/sandbox-snapshots/${id}`) +
+    return (sandboxSnapshotUrl(runtimesStore.getState().runtimesUrl, id) +
         URLExt.objectToQueryString({
             download: '1',
             token: iamStore.getState().token ?? '',
@@ -201,7 +214,7 @@ export function exportCodeSandboxSnapshot(id) {
  */
 export async function deleteCodeSandboxSnapshot(id) {
     await requestDatalayerAPI({
-        url: URLExt.join(runtimesStore.getState().runtimesUrl, `api/runtimes/v1/sandbox-snapshots/${id}`),
+        url: sandboxSnapshotUrl(runtimesStore.getState().runtimesUrl, id),
         method: 'DELETE',
         token: iamStore.getState().token,
     });
@@ -212,7 +225,7 @@ export async function deleteCodeSandboxSnapshot(id) {
 export async function updateCodeSandboxSnapshot(id, metadata) {
     if (metadata.name || metadata.description) {
         await requestDatalayerAPI({
-            url: URLExt.join(runtimesStore.getState().runtimesUrl, `api/runtimes/v1/sandbox-snapshots/${id}`),
+            url: sandboxSnapshotUrl(runtimesStore.getState().runtimesUrl, id),
             method: 'PATCH',
             body: { ...metadata },
             token: iamStore.getState().token,
@@ -232,7 +245,7 @@ export async function uploadCodeSandboxSnapshot(options) {
     // Create a new tus upload.
     const upload = new Upload(options.file, {
         // Endpoint is the upload creation URL from your tus server.
-        endpoint: `${runtimesStore.getState().runtimesUrl}/api/runtimes/v1/sandbox-snapshots/upload`,
+        endpoint: `${sandboxSnapshotsUrl(runtimesStore.getState().runtimesUrl)}/upload`,
         headers: { Authorization: `Bearer ${iamStore.getState().token}` },
         // Retry delays will enable tus-js-client to automatically retry on errors.
         // retryDelays: [0, 3000, 5000, 10000, 20000],

package/lib/runtimes/apis.d.ts

@@ -20,8 +20,17 @@ export interface IDatalayerSessionContext extends ISessionContext {
 export interface IRuntimeOptions {
     /**
      * Environment name
+     *
+     * A platform environment by its name, or an environment somebody built,
+     * named `<account-handle>/<name>` or by its uid (PLAN_ENV.md, D-2).
      */
     environmentName: string;
+    /**
+     * Which version of a user environment to launch: its number, or a version
+     * uid. Absent means the version its owner promoted, which is what a platform
+     * environment always runs (E1-19).
+     */
+    environmentVersion?: number | string;
     /**
      * Credits limit to be consumed by the kernel
      */
@@ -169,7 +178,7 @@ export interface IRemoteRuntimesManager extends IDisposable {
     /**
      * Snapshot a runtime
      *
-     * The runtime may be given by its `id` or `podName`.
+     * The runtime may be given by its `id` or `runtimeName`.
      * A custom description for the snapshot can be provided.
      *
      * @returns The snapshot description
@@ -182,7 +191,7 @@ export interface IRemoteRuntimesManager extends IDisposable {
         /**
          * The kernel pod name to snapshot
          */
-        podName?: string;
+        runtimeName?: string;
         /**
          * The snapshot name
          */
@@ -199,7 +208,7 @@ export interface IRemoteRuntimesManager extends IDisposable {
     /**
      * Load a snapshot within a runtim
      *
-     * The runtime may be given by its `id` or `podName`.
+     * The runtime may be given by its `id` or `runtimeName`.
      */
     loadSandboxSnapshot(options: {
         /**
@@ -209,7 +218,7 @@ export interface IRemoteRuntimesManager extends IDisposable {
         /**
          * The kernel pod name
          */
-        podName?: string;
+        runtimeName?: string;
         /**
          * The snapshot UID
          */

package/lib/runtimes/browser/agent.d.ts

@@ -0,0 +1,54 @@
+/**
+ * An agent loop that turns in the page.
+ *
+ * The server-side harness reads a spec and builds a pydantic-ai agent from it.
+ * This reads the same spec and builds a Vercel AI SDK agent from it — same
+ * prompt, same model name, same tools, different thing turning the loop.
+ *
+ * What a browser agent does *not* get comes from the spec too, and it is not a
+ * limitation this module has to enforce: a spec written for this harness
+ * declares no MCP servers, no sandbox and no codemode, because none of them
+ * exist without a server. All that is left is the frontend tools, and those
+ * were always the ones that ran here anyway.
+ *
+ * @module runtimes/browser/agent
+ */
+import { ToolLoopAgent, type LanguageModel } from 'ai';
+import type { Agentspec } from '../../types/agentspecs';
+import type { FrontendToolDefinition } from '../../types/tools';
+import { type FrontendToolsToVercelAIOptions } from './frontendTools';
+import { type BrowserModelOptions } from './model';
+/**
+ * How many model turns one request may take.
+ *
+ * A compaction reads a notebook cell by cell and then edits it, so the loop
+ * needs room — but it is running against a person's own page with nothing
+ * between it and a bill, so it needs a ceiling too.
+ */
+export declare const DEFAULT_BROWSER_MAX_STEPS = 24;
+export type CreateBrowserAgentOptions = FrontendToolsToVercelAIOptions & {
+    /** The spec to run. Its prompt, model and identity are used as written. */
+    spec: Pick<Agentspec, 'id' | 'model' | 'systemPrompt'>;
+    /**
+     * The tools the agent can call, in this page.
+     *
+     * The same array a host passes to `<Chat frontendTools={...}>` — from
+     * `useNotebookTools`, `useLexicalTools`, or hand-written.
+     */
+    frontendTools: FrontendToolDefinition[];
+    /** Where to reach the model, unless one is supplied outright. */
+    inference?: Omit<BrowserModelOptions, 'model'>;
+    /** A ready-made model, for a host that resolves models its own way. */
+    model?: LanguageModel;
+    /** Turn ceiling for one request. @see DEFAULT_BROWSER_MAX_STEPS */
+    maxSteps?: number;
+};
+/**
+ * Build the agent a browser variant runs.
+ *
+ * The result is an SDK agent, so it drops straight into `DirectChatTransport`
+ * and from there into the same `useChat` the rest of the chat UI is built on
+ * — which is why nothing downstream of the transport has to know which
+ * harness produced its messages.
+ */
+export declare function createBrowserAgent(options: CreateBrowserAgentOptions): ToolLoopAgent;