@datalayer/agent-runtimes 1.0.29 → 1.3.10

package/lib/runtimes/browser/subagents.js

@@ -0,0 +1,241 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * 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 { ToolLoopAgent, stepCountIs, tool, jsonSchema, } from 'ai';
+import { SUBAGENT_STOPPED, } from '../../types/stream';
+import { createBrowserModel } from './model';
+/** How many turns a delegated task may take before it is stopped. */
+export const DEFAULT_SUBAGENT_MAX_STEPS = 12;
+/** The input every delegation tool takes. */
+const TASK_SCHEMA = {
+    type: 'object',
+    properties: {
+        task: {
+            type: 'string',
+            description: 'What to do, stated so that it can be carried out without the rest of this conversation.',
+        },
+    },
+    required: ['task'],
+};
+/**
+ * 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 function subagentTools(options) {
+    const { subagents, inference, model, sharing = 'shared', maxSteps = DEFAULT_SUBAGENT_MAX_STEPS, tools: shared, onEvent, signal: runSignal, } = options;
+    const tools = {};
+    for (const subagent of subagents) {
+        tools[subagent.name] = tool({
+            description: subagent.description,
+            inputSchema: jsonSchema(TASK_SCHEMA),
+            execute: async (input, executionOptions) => {
+                const { task } = (input ?? {});
+                if (!task?.trim()) {
+                    return { error: 'A delegated task needs to say what to do.' };
+                }
+                // Keyed by the parent's tool call, as the server keys its events:
+                // one delegation, one timeline, whichever side ran it. A run ends
+                // once: a stream that reports an error and then rejects would
+                // otherwise say so twice.
+                const toolCallId = executionOptions?.toolCallId ?? null;
+                let ended = false;
+                const emit = (event) => {
+                    if (event.phase === 'end' || event.phase === 'error') {
+                        if (ended) {
+                            return;
+                        }
+                        ended = true;
+                    }
+                    onEvent?.({ subagentName: subagent.name, toolCallId, ...event });
+                };
+                const child = new ToolLoopAgent({
+                    id: subagent.name,
+                    model: createBrowserModel({
+                        ...inference,
+                        model: subagent.model ?? model,
+                    }),
+                    instructions: subagent.instructions,
+                    tools: subagent.tools ?? shared ?? {},
+                    stopWhen: stepCountIs(maxSteps),
+                });
+                // Stopped when either the run or this tool call is: the two signals
+                // are one to the child.
+                const signal = anySignal([
+                    executionOptions?.abortSignal,
+                    runSignal?.(),
+                ]);
+                emit({ phase: 'start', task });
+                try {
+                    // `messages` for a shared conversation, `prompt` for an isolated
+                    // one — the same two shapes the SDK documents, chosen by the team.
+                    const history = sharing === 'shared'
+                        ? (executionOptions?.messages ?? [])
+                        : [];
+                    // Streamed rather than generated, so the run can be watched: each
+                    // part becomes an event as it arrives, and the text is what the
+                    // parent is handed at the end.
+                    const result = await child.stream({
+                        messages: [...history, { role: 'user', content: task }],
+                        abortSignal: signal,
+                    });
+                    const streamed = await relaySubagentRun(result.fullStream, emit, signal);
+                    if (signal?.aborted) {
+                        emit({ phase: 'error', error: STOPPED });
+                        return { agent: subagent.name, error: STOPPED };
+                    }
+                    const output = streamed || (await result.text);
+                    emit({ phase: 'end', output });
+                    return { agent: subagent.name, result: output };
+                }
+                catch (reason) {
+                    // Returned rather than thrown: a failed delegation is a step the
+                    // parent can recover from — try another member, or tell the person
+                    // — and a throw would abort the whole run instead.
+                    // A stop is said as a stop, not as whatever the aborted fetch threw.
+                    const error = signal?.aborted
+                        ? STOPPED
+                        : reason instanceof Error
+                            ? reason.message
+                            : String(reason);
+                    emit({ phase: 'error', error });
+                    return { agent: subagent.name, error };
+                }
+            },
+            // What the parent's model reads. The person can see the whole delegated
+            // run in the transcript; the parent only needs its conclusion, and
+            // paying for the rest in context is how a delegation model runs out of
+            // room three hand-offs in.
+            toModelOutput: ({ output }) => {
+                const value = output;
+                return {
+                    type: 'text',
+                    value: value?.error
+                        ? `${subagent.name} could not finish: ${value.error}`
+                        : (value?.result ?? 'Done.'),
+                };
+            },
+        });
+    }
+    return tools;
+}
+/** What a delegation says when the person stopped it. */
+export const STOPPED = SUBAGENT_STOPPED;
+/** One signal for several, or the one there is. */
+function anySignal(signals) {
+    const present = signals.filter((entry) => Boolean(entry));
+    if (present.length <= 1) {
+        return present[0];
+    }
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any(present);
+    }
+    // Older runtimes: a controller that follows whichever fires first.
+    const controller = new AbortController();
+    for (const entry of present) {
+        if (entry.aborted) {
+            controller.abort(entry.reason);
+            break;
+        }
+        entry.addEventListener('abort', () => controller.abort(entry.reason), {
+            once: true,
+        });
+    }
+    return controller.signal;
+}
+/** A tool's result as a line the timeline can show. */
+function preview(value) {
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    return text.length > 400 ? `${text.slice(0, 400)}…` : text;
+}
+/**
+ * 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 async function relaySubagentRun(stream, emit, signal) {
+    let text = '';
+    for await (const part of stream) {
+        // Stopped: whatever is still in the pipe is not worth relaying.
+        if (signal?.aborted) {
+            break;
+        }
+        switch (part.type) {
+            case 'text-delta':
+                text += part.text ?? '';
+                emit({ phase: 'text', text: part.text ?? '' });
+                break;
+            case 'reasoning-delta':
+                emit({ phase: 'thinking', text: part.text ?? '' });
+                break;
+            case 'tool-call':
+                emit({
+                    phase: 'tool_call',
+                    toolName: part.toolName,
+                    toolArgs: (part.input ?? {}),
+                });
+                break;
+            case 'tool-result':
+                emit({
+                    phase: 'tool_result',
+                    toolName: part.toolName,
+                    result: preview(part.output),
+                });
+                break;
+            case 'tool-error':
+                emit({
+                    phase: 'tool_result',
+                    toolName: part.toolName,
+                    result: preview(part.error),
+                });
+                break;
+            case 'error':
+                emit({
+                    phase: 'error',
+                    error: part.error instanceof Error
+                        ? part.error.message
+                        : String(part.error),
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    return text;
+}

package/lib/runtimes/index.d.ts

@@ -1,5 +1,8 @@
 export * from './actions';
+export * from './lifecycle';
 export * from './apis';
 export * from './settings';
 export * from './snapshots';
 export * from './utils';
+export * from './variants';
+export * from './browser';

package/lib/runtimes/index.js

@@ -3,7 +3,10 @@
  * Distributed under the terms of the Modified BSD License.
  */
 export * from './actions';
