@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/runtimes/browser/anonymousToken.js

@@ -0,0 +1,300 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A key for a visitor who has not signed in, and the clock on it.
+ *
+ * The inference service admits members only — a page cannot hold an AWS
+ * credential, so completions go through a service that does, and that service
+ * has to know who is spending. A public landing page has nobody to name, which
+ * is why an in-page agent there answered every request with 401.
+ *
+ * `POST /anonymous/token` is the service's answer: a short-lived token, no user
+ * attached, no other route, and no way to renew it. This module is the client
+ * for it.
+ *
+ * **One key, and the key says when it dies.** No renewal loop: renewing on a
+ * timer would give an anonymous visitor unmetered access to a members-only
+ * service with nothing on screen admitting it, and a clock that resets never
+ * reaches the moment where the workspace asks them to sign in — which is the
+ * whole point of showing one.
+ *
+ * **The deadline is read out of the token, not calculated beside it.** The JWT
+ * carries `exp`, and that claim is what the service will actually enforce; an
+ * `expires_in` counted against this machine's clock is a second opinion, and
+ * the two disagree whenever anything sits between them. What is taken from the
+ * token is its *lifetime* — `exp - iat`, both from the same issuer at the same
+ * instant — and that is added to the local clock. A duration is immune to the
+ * skew an absolute timestamp is not: a visitor whose laptop is ten minutes
+ * fast would otherwise be told their key expired before it was issued.
+ *
+ * The trial is an offer, not a boundary. It lives in a page, so a reload or a
+ * switch of target gets another key, and nothing here pretends otherwise:
+ * what actually limits anonymous use is the service, which rate limits the
+ * mint endpoint precisely because it is open to anyone. Spending effort making
+ * this side harder to reset would buy nothing the server does not already own.
+ *
+ * How long a key lives is the service's to decide —
+ * `DATALAYER_ANONYMOUS_TOKEN_TTL_SECONDS`, sixty seconds by default. Nothing
+ * here assumes a number; whatever is signed is what is counted.
+ *
+ * A shared session rather than a hook's private state, because three things
+ * need the same answer: the chat, which sends the token; the timer in the
+ * chat header, which draws what is left of it; and the panel that takes over
+ * when it is gone. Three hooks would have minted three keys.
+ *
+ * @module runtimes/browser/anonymousToken
+ */
+import { useEffect } from 'react';
+import { create } from 'zustand';
+/**
+ * What to assume when a token says nothing about its own life.
+ *
+ * Matches the service's default, and is kept in step with it. Only reached for
+ * a token that is neither a JWT with the claims to read nor accompanied by an
+ * `expires_in` — which the service has never sent, so this is a floor under a
+ * bug rather than a policy.
+ */
+const DEFAULT_TTL_MS = 300_000;
+/** How long to wait before trying again when the service refuses. */
+const RETRY_MS = 3_000;
+/**
+ * The expiry timer, module-scoped because the store is.
+ *
+ * Held outside the state so that clearing the session can cancel it — a timer
+ * left running would mark a signed-in member's session expired a minute after
+ * they signed in.
+ */
+let pendingTimer;
+/**
+ * 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 function readJwtClaims(token) {
+    const payload = token.split('.')[1];
+    if (!payload) {
+        return undefined;
+    }
+    try {
+        // base64url → base64, then padded: `atob` accepts neither `-`/`_` nor a
+        // missing tail, and JWTs are written with both.
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+        const claims = JSON.parse(atob(padded));
+        return claims && typeof claims === 'object'
+            ? claims
+            : undefined;
+    }
+    catch {
+        return 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 function tokenLifetimeMs(token, expiresInSeconds) {
+    const claims = readJwtClaims(token);
+    if (claims?.exp && claims?.iat && claims.exp > claims.iat) {
+        return (claims.exp - claims.iat) * 1000;
+    }
+    if (expiresInSeconds && expiresInSeconds > 0) {
+        return expiresInSeconds * 1000;
+    }
+    return DEFAULT_TTL_MS;
+}
+/**
+ * Mint one. Throws if the service refuses.
+ *
+ * The moment it dies is read off the token itself; see {@link tokenLifetimeMs}.
+ */
+export async function fetchAnonymousToken(inferenceUrl, signal) {
+    const base = inferenceUrl.replace(/\/+$/, '');
+    const response = await fetch(`${base}/api/ai-inference/v1/anonymous/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        signal,
+    });
+    if (!response.ok) {
+        throw new Error(`Anonymous inference token refused by ${base} (HTTP ${response.status})`);
+    }
+    const body = (await response.json());
+    if (!body.token) {
+        throw new Error(`No token in the reply from ${base}`);
+    }
+    const lifetimeMs = tokenLifetimeMs(body.token, body.expires_in);
+    return {
+        token: body.token,
+        lifetimeMs,
+        expiresAt: Date.now() + lifetimeMs,
+    };
+}
+export const useAnonymousSessionStore = create((set, get) => {
+    /** Ask for a key, and arrange for the end of it. */
+    const mint = (inferenceUrl) => {
+        set({ status: 'minting', error: undefined });
+        void fetchAnonymousToken(inferenceUrl)
+            .then(minted => {
+            // Somebody signed in while the request was in flight; their token is
+            // the better one and this session was already cleared.
+            if (get().status !== 'minting') {
+                return;
+            }
+            set({
+                status: 'active',
+                token: minted.token,
+                // Both straight from the token: when it dies, and how long it was
+                // given — which is what a countdown needs to draw a proportion
+                // rather than just a number.
+                expiresAt: minted.expiresAt,
+                grantedMs: minted.lifetimeMs,
+                error: undefined,
+            });
+            clearTimeout(pendingTimer);
+            /*
+             * The store expires itself rather than waiting to be told.
+             *
+             * The countdown in the header would do it, but only while it is
+             * mounted — and a workspace whose chat header is hidden would then
+             * go on sending a dead key and reading the 401 as the agent being
+             * broken.
+             */
+            pendingTimer = setTimeout(() => get().expire(), Math.max(0, minted.expiresAt - Date.now()));
+        })
+            .catch((error) => {
+            if (get().status !== 'minting') {
+                return;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn('[anonymousToken] could not mint a token', error);
+            /*
+             * One more attempt, backed off.
+             *
+             * The endpoint is open to anyone and therefore rate limited, and a
+             * page that hammered it after a refusal would earn itself a longer
+             * one. A single retry covers the case worth covering — a service
+             * that was briefly unreachable — without turning a refusal into a
+             * loop.
+             */
+            const firstFailure = !get().retried;
+            set({ status: 'failed', error: message, retried: true });
+            if (firstFailure) {
+                clearTimeout(pendingTimer);
+                pendingTimer = setTimeout(() => {
+                    if (get().status === 'failed') {
+                        mint(inferenceUrl);
+                    }
+                }, RETRY_MS);
+            }
+        });
+    };
+    return {
+        status: 'idle',
+        start: (inferenceUrl) => {
+            const { status } = get();
+            // Minting, live, retrying, or spent: all four already have their
+            // answer. Only a visitor who has never asked gets a key, which is what
+            // stops one being handed out again on the next render.
+            if (status !== 'idle') {
+                return;
+            }
+            if (!inferenceUrl) {
+                return;
+            }
+            mint(inferenceUrl);
+        },
+        expire: () => {
+            const { status } = get();
+            if (status === 'idle' || status === 'expired') {
+                return;
+            }
+            clearTimeout(pendingTimer);
+            pendingTimer = undefined;
+            // The token goes with the status: anything still holding a reference
+            // to this session must not be able to send a key the service will
+            // refuse.
+            set({ status: 'expired', token: undefined });
+        },
+        clear: () => {
+            if (get().status === 'idle') {
+                return;
+            }
+            clearTimeout(pendingTimer);
+            pendingTimer = undefined;
+            set({
+                status: 'idle',
+                token: undefined,
+                expiresAt: undefined,
+                grantedMs: undefined,
+                error: undefined,
+                retried: false,
+            });
+        },
+    };
+});
+/** Read the shared session without touching it. For anything that only draws it. */
+export function useAnonymousSession() {
+    /*
+     * The whole state, not a projection of it.
+     *
+     * A selector building `{status, token, ...}` returns a new object on every
+     * render, and React's `useSyncExternalStore` — which is what zustand is
+     * built on — treats an unstable snapshot as a loop. The store object itself
+     * changes identity exactly when something in it changed, which is the
+     * subscription that was wanted anyway.
+     */
+    return useAnonymousSessionStore();
+}
+/**
+ * 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 function useAnonymousInferenceSession(inferenceUrl, enabled) {
+    const session = useAnonymousSession();
+    useEffect(() => {
+        const { start, clear } = useAnonymousSessionStore.getState();
+        if (enabled && inferenceUrl) {
+            start(inferenceUrl);
+            return undefined;
+        }
+        // Somebody signed in, or the workspace moved to an agent that does its own
+        // authenticating: the key is not ours to keep holding.
+        clear();
+        return undefined;
+    }, [inferenceUrl, enabled]);
+    return session;
+}
+/** How much of the key's life is left, in milliseconds. Never negative. */
+export function anonymousTimeLeft(session, now = Date.now()) {
+    return Math.max(0, (session.expiresAt ?? now) - now);
+}
+export default useAnonymousInferenceSession;

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

@@ -0,0 +1,61 @@
+/**
+ * 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
+ */
+import { type ToolSet } from 'ai';
+import type { FrontendToolDefinition, ToolCallRequest, ToolRenderStatus } from '../../types/tools';
+/**
+ * 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 declare function toolInputSchema(definition: Pick<FrontendToolDefinition, 'parameters'>): Record<string, unknown>;
+export type FrontendToolsToVercelAIOptions = {
+    /**
+     * Asks a person to approve a call before it runs.
+     *
+     * Only consulted for tools that declare `renderAndWaitForResponse`, and it
+     * is the same callback the AG-UI path uses. Returning `null` rejects the
+     * call — the model is told so and can carry on.
+     */
+    onHitlRequired?: (toolCall: ToolCallRequest, definition: FrontendToolDefinition) => Promise<unknown | null>;
+    /** Reports a call moving through executing → complete/failed. */
+    onStatusChange?: (toolCallId: string, status: ToolRenderStatus, result?: unknown, error?: string) => void;
+};
+/**
+ * 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 declare function frontendToolsToVercelAI(frontendTools: FrontendToolDefinition[], options?: FrontendToolsToVercelAIOptions): ToolSet;

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;