@datalayer/agent-runtimes 1.0.29 → 1.3.11

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;

package/lib/runtimes/variants.js

@@ -0,0 +1,187 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * 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 const AGENT_RUNTIME_VARIANTS = [
+    'browser-vercelai',
+    'local-pydanticai',
+    'cloud-pydanticai',
+];
+/** The variant used when a caller does not choose one. */
+export const DEFAULT_AGENT_RUNTIME_VARIANT = 'cloud-pydanticai';
+/**
+ * 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 const SPEC_HARNESS_BY_HARNESS = {
+    pydanticai: 'pydantic-ai',
+    vercelai: 'vercel-ai',
+};
+/** The reverse, for reading an agentspec's declared harness. */
+export const HARNESS_BY_SPEC_HARNESS = {
+    'pydantic-ai': 'pydanticai',
+    'vercel-ai': 'vercelai',
+};
+const VARIANT_BY_LEGACY_TARGET = {
+    'backend-services': 'cloud-pydanticai',
+    'local-agent-runtimes': 'local-pydanticai',
+};
+/** Whether a string is a variant this package knows how to start. */
+export function isAgentRuntimeVariant(value) {
+    return (typeof value === 'string' &&
+        AGENT_RUNTIME_VARIANTS.includes(value));
+}
+/**
+ * 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 function toAgentRuntimeVariant(value, fallback = DEFAULT_AGENT_RUNTIME_VARIANT) {
+    if (!value) {
+        return fallback;
+    }
+    if (isAgentRuntimeVariant(value)) {
+        return value;
+    }
+    return VARIANT_BY_LEGACY_TARGET[value] ?? fallback;
+}
+/** Where this variant's loop runs. */
+export function locationOf(variant) {
+    return variant.slice(0, variant.indexOf('-'));
+}
+/** What turns this variant's loop. */
+export function harnessOf(variant) {
+    return variant.slice(variant.indexOf('-') + 1);
+}
+/**
+ * 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 function runsInBrowser(variant) {
+    return locationOf(variant) === 'browser';
+}
+/**
+ * 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 function needsRuntimeService(variant) {
+    return !runsInBrowser(variant);
+}
+/**
+ * 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 function variantForLocation(location) {
+    return (AGENT_RUNTIME_VARIANTS.find(variant => locationOf(variant) === location) ??
+        DEFAULT_AGENT_RUNTIME_VARIANT);
+}
+/**
+ * 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 function variantSupportsSpecHarness(variant, specHarness) {
+    if (runsInBrowser(variant)) {
+        return true;
+    }
+    if (!specHarness) {
+        // A spec that says nothing wants the framework that has always run it.
+        return harnessOf(variant) === 'pydanticai';
+    }
+    return SPEC_HARNESS_BY_HARNESS[harnessOf(variant)] === specHarness;
+}
+/**
+ * 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 function variantsForSpecHarness(specHarness) {
+    return AGENT_RUNTIME_VARIANTS.filter(variant => variantSupportsSpecHarness(variant, specHarness));
+}
+/**
+ * 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 function legacyTargetOf(variant) {
+    return locationOf(variant) === 'cloud'
+        ? 'backend-services'
+        : 'local-agent-runtimes';
+}
+/**
+ * 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 function specHarnessOf(spec) {
+    return HARNESS_BY_SPEC_HARNESS[spec.harness ?? ''] ?? 'pydanticai';
+}
+/**
+ * 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 function variantsForSpec(spec) {
+    return variantsForSpecHarness(spec.harness);
+}
+/**
+ * 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 function defaultVariantForSpec(spec) {
+    if (variantSupportsSpecHarness(DEFAULT_AGENT_RUNTIME_VARIANT, spec.harness)) {
+        return DEFAULT_AGENT_RUNTIME_VARIANT;
+    }
+    return variantsForSpec(spec)[0] ?? DEFAULT_AGENT_RUNTIME_VARIANT;
+}

package/lib/services/reconnectToRuntime.d.ts

@@ -1,7 +1,7 @@
 import { ServiceManager } from '@jupyterlab/services';
 export interface RuntimeInfo {
     runtimeId: string;
-    podName: string;
+    runtimeName: string;
     ingress: string;
     token: string;
     environmentName?: string;
@@ -20,7 +20,7 @@ export interface RuntimeInfo {
  * ```typescript
  * const runtimeInfo = {
  *   runtimeId: 'abc123',
- *   podName: 'jupyter-pod-xyz',
+ *   runtimeName: 'jupyter-pod-xyz',
  *   ingress: 'https://jupyter.example.com',
  *   token: 'secret-token'
  * };

package/lib/services/reconnectToRuntime.js

@@ -17,7 +17,7 @@ import { ServerConnection, ServiceManager } from '@jupyterlab/services';
  * ```typescript
  * const runtimeInfo = {
  *   runtimeId: 'abc123',
- *   podName: 'jupyter-pod-xyz',
+ *   runtimeName: 'jupyter-pod-xyz',
  *   ingress: 'https://jupyter.example.com',
  *   token: 'secret-token'
  * };
@@ -39,14 +39,14 @@ export const reconnectToRuntime = async (runtimeInfo) => {
             environmentName: runtimeInfo.environmentName || 'unknown',
             credits: 0,
             reservationId: runtimeInfo.runtimeId,
-            podName: runtimeInfo.podName,
+            runtimeName: runtimeInfo.runtimeName,
             ingress: runtimeInfo.ingress,
             token: runtimeInfo.token,
             createdAt: new Date().toISOString(),
         };
         console.log('Reconnected to existing runtime:', {
             runtimeId: runtimeInfo.runtimeId,
-            podName: runtimeInfo.podName,
+            runtimeName: runtimeInfo.runtimeName,
             ingress: runtimeInfo.ingress,
         });
         return serviceManager;

package/lib/services/sandboxServiceManagers.d.ts

@@ -22,10 +22,10 @@ import type { ServiceManager } from '@jupyterlab/services';
  * @returns An unregister function to call when the component disposes the
  *   manager itself (cleanup). Unregistering does NOT dispose the manager.
  */