+export * from './lifecycle';
 export * from './apis';
 export * from './settings';
 export * from './snapshots';
 export * from './utils';
+export * from './variants';
+export * from './browser';

package/lib/runtimes/lifecycle.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The converged sandbox lifecycle, in TypeScript.
+ *
+ * The Python side states this vocabulary in `code_sandboxes.lifecycle` and the
+ * Runtimes client is written to it. This is the same statement for callers that
+ * reach the API from a browser: one place that knows how a runtime URL is
+ * spelled, so a hook, a mixin and a page cannot drift from each other the way
+ * they did when each built its own string.
+ *
+ * Transport stays with the caller — `requestDatalayerAPI`, `requestDatalayer`
+ * and a bare `fetch` all have their reasons. Only the URLs and the verbs are
+ * shared, because those are what has to agree.
+ */
+/**
+ * A verb a caller may use, and the REST spelling it corresponds to.
+ *
+ * Mirrors `LIFECYCLE_OPERATIONS` in `code_sandboxes.lifecycle` — if one of them
+ * changes, so does the other, and the tests on both sides say so.
+ */
+export declare const LIFECYCLE_OPERATIONS: {
+    readonly create: "POST /runtimes";
+    readonly start: "POST /runtimes (implied) — begin a created sandbox";
+    readonly stop: "DELETE /runtimes/{runtime_name}";
+    readonly pause: "POST /runtimes/{runtime_name}/pause";
+    readonly resume: "POST /runtimes/{runtime_name}/resume";
+    readonly list: "GET /runtimes";
+    readonly get: "GET /runtimes/{runtime_name}";
+    readonly update: "PUT /runtimes/{runtime_name}";
+    readonly snapshot: "POST /sandbox-snapshots";
+    readonly execute: "run code in the sandbox";
+};
+/**
+ * The name of a lifecycle verb.
+ */
+export type LifecycleOperation = keyof typeof LIFECYCLE_OPERATIONS;
+/**
+ * The Runtimes API prefix, below whichever host serves it.
+ */
+export declare const RUNTIMES_API_PREFIX = "api/runtimes/v1";
+/**
+ * Every runtime — the collection.
+ *
+ * `create` posts here and `list` gets here.
+ */
+export declare function runtimesUrl(baseUrl: string): string;
+/**
+ * One runtime, by pod name.
+ *
+ * `get` reads it, `update` puts to it, and `stop` deletes it — whether the
+ * runtime is running or paused, which is why there is no second path for the
+ * paused case.
+ */
+export declare function runtimeUrl(baseUrl: string, runtimeName: string): string;
+/**
+ * Suspend one runtime, keeping its state.
+ */
+export declare function runtimePauseUrl(baseUrl: string, runtimeName: string): string;
+/**
+ * Bring one paused runtime back.
+ */
+export declare function runtimeResumeUrl(baseUrl: string, runtimeName: string): string;
+/**
+ * The snapshots collection.
+ *
+ * A snapshot outlives the runtime it came from, which is why it is its own
+ * resource rather than a sub-path of the pod.
+ */
+export declare function sandboxSnapshotsUrl(baseUrl: string): string;
+/**
+ * One snapshot, by UID.
+ */
+export declare function sandboxSnapshotUrl(baseUrl: string, id: string): string;
+/**
+ * The checkpoint records behind pause and resume.
+ */
+export declare function runtimeCheckpointsUrl(baseUrl: string): string;

