@datalayer/agent-runtimes 1.3.29 → 1.3.32

package/lib/loop/embed/AppEmbed.d.ts

@@ -0,0 +1,42 @@
+import type { CSSProperties, JSX, ReactNode } from 'react';
+import type { AppAccent, AppEmbedMode, AppSpec } from '../../types/agentspecs';
+import { type AppInstance } from '../apps/AppRenderer';
+import { type EmbedColorMode } from './embedConfig';
+export type AppEmbedProps = {
+    /** The application. */
+    app: AppSpec;
+    /** How it sits in the page; the Appspec's `deployment.embedded.mode` by default. */
+    mode?: AppEmbedMode;
+    /** The host's accent; the application's own by default. */
+    accent?: AppAccent;
+    /** Light, dark, or the visitor's system. */
+    colorMode?: EmbedColorMode;
+    /** The host's face, a CSS font family; the theme's by default. */
+    font?: string;
+    /**
+     * An agent-runtimes server the application's agent runs on. Without one,
+     * it runs on a Datalayer runtime, launched with the visitor's Datalayer
+     * credentials.
+     */
+    serverUrl?: string;
+    /** What its record is kept under, on Datalayer. */
+    instance?: AppInstance;
+    /** Height of an inline application. */
+    height?: number | string;
+    /**
+     * Draw overlays — menus, dialogs — inside the embed's own root rather than
+     * in Primer's, in the host's `<body>`: what the element asks for, since a
+     * shadow root's styles stop at its edge. A React host leaves it off.
+     */
+    ownPortal?: boolean;
+};
+/** The `loop` theme, with the application's (or the host's) accent and face. */
+export declare function EmbedThemed({ accent, colorMode, font, children, style, }: {
+    accent: AppAccent;
+    colorMode: 'light' | 'dark';
+    font?: string;
+    children: ReactNode;
+    style?: CSSProperties;
+}): JSX.Element;
+export declare function AppEmbed({ app, mode, accent, colorMode, font, serverUrl, instance, height, ownPortal, }: AppEmbedProps): JSX.Element;
+export default AppEmbed;

package/lib/loop/embed/AppEmbed.js