-export declare function registerSandboxServiceManager(podName: string, manager: ServiceManager.IManager): () => void;
+export declare function registerSandboxServiceManager(runtimeName: string, manager: ServiceManager.IManager): () => void;
 /**
  * Dispose (and unregister) every `ServiceManager` registered against a
  * sandbox pod. Safe to call multiple times — `disposeServiceManager` is
  * idempotent, and disposed managers are dropped from the registry.
  */
-export declare function disposeSandboxServiceManagers(podName: string): void;
+export declare function disposeSandboxServiceManagers(runtimeName: string): void;

package/lib/services/sandboxServiceManagers.js

@@ -3,30 +3,30 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { disposeServiceManager } from '@datalayer/jupyter-react';
-const sandboxManagersByPod = new Map();
+const sandboxManagersByRuntime = new Map();
 /**
  * Register a `ServiceManager` connected to a sandbox pod.
  *
  * @returns An unregister function to call when the component disposes the
  *   manager itself (cleanup). Unregistering does NOT dispose the manager.
  */
-export function registerSandboxServiceManager(podName, manager) {
-    const normalized = String(podName || '').trim();
+export function registerSandboxServiceManager(runtimeName, manager) {
+    const normalized = String(runtimeName || '').trim();
     if (!normalized || !manager) {
         return () => { };
     }
-    let managers = sandboxManagersByPod.get(normalized);
+    let managers = sandboxManagersByRuntime.get(normalized);
     if (!managers) {
         managers = new Set();
-        sandboxManagersByPod.set(normalized, managers);
+        sandboxManagersByRuntime.set(normalized, managers);
     }
     managers.add(manager);
     return () => {
-        const registered = sandboxManagersByPod.get(normalized);
+        const registered = sandboxManagersByRuntime.get(normalized);
         if (registered) {
             registered.delete(manager);
             if (registered.size === 0) {
-                sandboxManagersByPod.delete(normalized);
+                sandboxManagersByRuntime.delete(normalized);
             }
         }
     };
@@ -36,16 +36,16 @@ export function registerSandboxServiceManager(podName, manager) {
  * sandbox pod. Safe to call multiple times — `disposeServiceManager` is
  * idempotent, and disposed managers are dropped from the registry.
  */
-export function disposeSandboxServiceManagers(podName) {
-    const normalized = String(podName || '').trim();
+export function disposeSandboxServiceManagers(runtimeName) {
+    const normalized = String(runtimeName || '').trim();
     if (!normalized) {
         return;
     }
-    const managers = sandboxManagersByPod.get(normalized);
+    const managers = sandboxManagersByRuntime.get(normalized);
     if (!managers) {
         return;
     }
-    sandboxManagersByPod.delete(normalized);
+    sandboxManagersByRuntime.delete(normalized);
     managers.forEach(manager => {
         try {
             disposeServiceManager(manager);