package/lib/runtimes/lifecycle.js

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The converged sandbox lifecycle, in TypeScript.
+ *
+ * The Python side states this vocabulary in `code_sandboxes.lifecycle` and the
+ * Runtimes client is written to it. This is the same statement for callers that
+ * reach the API from a browser: one place that knows how a runtime URL is
+ * spelled, so a hook, a mixin and a page cannot drift from each other the way
+ * they did when each built its own string.
+ *
+ * Transport stays with the caller — `requestDatalayerAPI`, `requestDatalayer`
+ * and a bare `fetch` all have their reasons. Only the URLs and the verbs are
+ * shared, because those are what has to agree.
+ */
+/**
+ * A verb a caller may use, and the REST spelling it corresponds to.
+ *
+ * Mirrors `LIFECYCLE_OPERATIONS` in `code_sandboxes.lifecycle` — if one of them
+ * changes, so does the other, and the tests on both sides say so.
+ */
+export const LIFECYCLE_OPERATIONS = {
+    create: 'POST /runtimes',
+    start: 'POST /runtimes (implied) — begin a created sandbox',
+    stop: 'DELETE /runtimes/{runtime_name}',
+    pause: 'POST /runtimes/{runtime_name}/pause',
+    resume: 'POST /runtimes/{runtime_name}/resume',
+    list: 'GET /runtimes',
+    get: 'GET /runtimes/{runtime_name}',
+    update: 'PUT /runtimes/{runtime_name}',
+    snapshot: 'POST /sandbox-snapshots',
+    execute: 'run code in the sandbox',
+};
+/**
+ * The Runtimes API prefix, below whichever host serves it.
+ */
+export const RUNTIMES_API_PREFIX = 'api/runtimes/v1';
+/**
+ * Join a base URL to a path without doubling or dropping the slash between.
+ *
+ * `URLExt.join` would do this, but the callers of this module include ones with
+ * no JupyterLab dependency, and a runtime URL is not worth one.
+ */
+function join(base, path) {
+    return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+/**
+ * Every runtime — the collection.
+ *
+ * `create` posts here and `list` gets here.
+ */
+export function runtimesUrl(baseUrl) {
+    return join(baseUrl, `${RUNTIMES_API_PREFIX}/runtimes`);
+}
+/**
+ * One runtime, by pod name.
+ *
+ * `get` reads it, `update` puts to it, and `stop` deletes it — whether the
+ * runtime is running or paused, which is why there is no second path for the
+ * paused case.
+ */
+export function runtimeUrl(baseUrl, runtimeName) {
+    return `${runtimesUrl(baseUrl)}/${runtimeName}`;
+}
+/**
+ * Suspend one runtime, keeping its state.
+ */
+export function runtimePauseUrl(baseUrl, runtimeName) {
+    return `${runtimeUrl(baseUrl, runtimeName)}/pause`;
+}
+/**
+ * Bring one paused runtime back.
+ */
+export function runtimeResumeUrl(baseUrl, runtimeName) {
+    return `${runtimeUrl(baseUrl, runtimeName)}/resume`;
+}
+/**
+ * The snapshots collection.
+ *
+ * A snapshot outlives the runtime it came from, which is why it is its own
+ * resource rather than a sub-path of the pod.
+ */
+export function sandboxSnapshotsUrl(baseUrl) {
+    return join(baseUrl, `${RUNTIMES_API_PREFIX}/sandbox-snapshots`);
+}
+/**
+ * One snapshot, by UID.
+ */
+export function sandboxSnapshotUrl(baseUrl, id) {
+    return `${sandboxSnapshotsUrl(baseUrl)}/${id}`;
+}
+/**
+ * The checkpoint records behind pause and resume.
+ */
+export function runtimeCheckpointsUrl(baseUrl) {
+    return join(baseUrl, `${RUNTIMES_API_PREFIX}/runtime-checkpoints`);
+}

package/lib/runtimes/variants.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Agent runtime variants: where an agent's loop runs, and what runs it.
+ *
+ * There have always been two ways to start an agent — a local agent-runtimes
+ * server and a cloud one — and they were named after the service each talked
+ * to (`local-agent-runtimes`, `backend-services`). That naming held while both
+ * ran the same framework. A browser agent breaks it: it talks to no service at
+ * all, and it runs a different framework.
+ *
+ * So a variant names the two things that actually vary, in that order:
+ *
+ *     <location>-<harness>        browser-vercelai
+ *                                 local-pydanticai
+ *                                 cloud-pydanticai
+ *
+ * The point of splitting them is that most code cares about exactly one half.
+ * Anything about *reaching* a runtime — a URL, a lifecycle, a sandbox — is a
+ * question of location. Anything about *turning the loop* — the SDK, the tool
+ * protocol, the streaming format — is a question of harness. Code that branches
+ * on the whole variant string has to be edited every time either axis gains a
+ * value; code that asks {@link locationOf} or {@link harnessOf} does not.
+ *
+ * That is what makes the next ones cheap. `cloud-ax` is a new harness against
+ * an existing location, so only harness-specific code changes; `browser-ax` is
+ * a combination of two things that already exist.
+ *
+ * @module runtimes/variants
+ */
+import type { Agentspec } from '../types/agentspecs';
+/** Where the agent's loop runs. */
+export type AgentLocation = 'browser' | 'local' | 'cloud';
+/**
+ * What turns the loop.
+ *
+ * Spelled without the hyphen the frameworks use in their own names, because
+ * the hyphen is already doing a job here: it separates location from harness.
+ * {@link SPEC_HARNESS_BY_HARNESS} maps back to the spelling an agentspec uses.
+ */
+export type AgentHarness = 'pydanticai' | 'vercelai';
+/**
+ * The combinations that exist today.
+ *
+ * Enumerated rather than derived from the two axes, because not every pairing
+ * is real: there is no `browser-pydanticai`, and a type that admitted one would
+ * be describing a runtime nobody can start.
+ */
+export declare const AGENT_RUNTIME_VARIANTS: readonly ["browser-vercelai", "local-pydanticai", "cloud-pydanticai"];
+export type AgentRuntimeVariant = (typeof AGENT_RUNTIME_VARIANTS)[number];
+/** The variant used when a caller does not choose one. */
+export declare const DEFAULT_AGENT_RUNTIME_VARIANT: AgentRuntimeVariant;
+/**
+ * The harness as an agentspec spells it.
+ *
+ * A spec says `harness: pydantic-ai`; a variant says `pydanticai`. Same thing,
+ * two spellings forced by the separator, and this is the one place that knows
+ * it — rather than every caller doing its own `replace('-', '')`.
+ */
+export declare const SPEC_HARNESS_BY_HARNESS: Record<AgentHarness, string>;
+/** The reverse, for reading an agentspec's declared harness. */
+export declare const HARNESS_BY_SPEC_HARNESS: Record<string, AgentHarness>;
+/**
+ * The names the two original ways to start an agent went by.
+ *
+ * Kept working rather than removed: they are exported API and appear in
+ * applications this package does not own. New code should pass a variant.
+ *
+ * @deprecated Use {@link AgentRuntimeVariant}.
+ */
+export type RuntimeCreationTarget = 'backend-services' | 'local-agent-runtimes';
+/** Whether a string is a variant this package knows how to start. */
+export declare function isAgentRuntimeVariant(value: unknown): value is AgentRuntimeVariant;
+/**
+ * The variant a caller meant, from a variant or one of the legacy target names.
+ *
+ * One funnel, so the rest of the package sees variants only and no branch has
+ * to remember that two vocabularies exist.
+ */
+export declare function toAgentRuntimeVariant(value: AgentRuntimeVariant | RuntimeCreationTarget | undefined | null, fallback?: AgentRuntimeVariant): AgentRuntimeVariant;
+/** Where this variant's loop runs. */
+export declare function locationOf(variant: AgentRuntimeVariant): AgentLocation;
+/** What turns this variant's loop. */
+export declare function harnessOf(variant: AgentRuntimeVariant): AgentHarness;
+/**
+ * Whether the loop runs in the page.
+ *
+ * The question worth asking wherever a runtime would otherwise be reached for,
+ * because it is the one that changes what exists: a browser agent has no
+ * service behind it, so no runtime to create, no sandbox to execute in, no MCP
+ * servers to call, and no lifecycle to pause or resume.
+ */
+export declare function runsInBrowser(variant: AgentRuntimeVariant): boolean;
+/**
+ * Whether a runtime has to be created and reached over HTTP.
+ *
+ * True for every location except the browser, and the reason most of the
+ * lifecycle code can stay indifferent to which of the two remote locations it
+ * is talking to.
+ */
+export declare function needsRuntimeService(variant: AgentRuntimeVariant): boolean;
+/**
+ * The variant for a location.
+ *
+ * A location decides its own harness, because only one framework can run there
+ * — the browser has no server to turn a pydantic-ai loop, and the two remote
+ * locations have no page to turn a Vercel AI one. Naming both halves in a
+ * variant is still worth it: it is what makes `cloud-ax` a value rather than a
+ * rewrite. But given a location, the harness is not a separate choice.
+ */
+export declare function variantForLocation(location: AgentLocation): AgentRuntimeVariant;
+/**
+ * Whether a variant can run an agent that declared this harness in its spec.
+ *
+ * An agentspec says which framework it *prefers* — `harness:` is where the
+ * agent normally runs, not a demand — and a variant says which framework a
+ * location can actually provide. Where they disagree the location wins, which
+ * is why the browser accepts any spec:
+ *
+ *     harness: pydantic-ai  +  browser  →  runs, with the Vercel AI SDK
+ *
+ * The alternative was a second spec per agent, identical but for one field.
+ * That duplicated the prompt, the tools, the evals and everything else that
+ * has nothing to do with where a loop turns — and it made a spec's author
+ * responsible for a decision the host makes.
+ *
+ * The remote locations are stricter: a spec built for the browser harness
+ * assumes frontend tools and no server, so running it on a runtime would be
+ * running something else.
+ */
+export declare function variantSupportsSpecHarness(variant: AgentRuntimeVariant, specHarness: string | undefined | null): boolean;
+/**
+ * The variants that could run an agent with this declared harness.
+ *
+ * What a host offers a person choosing where to run something. The browser is
+ * always among them — it can run anything, because it overrides the harness —
+ * while an agent built for the browser is not offered a remote runtime that
+ * would be running something else.
+ */
+export declare function variantsForSpecHarness(specHarness: string | undefined | null): AgentRuntimeVariant[];
+/**
+ * The legacy target name closest to a variant.
+ *
+ * For consumers still reading `runtimeCreationTarget`: a browser agent has no
+ * old name — there was no way to start one — so it reports as local, which is
+ * the truthful half of the answer (nothing remote is being reached).
+ *
+ * @deprecated Read the variant.
+ */
+export declare function legacyTargetOf(variant: AgentRuntimeVariant): RuntimeCreationTarget;
+/**
+ * The harness a spec asks for, in the variant spelling.
+ *
+ * Defaulted rather than optional: every agent is run by something, and a spec
+ * that says nothing is run by the framework that has always run it. That
+ * default is what lets every spec written before this field stay correct.
+ */
+export declare function specHarnessOf(spec: Pick<Agentspec, 'harness'>): AgentHarness;
+/**
+ * The variants that could run this agent.
+ *
+ * What a host offers when someone picks where to run something: an agent built
+ * for the browser harness should not be offered a cloud runtime that cannot
+ * turn its loop, and a server-side agent should not be offered the page.
+ */
+export declare function variantsForSpec(spec: Pick<Agentspec, 'harness'>): AgentRuntimeVariant[];
+/**
+ * The variant to start this agent with when the host has no preference.
+ *
+ * The package default when the spec can run there, and otherwise the first
+ * variant that can run it at all — so a `harness: vercel-ai` agent lands in
+ * the browser without every caller having to know that is where it belongs.
+ */
+export declare function defaultVariantForSpec(spec: Pick<Agentspec, 'harness'>): AgentRuntimeVariant;