@@ -0,0 +1,205 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * An application in another product's page, as a React component (LOOP
+ * D-07, D-09, D-11): what the `<datalayer-app>` element draws, and what a
+ * host that uses React mounts itself.
+ *
+ * Four modes, as the Appspec says (`deployment.embedded.mode`) or the host:
+ *
+ * - **inline** — the application where the component is: `AppRenderer`, its
+ *   page beside its conversation when it has one;
+ * - **bubble** — a round button in the corner that opens the conversation in
+ *   a popup, the copilot pattern;
+ * - **panel** — the conversation at the right edge of the page, at full
+ *   height;
+ * - **assistant** — the application's character on the page, speaking in a
+ *   balloon (§6.9), the one its Appspec names (`interface.assistant`).
+ *
+ * The three floating modes are `ChatFloating`'s, given the application's
+ * name, welcome, starters and accent, and its agent's endpoint — created
+ * with the application's spec in its payload, so the runtime enforces its
+ * rules there as it does inline.
+ *
+ * In the `loop` theme with the application's accent (T-12, T-05), which the
+ * host may override with the face and the mode (D-11).
+ *
+ * @module loop/embed/AppEmbed
+ */
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { registerPortalRoot } from '@primer/react';
+import { DatalayerThemeProvider, loopTheme } from '@datalayer/primer-addons';
+import { useIAMStore } from '@datalayer/core/lib/state/substates/IAMState';
+import { ChatFloating } from '../../chat/ChatFloating';
+import { useAgentRuntimes } from '../../hooks/useAgentRuntimes';
+import { AppRenderer, DATALAYER_BOOTSTRAP_AGENTSPEC, appDatalayerCreatePayload, defineAppPlugin, } from '../apps/AppRenderer';
+import { LoopAgentBlueprint } from '../core';
+import { ensureServerAgent } from '../plugins/agents/switchable';
+import { floatingViewOf } from './embedConfig';
+import { embedThemeStyles } from './embedTheme';
+/** What the application's agent is created with on an agent-runtimes server. */
+function serverCreatePayload(app) {
+    const blueprint = (defineAppPlugin(app).contributes ?? []).find((item) => item.point === LoopAgentBlueprint);
+    return blueprint?.value.createPayload ?? { name: app.id };
+}
+/**
+ * The application's agent on the host's agent-runtimes server: created
+ * there with the application's spec unless it is there already, as the
+ * workspace's Local target does.
+ */
+function useServerAgent(app, serverUrl) {
+    const [state, setState] = useState({
+        waiting: 'Starting…',
+    });
+    const source = JSON.stringify(app);
+    useEffect(() => {
+        let cancelled = false;
+        const base = serverUrl.replace(/\/+$/, '');
+        setState({ waiting: 'Starting…' });
+        ensureServerAgent(base, app.id, serverCreatePayload(app)).then(() => {
+            if (!cancelled) {
+                setState({
+                    protocol: {
+                        type: 'ag-ui',
+                        endpoint: `${base}/api/v1/ag-ui/${app.id}/`,
+                        agentId: app.id,
+                    },
+                });
+            }
+        }, (error) => {
+            if (!cancelled) {
+                setState({
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [serverUrl, source]);
+    return state;
+}
+/**
+ * The application's agent on a Datalayer runtime: allocated with a plain
+ * agentspec, the agent created there with the application's spec — the
+ * runtime `AppRenderer` launches inline (R-03, R-05).
+ */
+function useDatalayerAgent(app, instance) {
+    const token = useIAMStore(state => state.token);
+    const source = JSON.stringify(app);
+    const agentConfig = useMemo(() => ({
+        name: app.id,
+        protocol: 'ag-ui',
+        agentSpecId: DATALAYER_BOOTSTRAP_AGENTSPEC,
+        createPayload: appDatalayerCreatePayload(app, instance),
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [source, instance?.appUid, instance?.deploymentUid, instance?.version]);
+    const { runtime, error } = useAgentRuntimes({
+        agentSpecId: DATALAYER_BOOTSTRAP_AGENTSPEC,
+        agentConfig,
+        variant: 'cloud-pydanticai',
+        // Only for a visitor Datalayer knows: a runtime is somebody's to pay for.
+        autoStart: Boolean(token),
+        autoCreateAgent: Boolean(token),
+    });
+    if (!token) {
+        return {
+            error: `${app.name} runs on Datalayer, which needs you signed in. An application embedded for visitors who are not needs its embed token (LOOP D-14), or an agent-runtimes server of the host's own (the "server" attribute).`,
+        };
+    }
+    if (error) {
+        return { error };
+    }
+    if (!runtime?.agentBaseUrl) {
+        return { waiting: 'Starting…' };
+    }
+    return {
+        protocol: {
+            type: 'ag-ui',
+            endpoint: `${runtime.agentBaseUrl}/api/v1/ag-ui/${app.id}/`,
+            agentId: app.id,
+            authToken: token,
+        },
+    };
+}
+/** The application's face, as the floating chat's button and header draw it. */
+function Face({ emoji }) {
+    return (_jsx("span", { "aria-hidden": true, style: { fontSize: 18, lineHeight: 1 }, children: emoji }));
+}
+/** The bubble, the panel and the assistant: `ChatFloating` in that mode. */
+function FloatingChat({ app, view, colorMode, agent, }) {
+    const welcome = app.interface.welcome || app.description;
+    return (_jsx(ChatFloating
+    // A new agent is a new conversation.
+    , { defaultViewMode: view, assistantCharacter: app.interface.assistant ?? 'paperclip', protocol: agent.protocol, authToken: agent.protocol?.authToken, title: app.name, description: welcome, brandIcon: _jsx(Face, { emoji: app.emoji }), buttonIcon: _jsx(Face, { emoji: app.emoji }), buttonTooltip: `Talk to ${app.name}`, suggestions: app.interface.starters.map(starter => ({
+            title: starter.label,
+            message: starter.message,
+        })), themeVariant: "loop", colorMode: colorMode, showTokenUsage: false, showSettingsButton: false, showPoweredBy: false, useStore: false, launching: !agent.protocol && !agent.error, launchingMessage: agent.waiting, disabled: Boolean(agent.error), disableReason: agent.error }, agent.protocol?.endpoint ?? 'waiting'));
+}
+/** Floating, its agent on the host's agent-runtimes server. */
+function ServerFloating({ serverUrl, ...props }) {
+    return (_jsx(FloatingChat, { ...props, agent: useServerAgent(props.app, serverUrl) }));
+}
+/** Floating, its agent on a Datalayer runtime. */
+function DatalayerFloating({ instance, ...props }) {
+    return (_jsx(FloatingChat, { ...props, agent: useDatalayerAgent(props.app, instance) }));
+}
+/**
+ * Overlays — menus, dialogs — drawn inside the embed's own root, under the
+ * theme's element, so that they wear its theme: what the element asks for,
+ * since Primer's own portal root is in the host's `<body>`, outside the
+ * shadow root and its styles.
+ */
+function OwnPortalRoot() {
+    const ref = useRef(null);
+    useLayoutEffect(() => {
+        if (ref.current) {
+            registerPortalRoot(ref.current);
+        }
+    }, []);
+    return _jsx("div", { ref: ref, className: "datalayer-app-portal" });
+}
+/** The visitor's system mode, followed while it changes. */
+function useSystemMode() {
+    const query = typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+        ? window.matchMedia('(prefers-color-scheme: dark)')
+        : null;
+    const [dark, setDark] = useState(Boolean(query?.matches));
+    useEffect(() => {
+        if (!query) {
+            return undefined;
+        }
+        const follow = () => setDark(query.matches);
+        query.addEventListener?.('change', follow);
+        return () => query.removeEventListener?.('change', follow);
+    }, [query]);
+    return dark ? 'dark' : 'light';
+}
+/** The `loop` theme, with the application's (or the host's) accent and face. */
+export function EmbedThemed({ accent, colorMode, font, children, style, }) {
+    const themeStyles = useMemo(() => embedThemeStyles({ accent, font }), [accent, font]);
+    return (
+    /*
+     * Marked as themed above the provider, so that the provider counts
+     * itself nested and leaves the host's <body> and Primer's portal root
+     * alone: it would otherwise write the theme's tokens, colour and face on
+     * the host's page (T-13). A wrapper of no box.
+     */
+    _jsx("div", { "data-color-mode": colorMode, style: { display: 'contents' }, children: _jsx(DatalayerThemeProvider, { colorMode: colorMode, theme: loopTheme, themeStyles: themeStyles, baseStyles: style, children: children }) }));
+}
+export function AppEmbed({ app, mode, accent, colorMode = 'auto', font, serverUrl, instance, height = 640, ownPortal = false, }) {
+    const system = useSystemMode();
+    const resolvedMode = colorMode === 'auto' ? system : colorMode;
+    const shownAs = mode ?? app.deployment.embedded?.mode ?? 'inline';
+    const view = floatingViewOf(shownAs);
+    return (_jsxs(EmbedThemed, { accent: accent ?? app.interface.accent, colorMode: resolvedMode, font: font, style: view
+            ? // Floating: nothing in the page's flow, nothing painted behind.
+                { backgroundColor: 'transparent' }
+            : { height, display: 'flex', flexDirection: 'column' }, children: [ownPortal ? _jsx(OwnPortalRoot, {}) : null, view && serverUrl ? (_jsx(ServerFloating, { app: app, view: view, serverUrl: serverUrl, colorMode: resolvedMode })) : view ? (_jsx(DatalayerFloating, { app: app, view: view, instance: instance, colorMode: resolvedMode })) : (_jsx(AppRenderer, { app: app, target: serverUrl ? 'local' : 'datalayer', ...(serverUrl ? { serverUrl } : {}), instance: instance }))] }));
+}
+export default AppEmbed;

package/lib/loop/embed/datalayer-app.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/loop/embed/datalayer-app.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The one script a host loads (LOOP D-08): it defines `<datalayer-app>` and
+ * nothing else. Built on its own by `npm run build:embed`
+ * (`vite.embed.config.ts`) into `dist-embed/datalayer-app.js`, with the
+ * stylesheet the element links into its shadow root beside it
+ * (`dist-embed/datalayer-app.css`); served from a Datalayer origin at
+ * `/embed/`.
+ *
+ * @module loop/embed/datalayer-app
+ */
+import { defineDatalayerAppElement } from './element';
+defineDatalayerAppElement();

package/lib/loop/embed/element.d.ts

@@ -0,0 +1,57 @@
+import type { AppSpec } from '../../types/agentspecs';
+import { type ParsedAppspec } from '../apps/appspec';
+/** What the framed run page and the element say to each other. */
+export declare const EMBED_MESSAGES: {
+    readonly size: "datalayer-app:size";
+    readonly decision: "datalayer-app:decision";
+    /** To the frame: an embed token, the first or a new one. */
+    readonly token: "datalayer-app:token";
+    /** From the frame: the token lapsed; a new one is needed. */
+    readonly tokenExpired: "datalayer-app:token-expired";
+};
+/** Where an application comes from, once read. */
+export type EmbedSource = {
+    kind: 'spec';
+    app: AppSpec;
+} | {
+    kind: 'frame';
+    src: string;
+} | {
+    kind: 'said';
+    text: string;
+    expired?: boolean;
+};
+/** An Appspec from its text, YAML or JSON; refused in a sentence when it is neither. */
+export declare function appspecOfText(text: string): AppSpec;
+/**
+ * An application the embed can run, or a sentence saying why not: one with
+ * an id, and an agent to answer — what the spec tolerates in a draft, an
+ * embed cannot run.
+ */
+export declare function runnable({ app, problems }: ParsedAppspec): AppSpec;
+/** The run page an application on Datalayer is framed from. */
+export declare function frameSrcOf(origin: string, app: string, token?: string): string;
+/**
+ * An application on Datalayer, read with its embed token: what the space
+ * keeps of it (`model_s`, the stored definition), whose `spec` is the
+ * Appspec. A decision is framed; so is an application that has no spec.
+ */
+export declare function readEmbeddedApp({ api, origin, app, token, fetcher, }: {
+    api: string;
+    origin: string;
+    app: string;
+    token: string;
+    fetcher?: typeof fetch;
+}): Promise<EmbedSource>;
+export type DatalayerAppElementOptions = {
+    /** The element's name; `datalayer-app` by default. */
+    tag?: string;
+    /** Where the script was loaded from: the default origin, and where its stylesheet is. */
+    scriptUrl?: string;
+};
+/**
+ * Define the element, once. Returns its class, or `undefined` where there is
+ * no `customElements` (a server render) — a second call returns the class
+ * already defined.
+ */
+export declare function defineDatalayerAppElement(options?: DatalayerAppElementOptions): CustomElementConstructor | undefined;