@datalayer/agent-runtimes 1.0.29 → 1.3.11

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) {
@@ -96,13 +109,32 @@ export async function getRuntimes() {
     }
     return data.runtimes ?? [];
 }
+/**
+ * One runtime as the platform answers it now — why its pod waits included —
+ * or `null` when there is none by that uid (E2-19).
+ */
+export async function getRuntimeRecord(id) {
+    try {
+        const data = await requestDatalayerAPI({
+            url: runtimeUrl(runtimesStore.getState().runtimesUrl, id),
+            token: iamStore.getState().token,
+        });
+        return data.runtime ?? null;
+    }
+    catch (error) {
+        if (error.response?.status === 404) {
+            return null;
+        }
+        throw error;
+    }
+}
 /**
  * Delete a Runtime
  */
 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 +151,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 +176,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 +190,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 +208,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 +233,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 +244,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 +264,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;

package/lib/runtimes/browser/agent.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * 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, stepCountIs } from 'ai';
+import { frontendToolsToVercelAI, } from './frontendTools';
+import { createBrowserModel } 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 const DEFAULT_BROWSER_MAX_STEPS = 24;
+/**
+ * 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 function createBrowserAgent(options) {
+    const { spec, frontendTools, inference, model, maxSteps = DEFAULT_BROWSER_MAX_STEPS, onHitlRequired, onStatusChange, } = options;
+    if (!model && !inference) {
+        throw new Error('A browser agent needs either a `model` or an `inference` endpoint to reach one.');
+    }
+    return new ToolLoopAgent({
+        id: spec.id,
+        model: model ??
+            createBrowserModel({
+                ...inference,
+                model: spec.model,
+            }),
+        instructions: spec.systemPrompt,
+        tools: frontendToolsToVercelAI(frontendTools, {
+            onHitlRequired,
+            onStatusChange,
+        }),
+        stopWhen: stepCountIs(maxSteps),
+    });
+}

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

@@ -0,0 +1,121 @@
+/** A minted token and the moment it stops being worth sending. */
+export type AnonymousToken = {
+    token: string;
+    /** Epoch milliseconds, from the token's own lifetime plus the local clock. */
+    expiresAt: number;
+    /** How long the service signed it for, as the token itself declares. */
+    lifetimeMs: number;
+};
+/** Where an anonymous visitor's access has got to. */
+export type AnonymousSessionStatus = 
+/** Nobody has asked for a key — the usual case, because somebody is signed in. */
+'idle'
+/** Asked for, not yet answered. */
+ | 'minting'
+/** Held, and still worth sending. */
+ | 'active'
+/** Spent. The agent will be refused from here on. */
+ | 'expired'
+/** The service would not issue one. */
+ | 'failed';
+export type AnonymousSession = {
+    status: AnonymousSessionStatus;
+    /** The key, while it is worth sending. */
+    token?: string;
+    /**
+     * Epoch milliseconds at which the key stops being honoured.
+     *
+     * Read out of the token — see {@link tokenLifetimeMs} — rather than assumed,
+     * so a service that signs keys for five minutes is counted for five minutes
+     * without anything here being changed.
+     */
+    expiresAt?: number;
+    /** How long the key was signed for, so a countdown can draw a proportion. */
+    grantedMs?: number;
+    /** Why there is no key, when the service refused. */
+    error?: string;
+};
+type AnonymousSessionStore = AnonymousSession & {
+    /** Whether the one retry has been spent, so a refusal cannot loop. */
+    retried?: boolean;
+    /**
+     * Get a key, if this visitor has not had one.
+     *
+     * Idempotent by design: every consumer may call it, and a session already
+     * under way — or already spent — is left exactly as it is. Spent in
+     * particular: minting again on the next render is how a trial that is
+     * supposed to end becomes one that never does.
+     */
+    start: (inferenceUrl: string) => void;
+    /**
+     * Declare the key spent, now.
+     *
+     * Called by the store's own timer, and by anything that can see the clock
+     * has passed — a countdown on screen recomputes from the wall clock every
+     * tick, where a `setTimeout` in a background tab is only ever late.
+     */
+    expire: () => void;
+    /** Give the key up. Called when a member signs in, whose token is better. */
+    clear: () => void;
+};
+/** The claims this module reads. Everything else in the token is the service's. */
+type JwtClaims = {
+    /** Seconds since the epoch, issuer's clock. */
+    exp?: number;
+    iat?: number;
+};
+/**
+ * Read a JWT's claims without verifying it.
+ *
+ * Deliberately unverified, and safe to be: this is the page reading the
+ * expiry off a key it was just handed, so it can draw a countdown. Nothing is
+ * authorised on the strength of it — the service verifies the signature on
+ * every request, and a visitor who forged a longer `exp` would only be lying
+ * to their own clock.
+ *
+ * Returns nothing for anything that is not a three-part JWT with a JSON
+ * payload, so an opaque token degrades to the `expires_in` beside it rather
+ * than throwing in a header.
+ */
+export declare function readJwtClaims(token: string): JwtClaims | undefined;
+/**
+ * How long a freshly issued token is good for, in milliseconds.
+ *
+ * `exp - iat` first: both claims come from the issuer, at the same instant, so
+ * their difference is a duration that no clock anywhere can distort. It is
+ * also the only source that is certainly the truth, because `exp` is the claim
+ * the service enforces.
+ *
+ * `expires_in` is the fallback, for a token that is not a JWT or carries no
+ * `iat`. An absolute `exp` against the local clock is deliberately *not* in
+ * this chain: on a machine whose clock is minutes out it produces a key that
+ * appears to expire before it was issued, which is worse than either.
+ */
+export declare function tokenLifetimeMs(token: string, expiresInSeconds?: number): number;
+/**
+ * Mint one. Throws if the service refuses.
+ *
+ * The moment it dies is read off the token itself; see {@link tokenLifetimeMs}.
+ */
+export declare function fetchAnonymousToken(inferenceUrl: string, signal?: AbortSignal): Promise<AnonymousToken>;
+export declare const useAnonymousSessionStore: import("zustand").UseBoundStore<import("zustand").StoreApi<AnonymousSessionStore>>;
+/** Read the shared session without touching it. For anything that only draws it. */
+export declare function useAnonymousSession(): AnonymousSession;
+/**
+ * Hold an anonymous key for as long as one is wanted.
+ *
+ * The driving half: exactly one component in a tree should call this — the
+ * chat that would send the token — and everything else that needs to know
+ * reads {@link useAnonymousSession}.
+ *
+ * @param inferenceUrl Where the service is.
+ * @param enabled False when there is a signed-in member, whose own token is
+ *   better in every way — it names them, it is metered to them, and it does
+ *   not expire. Also false where no in-page agent will ask for inference at
+ *   all, so a workspace on a server-backed agent does not burn a trial nobody
+ *   is using.
+ */
+export declare function useAnonymousInferenceSession(inferenceUrl: string, enabled: boolean): AnonymousSession;
+/** How much of the key's life is left, in milliseconds. Never negative. */
+export declare function anonymousTimeLeft(session: Pick<AnonymousSession, 'expiresAt'>, now?: number): number;
+export default useAnonymousInferenceSession;