@datalayer/agent-runtimes 1.0.29 → 1.3.10

package/lib/runtimes/browser/frontendTools.js

@@ -0,0 +1,152 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * Frontend tools, as the Vercel AI SDK wants them.
+ *
+ * This is the piece that makes an in-browser agent worth having. A
+ * {@link FrontendToolDefinition} is a tool that runs in the page — it reaches
+ * into the notebook the reader is looking at, or the document they are
+ * editing — and the AG-UI path has always been able to call them: the client
+ * advertises `{name, description, parameters}` to the runtime, the model asks
+ * for one, and the client runs its `handler`.
+ *
+ * The browser harness needs exactly the same tools to work, and they do,
+ * because nothing about a frontend tool was ever server-shaped. What changes
+ * is only the round trip: AG-UI advertises the tool over the wire and posts
+ * the result back, while here the model call and the handler are in the same
+ * page, so the SDK calls the handler itself.
+ *
+ * So this module is a translation and not a second implementation:
+ *
+ * - the same array of definitions a host already passes to `<Chat>`
+ * - the same {@link ToolExecutor} underneath, so location routing,
+ *   human-in-the-loop and status reporting behave identically
+ * - the same JSON Schema the AG-UI path sends over the wire
+ *
+ * A host that has tools working in one harness gets them working in the other
+ * by passing the same array.
+ *
+ * @module runtimes/browser/frontendTools
+ */
+// From `ai` rather than `@ai-sdk/provider-utils` directly. `ai` re-exports
+// these from the copy of provider-utils it resolves itself, and a schema built
+// against a different copy is not the same type to TypeScript — the identity
+// is carried by a private symbol.
+import { jsonSchema, tool } from 'ai';
+import { createToolExecutor } from '../../tools/ToolExecutor';
+/** JSON Schema for a tool that takes nothing. */
+const NO_PARAMETERS = { type: 'object', properties: {} };
+/** The JSON Schema type for one of the shorthand parameter types. */
+function schemaForParameter(parameter) {
+    const described = parameter.description
+        ? { description: parameter.description }
+        : {};
+    const enumerated = parameter.enum ? { enum: parameter.enum } : {};
+    const base = { ...described, ...enumerated };
+    switch (parameter.type) {
+        case 'string[]':
+            return { ...base, type: 'array', items: { type: 'string' } };
+        case 'number[]':
+            return { ...base, type: 'array', items: { type: 'number' } };
+        case 'object[]':
+            return {
+                ...base,
+                type: 'array',
+                items: objectSchema(parameter.attributes),
+            };
+        case 'object':
+            return { ...base, ...objectSchema(parameter.attributes) };
+        default:
+            return { ...base, type: parameter.type ?? 'string' };
+    }
+}
+/** An object schema built from a nested attribute list. */
+function objectSchema(attributes) {
+    if (!attributes?.length) {
+        return { type: 'object', properties: {} };
+    }
+    return { type: 'object', ...parametersToSchema(attributes) };
+}
+/** The `properties`/`required` pair for a list of parameters. */
+function parametersToSchema(parameters) {
+    const properties = {};
+    const required = [];
+    for (const parameter of parameters) {
+        properties[parameter.name] = schemaForParameter(parameter);
+        if (parameter.required) {
+            required.push(parameter.name);
+        }
+    }
+    return required.length ? { properties, required } : { properties };
+}
+/**
+ * The JSON Schema for a tool's input.
+ *
+ * `parameters` comes in two shapes, because two ecosystems put it there: the
+ * notebook and document tools carry JSON Schema already, and CopilotKit-style
+ * definitions carry a `ToolParameter[]`. The AG-UI path sends whichever it
+ * finds straight over the wire; this does the same conversion so a tool
+ * describes itself identically to a model in either harness.
+ */
+export function toolInputSchema(definition) {
+    const parameters = definition.parameters;
+    if (!parameters) {
+        return { ...NO_PARAMETERS };
+    }
+    if (Array.isArray(parameters)) {
+        return { type: 'object', ...parametersToSchema(parameters) };
+    }
+    // Already JSON Schema. Passed through rather than rebuilt: it is the tool
+    // author's own description of the tool, and rewriting it could only lose
+    // something the model was meant to see.
+    return parameters;
+}
+/**
+ * Turn frontend tools into a Vercel AI SDK tool set.
+ *
+ * Errors come back as tool output rather than thrown. A throw would abort the
+ * whole generation over one bad call; an error the model can read is a step it
+ * can recover from — it can try a different cell, or tell the person what went
+ * wrong. This is what the AG-UI path does with a failed tool result too.
+ */
+export function frontendToolsToVercelAI(frontendTools, options = {}) {
+    const byName = new Map(frontendTools.map(entry => [entry.name, entry]));
+    // The same executor the rest of the package uses. It owns the parts that
+    // must not drift between harnesses: frontend/backend routing, the HITL
+    // pause, and the status callbacks a host renders progress from.
+    const executor = createToolExecutor({
+        getToolDefinition: (name) => byName.get(name),
+        onHitlRequired: options.onHitlRequired,
+        onStatusChange: options.onStatusChange,
+    });
+    const toolSet = {};
+    for (const definition of frontendTools) {
+        toolSet[definition.name] = tool({
+            description: definition.description,
+            inputSchema: jsonSchema(toolInputSchema(definition)),
+            execute: async (input, executionOptions) => {
+                const result = await executor.execute({
+                    toolCallId: executionOptions?.toolCallId ?? definition.name,
+                    toolName: definition.name,
+                    args: (input ?? {}),
+                    // The SDK hands over a complete argument set: unlike AG-UI, which
+                    // streams arguments and emits a first call with none, a tool call
+                    // here arrives once and whole.
+                    argsComplete: true,
+                });
+                if (!result.success) {
+                    return { error: result.error ?? 'The tool call failed.' };
+                }
+                return result.result ?? null;
+            },
+        });
+    }
+    return toolSet;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * The browser harness: an agent loop that runs in the page.
+ *
+ * @module runtimes/browser
+ */
+export * from './agent';
+export * from './anonymousToken';
+export * from './frontendTools';
+export * from './model';
+export * from './protocol';
+export * from './subagents';

package/lib/runtimes/browser/index.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * The browser harness: an agent loop that runs in the page.
+ *
+ * @module runtimes/browser
+ */
+export * from './agent';
+export * from './anonymousToken';
+export * from './frontendTools';
+export * from './model';
+export * from './protocol';
+export * from './subagents';

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

@@ -0,0 +1,52 @@
+import type { LanguageModel } from 'ai';
+/** Where the inference service's OpenAI-compatible API lives under its host. */
+export declare const INFERENCE_API_PATH = "/api/ai-inference/v1";
+/**
+ * The model a spec asks for when it says nothing.
+ *
+ * Matches the specs written for this harness rather than being a general
+ * default, so a caller that forgets to pass one still gets a working agent
+ * instead of a 404 from a model nobody provisioned.
+ */
+export declare const DEFAULT_BROWSER_MODEL = "bedrock:us.anthropic.claude-sonnet-4-6";
+export type BrowserModelOptions = {
+    /**
+     * Base URL of the inference service — `configuration.aiInferenceUrl`.
+     *
+     * The `/api/ai-inference/v1` suffix is added when it is not already there,
+     * so a caller can pass either the host or the full API root.
+     */
+    inferenceUrl: string;
+    /** The model id, as a spec spells it. */
+    model?: string;
+    /**
+     * The signed-in person's Datalayer token.
+     *
+     * Required in practice: the inference service admits platform members only.
+     * Optional in the type so a host can build the model before the token has
+     * arrived, and {@link browserModelRequiresSignIn} is the check to make
+     * before offering the agent rather than letting it fail on the first turn.
+     */
+    token?: string;
+    /** Extra headers, for a host that authenticates some other way. */
+    headers?: Record<string, string>;
+    /** Custom fetch, for tests and for hosts that wrap the network. */
+    fetch?: typeof globalThis.fetch;
+};
+/**
+ * Whether this agent would be refused for want of a sign-in.
+ *
+ * Worth asking before showing a chat: an agent that answers every message with
+ * a 401 is worse than one a host had the sense not to offer.
+ */
+export declare function browserModelRequiresSignIn(options: Pick<BrowserModelOptions, 'token'>): boolean;
+/** The API root for an inference host, given either form of the URL. */
+export declare function inferenceApiUrl(inferenceUrl: string): string;
+/**
+ * A language model that answers from the inference service.
+ *
+ * `.chat()` rather than the provider's default: that is the
+ * `/chat/completions` endpoint, which is the one the inference service
+ * normalises tools and model names for.
+ */
+export declare function createBrowserModel(options: BrowserModelOptions): LanguageModel;

package/lib/runtimes/browser/model.js

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * The model a browser agent talks to.
+ *
+ * A page cannot hold an AWS credential, so an in-browser agent does not reach
+ * Bedrock directly — it reaches the Datalayer inference service, which is
+ * OpenAI-compatible, holds the AWS credentials on the other side, and routes
+ * to Bedrock through LiteLLM. The SDK's OpenAI provider pointed at that base
+ * URL is the whole of it.
+ *
+ * **The service authenticates.** Every route on it requires a platform member,
+ * so a browser agent needs the signed-in person's Datalayer token and is
+ * refused with a 401 without one. This is the one thing an in-browser agent
+ * cannot do without a server: no runtime, no sandbox, but still an account.
+ * {@link createBrowserModel} sends the token as the bearer credential, so the
+ * request is attributed to the person making it and their usage is metered
+ * like any other.
+ *
+ * The model *name* needs no translation. A spec writes
+ * `bedrock:us.anthropic.claude-sonnet-4-6`, and the inference service already
+ * normalises that prefix for LiteLLM — the same string the server-side harness
+ * sends. Both harnesses name a model identically, which is what keeps one spec
+ * runnable in either.
+ *
+ * @module runtimes/browser/model
+ */
+import { createOpenAI } from '@ai-sdk/openai';
+/** Where the inference service's OpenAI-compatible API lives under its host. */
+export const INFERENCE_API_PATH = '/api/ai-inference/v1';
+/**
+ * The model a spec asks for when it says nothing.
+ *
+ * Matches the specs written for this harness rather than being a general
+ * default, so a caller that forgets to pass one still gets a working agent
+ * instead of a 404 from a model nobody provisioned.
+ */
+export const DEFAULT_BROWSER_MODEL = 'bedrock:us.anthropic.claude-sonnet-4-6';
+/**
+ * Whether this agent would be refused for want of a sign-in.
+ *
+ * Worth asking before showing a chat: an agent that answers every message with
+ * a 401 is worse than one a host had the sense not to offer.
+ */
+export function browserModelRequiresSignIn(options) {
+    return !options.token?.trim();
+}
+/** The API root for an inference host, given either form of the URL. */
+export function inferenceApiUrl(inferenceUrl) {
+    const trimmed = inferenceUrl.replace(/\/+$/, '');
+    return trimmed.endsWith(INFERENCE_API_PATH)
+        ? trimmed
+        : `${trimmed}${INFERENCE_API_PATH}`;
+}
+/**
+ * A fetch that says which host it could not reach.
+ *
+ * A browser agent's most likely failure is that it is pointed at the wrong
+ * host — the inference service sits with the control plane, not on the
+ * runtimes plane, and a URL for the latter fails CORS preflight because it
+ * does not serve the route at all. What the SDK surfaces for that is
+ * `TypeError: Failed to fetch`, from a stack several libraries deep, naming
+ * nothing. This says what was being called.
+ */
+function describingFetch(base, apiUrl) {
+    return async (input, init) => {
+        try {
+            return await base(input, init);
+        }
+        catch (error) {
+            throw new Error(`Could not reach the inference service at ${apiUrl}. ` +
+                'Check that this is the right host — the service runs with the ' +
+                'control plane, not the runtimes plane — and that it allows this ' +
+                `origin. (${error instanceof Error ? error.message : String(error)})`, { cause: error });
+        }
+    };
+}
+/**
+ * A language model that answers from the inference service.
+ *
+ * `.chat()` rather than the provider's default: that is the
+ * `/chat/completions` endpoint, which is the one the inference service
+ * normalises tools and model names for.
+ */
+export function createBrowserModel(options) {
+    const apiUrl = inferenceApiUrl(options.inferenceUrl);
+    const provider = createOpenAI({
+        name: 'datalayer-ai-inference',
+        baseURL: apiUrl,
+        // Sent as `Authorization: Bearer <token>`, which is what the service's
+        // bearer scheme reads — so the completion is made as the signed-in person
+        // and attributed to them.
+        //
+        // The placeholder is for the signed-out case, where the provider would
+        // otherwise go looking for a key in an environment a browser does not
+        // have: the refusal then comes from the service, as a 401 a host can
+        // report, rather than from the SDK as a missing-configuration throw.
+        apiKey: options.token?.trim() || 'anonymous',
+        headers: options.headers,
+        fetch: describingFetch(options.fetch ?? globalThis.fetch, apiUrl),
+    });
+    return provider.chat(options.model || DEFAULT_BROWSER_MODEL);
+}

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

@@ -0,0 +1,54 @@
+/**
+ * How a chat is told to talk to an in-page agent.
+ *
+ * The shape belongs with the harness rather than with whoever renders a chat.
+ * It started in the examples, and then the LOOP workspace needed the identical
+ * thing — same fields, same reasons — which is the usual sign that a shape was
+ * living in the wrong place.
+ *
+ * @module runtimes/browser/protocol
+ */
+import type { ProtocolConfig } from '../../types/protocol';
+import type { AgentStreamSubagentPayload } from '../../types/stream';
+import type { FrontendToolDefinition } from '../../types/tools';
+import type { TeamContextSharing } from '../../types/teams';
+import type { BrowserModelOptions } from './model';
+import type { BrowserSubagent } from './subagents';
+export type BrowserProtocolOptions = {
+    /** The agent's id, for the chat to name it by. */
+    agentId: string;
+    /** The agent's instructions. */
+    instructions?: string;
+    /** The model id, as a spec spells it. */
+    model?: string;
+    /** The tools the agent may call in this page, if any. */
+    frontendTools?: FrontendToolDefinition[];
+    /** Where to reach a model. */
+    inference: Omit<BrowserModelOptions, 'model'>;
+    /**
+     * Agents this one may hand work to.
+     *
+     * Each becomes a tool named after it, so the model reaches for `Compactor`
+     * rather than `delegate_task('Compactor', …)`. What the child is told about
+     * the conversation is {@link sharing}.
+     */
+    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;
+};
+/**
+ * The protocol config for an agent whose loop runs in this page.
+ *
+ * Two fields carry the weight:
+ *
+ * - `endpoint` is empty and stays empty. There is nothing to address, and the
+ *   live objects travel in `options` — the seam `createProtocolAdapter` leaves
+ *   for an adapter whose configuration is not a URL.
+ * - `enableConfigQuery: false`, because models, tools and skills all come from
+ *   a runtime this agent does not have. Said explicitly rather than left
+ *   undefined: the composer waits on that query before it will accept a
+ *   keystroke, so an omitted flag reads as a chat that silently ignores typing.
+ */
+export declare function browserProtocolConfig(options: BrowserProtocolOptions): ProtocolConfig;

package/lib/runtimes/browser/protocol.js

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The protocol config for an agent whose loop runs in this page.
+ *
+ * Two fields carry the weight:
+ *
+ * - `endpoint` is empty and stays empty. There is nothing to address, and the
+ *   live objects travel in `options` — the seam `createProtocolAdapter` leaves
+ *   for an adapter whose configuration is not a URL.
+ * - `enableConfigQuery: false`, because models, tools and skills all come from
+ *   a runtime this agent does not have. Said explicitly rather than left
+ *   undefined: the composer waits on that query before it will accept a
+ *   keystroke, so an omitted flag reads as a chat that silently ignores typing.
+ */
+export function browserProtocolConfig(options) {
+    const { agentId, instructions, model, frontendTools, inference, subagents, sharing, onSubagentEvent, } = options;
+    return {
+        type: 'browser-vercel-ai',
+        endpoint: '',
+        agentId,
+        enableConfigQuery: false,
+        options: {
+            instructions,
+            model,
+            frontendTools,
+            inference,
+            subagents,
+            sharing,
+            onSubagentEvent,
+        },
+    };
+}

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

@@ -0,0 +1,131 @@
+/**
+ * Delegation, for an agent whose loop runs in the page.
+ *
+ * The server-side harness already has this: `subagents/capability.py`
+ * contributes a `delegate_task` tool to a pydantic-ai agent, runs the named
+ * subagent in a child run, and hands its final output back to the parent. This
+ * is the same idea in the browser, and deliberately built the way the Vercel AI
+ * SDK documents rather than reinvented:
+ *
+ * - a subagent is a {@link ToolLoopAgent}, the same class the parent is;
+ * - the parent reaches it through an ordinary `tool()` whose `execute` calls
+ *   `generate()` and returns the text;
+ * - what the parent's model sees is trimmed with `toModelOutput`.
+ *
+ * The one thing that is ours is *which conversation the child is given*. The
+ * SDK isolates by default and shows you how to pass `messages` instead; a
+ * teamspec says which of those a team wants, so the choice is read from the
+ * spec rather than decided here.
+ *
+ * One SDK constraint worth knowing: a subagent tool cannot take part in
+ * approval flows. A subagent that must be approved has to be a plain tool.
+ *
+ * @module runtimes/browser/subagents
+ */
+import { type ToolSet } from 'ai';
+import { type AgentStreamSubagentPayload } from '../../types/stream';
+import type { TeamContextSharing } from '../../types/teams';
+import { type BrowserModelOptions } from './model';
+/** How many turns a delegated task may take before it is stopped. */
+export declare const DEFAULT_SUBAGENT_MAX_STEPS = 12;
+/** One agent a parent may hand work to. */
+export type BrowserSubagent = {
+    /** The name the parent addresses it by. Becomes the tool name. */
+    name: string;
+    /** What it is for, and when to reach for it. Read by the parent's model. */
+    description: string;
+    /** Its instructions. */
+    instructions?: string;
+    /** Its model, as a spec spells it. Falls back to the parent's. */
+    model?: string;
+    /** Tools it may call in this page. Usually a narrower set than the parent's. */
+    tools?: ToolSet;
+    /**
+     * The octicon name its spec asked for.
+     *
+     * Carried, not used: the harness has no interface. It is here so a menu
+     * offering this subagent can draw it the same way it draws a team member,
+     * rather than the two disagreeing about what the same agent looks like.
+     */
+    icon?: string;
+};
+export type SubagentToolsOptions = {
+    subagents: BrowserSubagent[];
+    /** Where to reach a model. */
+    inference: Omit<BrowserModelOptions, 'model'>;
+    /** The parent's model, for a subagent that names none. */
+    model?: string;
+    /**
+     * What the child is told about the conversation so far.
+     *
+     * From the team's `context.sharing`. `shared` hands over the parent's
+     * messages and appends the task; anything else starts the child on the task
+     * alone — which is what the SDK does by default, and what a delegation model
+     * wants.
+     *
+     * `own-turns` collapses to isolated here on purpose: a subagent has no turns
+     * of its own to be given, so the honest reading of "only its own history" is
+     * "no history".
+     */
+    sharing?: TeamContextSharing;
+    /** Turn ceiling for one delegated task. */
+    maxSteps?: number;
+    /**
+     * Told what a delegated run does, as it does it.
+     *
+     * The same events the server-side harness puts on its monitoring stream —
+     * `start`, `text`, `tool_call`, `tool_result`, `end`, `error`, keyed by the
+     * parent's tool call — so whatever draws a delegation's progress (the
+     * side panel, the pulse in the composer) draws it the same whether the
+     * loop turns on a server or in this page.
+     */
+    onEvent?: (event: AgentStreamSubagentPayload) => void;
+    /**
+     * The page's tools, for a member that declares none of its own.
+     *
+     * A team's members all work in the page the person has open — the Reviewer
+     * re-runs the cells, Decks writes the deck — and a member reached by
+     * delegation is still that member. Without this a delegated task ran with
+     * no tools at all, and "ask the Reviewer to check this" came back as an
+     * opinion about cells it could not run. A subagent that names a narrower
+     * set of its own keeps it.
+     */
+    tools?: ToolSet;
+    /**
+     * The run's abort signal, read when a delegation starts.
+     *
+     * The SDK hands a tool the run's signal too, and the child listens to
+     * both: a person pressing stop must stop the child as surely as the
+     * parent, and a signal reached one way is as good as the other.
+     */
+    signal?: () => AbortSignal | undefined;
+};
+/**
+ * The tools a parent needs in order to delegate.
+ *
+ * One per subagent, named after it, so the model reaches for `Compactor`
+ * rather than for `delegate_task('Compactor', …)`. A name the model can read
+ * is a name it picks correctly more often, and the description is what it
+ * chooses on.
+ */
+export declare function subagentTools(options: SubagentToolsOptions): ToolSet;
+/** What a delegation says when the person stopped it. */
+export declare const STOPPED = "Stopped.";
+/** The parts of a streamed run this relays; the SDK's stream has more, which pass. */
+export type SubagentStreamPart = {
+    type: string;
+    text?: string;
+    toolName?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: unknown;
+};
+/**
+ * Turn a delegated run's stream into subagent events, and return its text.
+ *
+ * Text and reasoning deltas, tool calls and their results, and errors — the
+ * phases the server-side harness reports — each emitted as the part arrives.
+ * Everything else the SDK streams (step and finish markers, sources, files)
+ * is not a phase and passes in silence.
+ */
+export declare function relaySubagentRun(stream: AsyncIterable<SubagentStreamPart>, emit: (event: Omit<AgentStreamSubagentPayload, 'subagentName' | 'toolCallId'>) => void, signal?: AbortSignal): Promise<string>;