@datalayer/agent-runtimes 1.3.28 → 1.3.30

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;

package/lib/loop/embed/element.js

@@ -0,0 +1,405 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `<datalayer-app>`: an application in another product's page, as one
+ * script tag and one element (LOOP D-08), in the mode its Appspec says
+ * (D-07), its theme isolated from the host's and overridable in the three
+ * ways that matter (T-13, D-11).
+ *
+ *   <script src="https://datalayer.app/embed/datalayer-app.js" async></script>
+ *   <datalayer-app app="01M…" origin="https://datalayer.app"></datalayer-app>
+ *
+ * What it shows comes from one of three places, first found first:
+ *
+ * 1. an Appspec written in the element, as YAML or JSON
+ *    (`<script type="application/yaml">…</script>`);
+ * 2. an Appspec at an address (`spec="https://…/support-desk.yaml"`);
+ * 3. an application on Datalayer (`app`), read with its embed token
+ *    (`token`). A decision, or an application given without a token, is
+ *    framed as before: Datalayer's run page in an iframe, sized to it, its
+ *    `decision` and `token-expired` events raised on the element.
+ *
+ * Every other application is drawn here, in the element's shadow root, by
+ * `AppEmbed` — inline, or floating over the page as a bubble, a panel or the
+ * assistant. The bundle's stylesheet is linked inside that root, the
+ * styled-components rules are written into it, and Primer's overlays are
+ * drawn in it, so nothing of the application's styles reaches the page and
+ * nothing of the page's reaches the application.
+ *
+ * @module loop/embed/element
+ */
+import { createRoot } from 'react-dom/client';
+import { StyleSheetManager } from 'styled-components';
+import { loopThemeStyles } from '@datalayer/primer-addons';
+import { coreStore } from '@datalayer/core/lib/state/substates/CoreState';
+import { parseAppspec } from '../apps/appspec';
+import { readAppspecYaml } from '../apps/yaml';
+import { AppEmbed } from './AppEmbed';
+import { EMBED_HOST_VARIABLES, EMBED_OBSERVED_ATTRIBUTES, EMBED_TAG, EmbedAttributeError, embedLookOf, inlineHeightOf, } from './embedConfig';
+import { embedShadowCss } from './embedTheme';
+/** What the framed run page and the element say to each other. */
+export const EMBED_MESSAGES = {
+    size: 'datalayer-app:size',
+    decision: 'datalayer-app:decision',
+    /** To the frame: an embed token, the first or a new one. */
+    token: 'datalayer-app:token',
+    /** From the frame: the token lapsed; a new one is needed. */
+    tokenExpired: 'datalayer-app:token-expired',
+};
+/** An Appspec from its text, YAML or JSON; refused in a sentence when it is neither. */
+export function appspecOfText(text) {
+    // Written in a page, a document is indented with its markup: the
+    // indentation every line shares is the page's, not the document's.
+    const lines = text.replace(/\t/g, '  ').split('\n');
+    const indent = Math.min(...lines
+        .filter(line => line.trim())
+        .map(line => line.length - line.trimStart().length));
+    const trimmed = lines
+        .map(line => line.slice(Number.isFinite(indent) ? indent : 0))
+        .join('\n')
+        .trim();
+    if (!trimmed) {
+        throw new EmbedAttributeError('datalayer-app: the Appspec is empty.');
+    }
+    let parsed;
+    if (trimmed.startsWith('{')) {
+        let document;
+        try {
+            document = JSON.parse(trimmed);
+        }
+        catch (error) {
+            throw new EmbedAttributeError(`datalayer-app: the Appspec is not JSON (${error.message}).`);
+        }
+        parsed = parseAppspec(document);
+    }
+    else {
+        parsed = readAppspecYaml(trimmed);
+    }
+    return runnable(parsed);
+}
+/**
+ * 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 function runnable({ app, problems }) {
+    if (!app.id) {
+        throw new EmbedAttributeError(`datalayer-app: the Appspec names no application${problems.length ? ` (${problems[0]})` : ''}.`);
+    }
+    if (app.kind !== 'decision' && !app.agent) {
+        throw new EmbedAttributeError(`datalayer-app: “${app.name || app.id}” names no agent to answer; an embedded application is run by an agent (a team is not supported yet).`);
+    }
+    return app;
+}
+/** The run page an application on Datalayer is framed from. */
+export function frameSrcOf(origin, app, token = '') {
+    // The token in the fragment, which no server is sent: it reaches the page
+    // and no access log.
+    return `${origin.replace(/\/+$/, '')}/public/apps/${encodeURIComponent(app)}/run?embed=1${token ? `#token=${encodeURIComponent(token)}` : ''}`;
+}
+/**
+ * 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 async function readEmbeddedApp({ api, origin, app, token, fetcher = fetch, }) {
+    const response = await fetcher(`${api.replace(/\/+$/, '')}/api/spacer/v1/apps/${encodeURIComponent(app)}/embedded`, { headers: { Authorization: `Bearer ${token}` } });
+    if (response.status === 401) {
+        return {
+            kind: 'said',
+            text: 'datalayer-app: the embed token expired or is not for this application.',
+            expired: true,
+        };
+    }
+    if (!response.ok) {
+        return {
+            kind: 'said',
+            text: `datalayer-app: the application could not be read (${response.status}).`,
+        };
+    }
+    const body = (await response.json());
+    let definition;
+    try {
+        definition = JSON.parse(String(body.app?.model_s ?? '{}'));
+    }
+    catch {
+        definition = {};
+    }
+    if (!definition.spec) {
+        return { kind: 'frame', src: frameSrcOf(origin, app, token) };
+    }
+    const spec = runnable(parseAppspec(definition.spec));
+    return spec.kind === 'decision'
+        ? { kind: 'frame', src: frameSrcOf(origin, app, token) }
+        : { kind: 'spec', app: spec };
+}
+/** The script that is running, when it is a script tag. */
+function currentScriptUrl() {
+    try {
+        const script = document.currentScript;
+        return script?.src ? new URL(script.src, location.href).href : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 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 function defineDatalayerAppElement(options = {}) {
+    if (typeof window === 'undefined' || !('customElements' in window)) {
+        return undefined;
+    }
+    const tag = options.tag ?? EMBED_TAG;
+    const existing = customElements.get(tag);
+    if (existing) {
+        return existing;
+    }
+    const scriptUrl = options.scriptUrl ?? currentScriptUrl();
+    const scriptOrigin = scriptUrl ? new URL(scriptUrl).origin : '';
+    // The bundle's stylesheet, beside its script.
+    const stylesheetUrl = scriptUrl
+        ? scriptUrl.replace(/\.js(\?.*)?$/, '.css')
+        : '';
+    class DatalayerAppElement extends HTMLElement {
+        static get observedAttributes() {
+            return EMBED_OBSERVED_ATTRIBUTES;
+        }
+        root = null;
+        frame = null;
+        source = null;
+        loading = 0;
+        constructor() {
+            super();
+            this.attachShadow({ mode: 'open' });
+            this.onMessage = this.onMessage.bind(this);
+        }
+        /** An embed token, the attribute's. Set it to hand a new one over. */
+        get token() {
+            return this.getAttribute('token') ?? '';
+        }
+        set token(value) {
+            if (value) {
+                this.setAttribute('token', String(value));
+            }
+            else {
+                this.removeAttribute('token');
+            }
+        }
+        connectedCallback() {
+            window.addEventListener('message', this.onMessage);
+            void this.load();
+        }
+        disconnectedCallback() {
+            window.removeEventListener('message', this.onMessage);
+            this.unmount();
+        }
+        attributeChangedCallback(name, before, after) {
+            if (!this.isConnected || before === after) {
+                return;
+            }
+            // A new token is handed to the framed page that is already there,
+            // which keeps what the person entered.
+            if (name === 'token' && this.frame?.contentWindow && after) {
+                this.frame.contentWindow.postMessage({ type: EMBED_MESSAGES.token, token: after }, this.origin());
+                return;
+            }
+            // How it looks is drawn again; what it is, read again.
+            if (['mode', 'accent', 'theme', 'font', 'height'].includes(name)) {
+                this.draw();
+                return;
+            }
+            void this.load();
+        }
+        origin() {
+            return (this.getAttribute('origin') ||
+                scriptOrigin ||
+                location.origin).replace(/\/+$/, '');
+        }
+        inputs() {
+            const attributes = {};
+            for (const name of EMBED_OBSERVED_ATTRIBUTES) {
+                attributes[name] = this.getAttribute(name);
+            }
+            const computed = getComputedStyle(this);
+            const variables = {};
+            for (const [key, property] of Object.entries(EMBED_HOST_VARIABLES)) {
+                const value = computed.getPropertyValue(property).trim();
+                if (value) {
+                    variables[key] = value.replace(/^["']|["']$/g, '');
+                }
+            }
+            return { attributes, variables };
+        }
+        /** Where the application comes from: the element's own Appspec, an address, or Datalayer. */
+        async read() {
+            const inline = this.querySelector('script[type="application/yaml"], script[type="application/json"], script[type="text/yaml"]');
+            if (inline?.textContent?.trim()) {
+                return { kind: 'spec', app: appspecOfText(inline.textContent) };
+            }
+            const spec = this.getAttribute('spec');
+            if (spec) {
+                const response = await fetch(new URL(spec, location.href).href);
+                if (!response.ok) {
+                    return {
+                        kind: 'said',
+                        text: `datalayer-app: the Appspec at ${spec} could not be read (${response.status}).`,
+                    };
+                }
+                return { kind: 'spec', app: appspecOfText(await response.text()) };
+            }
+            const app = this.getAttribute('app');
+            if (!app) {
+                return {
+                    kind: 'said',
+                    text: 'datalayer-app: the "app" attribute names the application to show, or "spec" the address of its Appspec.',
+                };
+            }
+            const token = this.token;
+            if (!token) {
+                // A public application: Datalayer's run page, framed.
+                return { kind: 'frame', src: frameSrcOf(this.origin(), app) };
+            }
+            return readEmbeddedApp({
+                api: this.getAttribute('api') ||
+                    coreStore.getState().configuration?.spacerUrl ||
+                    'https://prod1.datalayer.run',
+                origin: this.origin(),
+                app,
+                token,
+            });
+        }
+        async load() {
+            const turn = ++this.loading;
+            let source;
+            try {
+                source = await this.read();
+            }
+            catch (error) {
+                source = {
+                    kind: 'said',
+                    text: error instanceof Error
+                        ? error.message
+                        : `datalayer-app: ${String(error)}`,
+                };
+            }
+            // A later read wins over an earlier one still in flight.
+            if (turn !== this.loading || !this.isConnected) {
+                return;
+            }
+            this.source = source;
+            this.draw();
+            if (source.kind === 'said' && source.expired) {
+                this.dispatchEvent(new CustomEvent('token-expired', {
+                    detail: { app: this.getAttribute('app') ?? '' },
+                    bubbles: true,
+                    composed: true,
+                }));
+            }
+        }
+        unmount() {
+            this.root?.unmount();
+            this.root = null;
+            this.frame = null;
+        }
+        /** The shadow root's skeleton: the bundle's stylesheet, the element's own, and what goes in it. */
+        skeleton(themeCss) {
+            const shadow = this.shadowRoot;
+            this.unmount();
+            shadow.replaceChildren();
+            if (stylesheetUrl) {
+                const link = document.createElement('link');
+                link.rel = 'stylesheet';
+                link.href = stylesheetUrl;
+                shadow.appendChild(link);
+            }
+            const style = document.createElement('style');
+            style.textContent = embedShadowCss(themeCss);
+            shadow.appendChild(style);
+            return shadow;
+        }
+        say(text) {
+            this.setAttribute('data-embed-mode', 'inline');
+            const shadow = this.skeleton();
+            const note = document.createElement('p');
+            note.className = 'datalayer-app-said';
+            note.setAttribute('role', 'status');
+            note.textContent = text;
+            shadow.appendChild(note);
+        }
+        draw() {
+            const source = this.source;
+            if (!source) {
+                return;
+            }
+            if (source.kind === 'said') {
+                this.say(source.text);
+                return;
+            }
+            if (source.kind === 'frame') {
+                this.setAttribute('data-embed-mode', 'inline');
+                const shadow = this.skeleton();
+                const frame = document.createElement('iframe');
+                frame.className = 'datalayer-app-frame';
+                frame.src = source.src;
+                frame.title = 'Datalayer app';
+                frame.style.height = `${inlineHeightOf(this.getAttribute('height'))}px`;
+                frame.setAttribute('allow', 'clipboard-write');
+                shadow.appendChild(frame);
+                this.frame = frame;
+                return;
+            }
+            let look;
+            try {
+                look = embedLookOf(this.inputs(), source.app);
+            }
+            catch (error) {
+                this.say(error.message);
+                return;
+            }
+            this.setAttribute('data-embed-mode', look.mode);
+            const shadow = this.skeleton(loopThemeStyles.css);
+            const mount = document.createElement('div');
+            mount.className = 'datalayer-app-root';
+            shadow.appendChild(mount);
+            this.root = createRoot(mount);
+            const server = this.getAttribute('server') || undefined;
+            this.root.render(_jsx(StyleSheetManager, { target: shadow, children: _jsx(AppEmbed, { app: source.app, mode: look.mode, accent: look.accent, colorMode: look.colorMode, font: look.font, serverUrl: server, height: inlineHeightOf(this.getAttribute('height')), ownPortal: true }) }));
+        }
+        onMessage(event) {
+            if (!this.frame || event.source !== this.frame.contentWindow) {
+                return;
+            }
+            if (event.origin !== this.origin()) {
+                return;
+            }
+            const data = (event.data ?? {});
+            if (data.type === EMBED_MESSAGES.size &&
+                typeof data.height === 'number' &&
+                data.height > 0) {
+                this.frame.style.height = `${Math.ceil(data.height)}px`;
+            }
+            else if (data.type === EMBED_MESSAGES.decision) {
+                this.dispatchEvent(new CustomEvent('decision', {
+                    detail: data.record,
+                    bubbles: true,
+                    composed: true,
+                }));
+            }
+            else if (data.type === EMBED_MESSAGES.tokenExpired) {
+                this.dispatchEvent(new CustomEvent('token-expired', {
+                    detail: { app: this.getAttribute('app') ?? '' },
+                    bubbles: true,
+                    composed: true,
+                }));
+            }
+        }
+    }
+    customElements.define(tag, DatalayerAppElement);
+    return DatalayerAppElement;
+}

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

@@ -0,0 +1,120 @@
+/**
+ * An application in another product's page, as its host writes it (LOOP
+ * D-07, D-08, D-11, T-13): one script tag and one element, `<datalayer-app>`,
+ * whose attributes — or, for the theme, the host's CSS variables — say what
+ * it shows and how it looks.
+ *
+ * Pure: what the element's attributes mean, the four modes and the chat each
+ * floats in, what a host may override and how it is checked, and the snippet
+ * the *Ship* tab copies. Nothing here touches the DOM, so all of it is read
+ * and tested without one.
+ *
+ * @module loop/embed/embedConfig
+ */
+import type { AppAccent, AppEmbedMode, AppSpec } from '../../types/agentspecs';
+/** The element's name: the one a host writes. */
+export declare const EMBED_TAG = "datalayer-app";
+/** Where the script is served on a Datalayer origin; the stylesheet beside it. */
+export declare const EMBED_SCRIPT_PATH = "/embed/datalayer-app.js";
+export declare const EMBED_STYLESHEET_PATH = "/embed/datalayer-app.css";
+/**
+ * The element's attributes, each in a sentence — what the documentation and
+ * the element's own refusals say.
+ */
+export declare const EMBED_ATTRIBUTES: {
+    readonly app: "The application’s id on Datalayer.";
+    readonly origin: "Where Datalayer is; the origin the script was loaded from by default.";
+    readonly token: "An embed token for an application that is not public, issued to your server for each visit.";
+    readonly spec: "The address of an Appspec (YAML or JSON) to run, in place of `app`.";
+    readonly mode: "inline, bubble, panel or assistant; the Appspec’s `deployment.embedded.mode` by default, then inline.";
+    readonly accent: "green, rose, sky, lime, sun or violet; the Appspec’s `interface.accent` by default.";
+    readonly theme: "light, dark or auto (the visitor’s system); auto by default.";
+    readonly font: "A CSS font family for the application’s text; Inter, then the system’s sans-serif, by default.";
+    readonly server: "An agent-runtimes server the application’s agent runs on; a Datalayer runtime by default.";
+    readonly api: "Datalayer’s API, where an application is read with its token; the platform’s by default.";
+    readonly height: "The height of an inline application, in pixels; 640 by default.";
+};
+export type EmbedAttribute = keyof typeof EMBED_ATTRIBUTES;
+/** Every attribute the element watches. */
+export declare const EMBED_OBSERVED_ATTRIBUTES: EmbedAttribute[];
+/**
+ * What a host may set from its own stylesheet, on the element or above it
+ * (D-11): the accent, the face and the mode. An attribute says the same and
+ * wins over the variable.
+ */
+export declare const EMBED_HOST_VARIABLES: {
+    readonly accent: "--datalayer-app-accent";
+    readonly font: "--datalayer-app-font";
+    readonly theme: "--datalayer-app-theme";
+};
+export type EmbedColorMode = 'light' | 'dark' | 'auto';
+export declare const EMBED_COLOR_MODES: EmbedColorMode[];
+/** The chat each floating mode is drawn as (`ChatFloating`'s view modes). */
+export type EmbedFloatingView = 'floating-small' | 'panel' | 'assistant';
+/**
+ * The four modes (D-07), and the chat they float in: a **bubble** is the
+ * round button that opens a popup — the copilot pattern; a **panel** is the
+ * conversation at the page's right edge, at full height; the **assistant** is
+ * the character that speaks in a balloon (§6.9). **Inline** has no chat of
+ * its own to float: the application, its page and its conversation, sit in
+ * the host's page where the element is.
+ */
+export declare const EMBED_FLOATING_VIEWS: Record<Exclude<AppEmbedMode, 'inline'>, EmbedFloatingView>;
+/** The chat a mode floats in; none for inline. */
+export declare function floatingViewOf(mode: AppEmbedMode): EmbedFloatingView | undefined;
+/** A value the element refuses, said in a sentence for the page to show. */
+export declare class EmbedAttributeError extends Error {
+    constructor(message: string);
+}
+/**
+ * A font family a host names, checked: names, quotes, commas and spaces, as
+ * a `font-family` is written — nothing that could close the declaration or
+ * fetch anything (`;`, braces, `url(`).
+ */
+export declare function checkedFont(value: string | null | undefined): string;
+/** What the element was told, as text: its attributes and the host's variables. */
+export type EmbedInputs = {
+    attributes: Partial<Record<EmbedAttribute, string | null>>;
+    /** The host's CSS variables, read on the element (`EMBED_HOST_VARIABLES`). */
+    variables?: Partial<Record<keyof typeof EMBED_HOST_VARIABLES, string>>;
+};
+/** How an application is shown and dressed in a host's page. */
+export type EmbedLook = {
+    mode: AppEmbedMode;
+    /** The accent the host chose, or the application's own. */
+    accent: AppAccent;
+    colorMode: EmbedColorMode;
+    /** The host's face; empty for the theme's own. */
+    font: string;
+};
+/**
+ * What the element shows and how, from what the host wrote and what the
+ * application says: an attribute first, then the host's CSS variable, then
+ * the Appspec, then the default. A value that is not one is refused with a
+ * sentence (`EmbedAttributeError`), never quietly replaced.
+ */
+export declare function embedLookOf(inputs: EmbedInputs, app?: Pick<AppSpec, 'interface' | 'deployment'>): EmbedLook;
+/** The height of an inline application, in pixels. */
+export declare function inlineHeightOf(value: string | null | undefined): number;
+/** What a snippet says beside the application's id. */
+export type EmbedSnippetOptions = {
+    /** Where Datalayer is: the script's origin, and the element's. */
+    origin: string;
+    /** The application's id. */
+    app: string;
+    /** Written when given — the *Ship* tab writes the Appspec's own. */
+    mode?: AppEmbedMode;
+    /** An embed token, for an application that is not public. */
+    token?: string;
+    accent?: AppAccent;
+    theme?: EmbedColorMode;
+    font?: string;
+};
+/**
+ * The snippet a host pastes (D-08): one script tag and one element. A public
+ * application needs no token; a private one takes the token its owner was
+ * issued for it, written as given, so the snippet works for as long as the
+ * token lives — a host's own page writes the one its server is issued for
+ * each visit.
+ */
+export declare function embedSnippetOf(options: EmbedSnippetOptions): string;