@datalayer/agent-runtimes 1.3.28 → 1.3.30

package/lib/loop/apps/AppRenderer.js

@@ -16,13 +16,26 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
  *   created with the application in its payload — so the runtime reaches only
  *   what the application connects to and enforces its rules before every tool
  *   call — and the application's starters as the openers of the empty chat;
- * - the **layout of its kind**: a chat is the conversation alone, with the
- *   A2UI surfaces its answers draw; the other layouts keep the editors.
+ * - its **layout**, as `interface.layout` says (`appLayoutOptions`, LOOP
+ *   T-07), on the workspace's own `page-layout` plugin: `chat` is the
+ *   conversation alone, with the A2UI surfaces its answers draw; `page` is
+ *   the page on a sheet with the composer over it and the conversation in a
+ *   panel the composer's display modes open; `split` is the conversation and
+ *   the page side by side, a hairline between them to drag;
+ * - its **page**, when it has one (`hasAppPage`: a chat, a widget or a worker
+ *   with a `page` or `split` layout): its A2UI surface drawn by the
+ *   `app-page` plugin, in place of the notebook and the document, fed from
+ *   the conversation and answered through it (`APP_KIND_PATHS`). A
+ *   decision's page stays the Studio's run page (R-02); its layout keeps the
+ *   editors;
+ * - its **frame**, when the host asks (`frame`): the `window-frame` plugin's
+ *   window, its title the application's face and name.
  *
  * @module loop/apps/AppRenderer
  */
 import { useMemo } from 'react';
 import { defineAgentCapacityPlugin } from '../plugins/agent-capacity';
+import { APP_PAGE_SURFACE, defineAppPagePlugin, hasAppPage, } from '../plugins/app-page';
 import { LoopEmbed } from '../embed/LoopEmbed';
 import { dumpAppspec } from './appspec';
 /** The id of an agent or a Cog, without its version. */
@@ -64,8 +77,75 @@ export function defineAppPlugin(app) {
             text: starter.label,
             message: starter.message,
         })),
+        // In the page, the agent is told what a runtime tells it: its own
+        // spec's prompt, then the application's instructions; on the
+        // application's model when it names one (`loop/apps/agent`).
+        instructions: app.instructions,
+        model: app.model,
     });
 }
+/**
+ * The workspace an application's layout asks for (LOOP T-07).
+ *
+ * - `chat`: the conversation alone — no editor, no page, no strip.
+ * - `page`: the page layout — its page (or, without one, the editors) on the
+ *   sheet; the composer a card over it, starting at the bottom, whose display
+ *   modes put it in the conversation panel beside, over or in the corner of
+ *   the page; the current turn under the composer, its copy and dismiss only.
+ * - `split`: the page layout's split — the conversation on the left with its
+ *   composer, the page on the right, a hairline between them to drag.
+ *
+ * With a page, the page is the one editor, opened, without a strip to swap
+ * it; without one (a decision, whose page is the Studio's), the editors stay.
+ */
+export function appLayoutOptions(app) {
+    const layout = app.interface.layout;
+    if (layout === 'chat') {
+        return { editors: false, showViewSelector: false };
+    }
+    const withPage = hasAppPage(app);
+    return {
+        editors: !withPage,
+        showViewSelector: !withPage,
+        ...(withPage ? { defaultEditor: APP_PAGE_SURFACE } : {}),
+        pageLayout: true,
+        pageLayoutArrangement: layout === 'split' ? 'split' : 'page',
+        pageLayoutPrompt: 'floating',
+        pageLayoutPromptAnchor: 'bottom',
+        pageLayoutTurnPanelFooter: 'actions',
+    };
+}
+/**
+ * What an application's agent is created with on a Datalayer runtime: under
+ * the application's id, over AG-UI, with the application's own document —
+ * so that the runtime registers it and decides every tool call by its rules
+ * (LOOP R-03, R-05), as `loop apps run --cloud` does. One payload for every
+ * place it runs: the workspace (`AppRenderer`) and the embed's floating
+ * modes (`AppEmbed`).
+ */
+export function appDatalayerCreatePayload(app, instance) {
+    return {
+        // Under the application's id, over AG-UI: what the workspace's
+        // chat addresses (`AppRenderer` gives it as `agentId`).
+        name: app.id,
+        transport: 'ag-ui',
+        agent_spec_id: agentIdOf(app),
+        app_spec: dumpAppspec(app),
+        // Code Mode calls every tool through `execute_code`, which an
+        // application without a shell is refused: its tools are called
+        // one by one instead, each decided by its rules.
+        enable_codemode: Boolean(app.permissions?.computer?.shell),
+        ...(instance
+            ? {
+                app_instance: {
+                    app_uid: instance.appUid ?? '',
+                    deployment_uid: instance.deploymentUid ?? '',
+                    version: instance.version ?? 0,
+                },
+            }
+            : {}),
+    };
+}
 /**
  * An application in a LOOP workspace: its agent, its starters, its layout.
  *
@@ -76,8 +156,7 @@ export function defineAppPlugin(app) {
 /** The agentspec a runtime is allocated with before an application's agent is created on it. */
 export const DATALAYER_BOOTSTRAP_AGENTSPEC = 'example-simple';
 const NO_PLUGINS = [];
-export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, ...embed }) {
-    const chatOnly = app.interface.layout === 'chat';
+export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, frame = false, ...embed }) {
     /*
      * The application plugin, made once per application. `LoopEmbed` rebuilds
      * its whole reactor when its plugins change, so a new plugin on every
@@ -88,36 +167,20 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, .
     const appPlugin = useMemo(() => (app.agent ? defineAppPlugin(app) : null), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [source]);
-    const allPlugins = useMemo(() => (appPlugin ? [appPlugin, ...plugins] : plugins), [appPlugin, plugins]);
+    const withPage = hasAppPage(app);
+    const pagePlugin = useMemo(() => (withPage ? defineAppPagePlugin(app) : null), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [source, withPage]);
+    const allPlugins = useMemo(() => appPlugin
+        ? [appPlugin, ...(pagePlugin ? [pagePlugin] : []), ...plugins]
+        : plugins, [appPlugin, pagePlugin, plugins]);
     /*
      * On Datalayer, the application runs on a runtime: allocated with a plain
      * agentspec, its agent created there with the application's spec — so that
      * the runtime registers it and decides every tool call by its rules (LOOP
      * R-03, R-05), as `loop apps run --cloud` does.
      */
-    const datalayerCreatePayload = useMemo(() => app.agent
-        ? {
-            // Under the application's id, over AG-UI: what the workspace's
-            // chat addresses (`agentId` below).
-            name: app.id,
-            transport: 'ag-ui',
-            agent_spec_id: agentIdOf(app),
-            app_spec: dumpAppspec(app),
-            // Code Mode calls every tool through `execute_code`, which an
-            // application without a shell is refused: its tools are called
-            // one by one instead, each decided by its rules.
-            enable_codemode: Boolean(app.permissions?.computer?.shell),
-            ...(instance
-                ? {
-                    app_instance: {
-                        app_uid: instance.appUid ?? '',
-                        deployment_uid: instance.deploymentUid ?? '',
-                        version: instance.version ?? 0,
-                    },
-                }
-                : {}),
-        }
-        : undefined, 
+    const datalayerCreatePayload = useMemo(() => (app.agent ? appDatalayerCreatePayload(app, instance) : undefined), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [source, instance?.appUid, instance?.deploymentUid, instance?.version]);
     if (!appPlugin) {
@@ -129,7 +192,11 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, .
     , { 
         // The application's own agent: created under its id, so that its
         // spec is applied to an agent of its own, never to the one it extends.
-        agentId: app.id, editors: !chatOnly, showViewSelector: !chatOnly, teamPicker: false, showAgentVariants: false, graph: false, pluginsPanel: false, datalayerAgentSpecId: DATALAYER_BOOTSTRAP_AGENTSPEC, 
+        agentId: app.id, ...appLayoutOptions(app), ...(frame
+            ? {
+                frameTitle: [app.emoji, app.name].filter(Boolean).join(' '),
+            }
+            : {}), teamPicker: false, showAgentVariants: false, graph: false, pluginsPanel: false, datalayerAgentSpecId: DATALAYER_BOOTSTRAP_AGENTSPEC, 
         // Where an application runs is decided by its host — the Studio's
         // Preview, the hosted page — not offered to its user.
         targetFixed: true, 

package/lib/loop/apps/agent.d.ts

@@ -0,0 +1,15 @@
+import type { Agentspec } from '../../types/agentspecs';
+/** An agent of the catalogue, or a Cog's agent, by `id` or `id:version`. */
+export declare function resolveAgentspec(reference: string): Agentspec | undefined;
+/**
+ * What the agent is told: its spec's system prompt, then what the
+ * application tells it on top — as the runtime joins them.
+ */
+export declare function agentInstructions(spec: Pick<Agentspec, 'systemPrompt'> | undefined, extra?: string): string | undefined;
+/**
+ * Why an agent turned in the page cannot run, or undefined when it can.
+ *
+ * An agent named by a reference that resolves to nothing would answer with
+ * no instructions — bare — which is not the agent that was asked for.
+ */
+export declare function inPageAgentRefusal(reference: string | undefined, spec: Agentspec | undefined): string | undefined;

package/lib/loop/apps/agent.js

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The agent an application runs, as the page turns it (LOOP H-01, E-11).
+ *
+ * On a runtime, an application's agent is its agent's spec — an agent of the
+ * catalogue, or a Cog's, which is an agent equipped with Frames, their
+ * context already in its system prompt — and the application's own
+ * instructions on top of it (`get_library_agent_spec` and the create route
+ * in `agent_runtimes/routes/agents.py`). The page turns the same agent in the
+ * browser, so it resolves it the same way: an application on a Cog that the
+ * page looked up among the agentspecs alone ran with no instructions at all.
+ *
+ * @module loop/apps/agent
+ */
+import { getAgentspecs } from '../../specs/agents';
+import { getCog } from '../../specs/cogs';
+/** An agent of the catalogue, or a Cog's agent, by `id` or `id:version`. */
+export function resolveAgentspec(reference) {
+    return getAgentspecs(reference) ?? getCog(reference)?.spec;
+}
+/**
+ * What the agent is told: its spec's system prompt, then what the
+ * application tells it on top — as the runtime joins them.
+ */
+export function agentInstructions(spec, extra) {
+    const parts = [spec?.systemPrompt?.trim(), extra?.trim()].filter((part) => Boolean(part));
+    return parts.length > 0 ? parts.join('\n\n') : undefined;
+}
+/**
+ * Why an agent turned in the page cannot run, or undefined when it can.
+ *
+ * An agent named by a reference that resolves to nothing would answer with
+ * no instructions — bare — which is not the agent that was asked for.
+ */
+export function inPageAgentRefusal(reference, spec) {
+    return reference && !spec
+        ? `There is no agent or Cog named “${reference}” in this page, so it cannot answer here.`
+        : undefined;
+}

package/lib/loop/apps/appspec.d.ts

@@ -24,13 +24,17 @@
  *
  * @module loop/apps/appspec
  */
-import type { AppAccent, AppKind, AppLayout, AppSpec } from '../../types/agentspecs';
+import type { AppAccent, AppAssistantCharacter, AppEmbedMode, AppKind, AppLayout, AppSpec } from '../../types/agentspecs';
 /** The version of the spec itself. */
 export declare const APP_SCHEMA = "loop.app/v1";
 /** The face of an application that has not chosen one. */
 export declare const DEFAULT_EMOJI = "\uD83D\uDC40";
 export declare const APP_KINDS: AppKind[];
 export declare const APP_ACCENTS: AppAccent[];
+/** The four ways an application sits in another product's page (LOOP D-07). */
+export declare const APP_EMBED_MODES: AppEmbedMode[];
+/** The characters an Appspec may name for its floating assistant (LOOP T-24). */
+export declare const APP_ASSISTANT_CHARACTERS: AppAssistantCharacter[];
 /** The layout a kind starts with. */
 export declare const DEFAULT_LAYOUTS: Record<AppKind, AppLayout>;
 /** What an application keeps of what it did, when it does not say. */

package/lib/loop/apps/appspec.js

@@ -16,6 +16,20 @@ export const APP_ACCENTS = [
     'sun',
     'violet',
 ];
+/** The four ways an application sits in another product's page (LOOP D-07). */
+export const APP_EMBED_MODES = [
+    'inline',
+    'bubble',
+    'panel',
+    'assistant',
+];
+/** The characters an Appspec may name for its floating assistant (LOOP T-24). */
+export const APP_ASSISTANT_CHARACTERS = [
+    'paperclip',
+    'wizard',
+    'cat',
+    'eyes',
+];
 const ACTION_CLASS_NAMES = [
     'read',
     'write',
@@ -203,6 +217,9 @@ function parseInterface(data, kind) {
     if (isData(data.surface)) {
         parsed.surface = parseSurface(data.surface);
     }
+    if (APP_ASSISTANT_CHARACTERS.includes(data.assistant)) {
+        parsed.assistant = data.assistant;
+    }
     return parsed;
 }
 function parseCriterion(data) {
@@ -239,7 +256,7 @@ function parseDeployment(data) {
     }
     if (isData(data.embedded)) {
         deployment.embedded = {
-            mode: oneOf(data.embedded.mode, ['inline', 'bubble', 'panel'], 'inline'),
+            mode: oneOf(data.embedded.mode, APP_EMBED_MODES, 'inline'),
             origins: texts(data.embedded.origins),
         };
     }
@@ -454,6 +471,9 @@ function dumpInterface(spec, kind) {
     if (spec.surface) {
         writer.data.surface = dumpSurface(spec.surface);
     }
+    if (spec.assistant) {
+        writer.data.assistant = spec.assistant;
+    }
     return writer.data;
 }
 function dumpDecision(decision) {

package/lib/loop/apps/checks.js

@@ -370,7 +370,8 @@ const ENUMS = {
         'feedback',
     ],
     visibility: ['private', 'invited', 'organization', 'link', 'public'],
-    mode: ['inline', 'bubble', 'panel'],
+    mode: ['inline', 'bubble', 'panel', 'assistant'],
+    character: ['paperclip', 'wizard', 'cat', 'eyes'],
     trigger: ['schedule', 'event', 'once'],
     criterion: ['metric', 'noul', 'choice', 'score'],
     direction: ['higher', 'lower'],
@@ -498,6 +499,7 @@ export function documentShapeProblems(document) {
     mapping(d.interface, 'interface', ui => {
         oneOf(ui.layout, ENUMS.layout, 'interface.layout');
         oneOf(ui.accent, ENUMS.accent, 'interface.accent');
+        oneOf(ui.assistant, ENUMS.character, 'interface.assistant');
         text(ui.welcome, 'interface.welcome');
         texts(ui.components, 'interface.components');
         records(ui.starters, 'interface.starters', (item, where) => {

package/lib/loop/apps/index.d.ts

@@ -3,6 +3,7 @@
  *
  * @module loop/apps
  */
+export * from './agent';
 export * from './AppRenderer';
 export * from './appspec';
 export * from './checks';

package/lib/loop/apps/index.js

@@ -7,6 +7,7 @@
  *
  * @module loop/apps
  */
+export * from './agent';
 export * from './AppRenderer';
 export * from './appspec';
 export * from './checks';

package/lib/loop/core/index.d.ts

@@ -4,6 +4,8 @@ import type { ExecutionState } from '@datalayer/jupyter-react/kernel-indicator';
 import type { ToolbarItem } from '@datalayer/primer-addons';
 import type { FrontendToolDefinition } from '../../types/tools';
 import type { ContextSnapshotData } from '../../types/context';
+import type { AssistantCharacter } from '../../chat/assistant/characters';
+import type { AssistantCharacterData } from '../../chat/assistant/formats/types';
 /** Lifecycle of the sandbox a workspace is attached to. */
 export type SandboxState = 'idle' | 'starting' | 'running' | 'stopping' | 'error';
 /** What the workspace knows about the sandbox behind it. */
@@ -481,6 +483,14 @@ export type AgentBlueprintContribution = {
     specId?: string;
     /** Extra fields merged into the server's create-agent payload. */
     createPayload?: Record<string, unknown>;
+    /**
+     * What the agent is told on top of its spec's system prompt — an
+     * application's instructions — when the page turns it, as a runtime
+     * appends them.
+     */
+    instructions?: string;
+    /** The model it runs on in the page, in place of its spec's. */
+    model?: string;
 };
 export declare const LoopAgentBlueprint: import("@datalayer/reactor").ContributionPoint<AgentBlueprintContribution>;
 /** One conversation opener a plugin offers on the empty chat. */
@@ -503,6 +513,19 @@ export type ChatSuggestionContribution = {
     suggestions: ChatSuggestionItem[];
 };
 export declare const LoopChatSuggestion: import("@datalayer/reactor").ContributionPoint<ChatSuggestionContribution>;
+/**
+ * A character the floating assistant may show (LOOP T-24): a drawing — one
+ * of Datalayer's own (T-25) or a plugin's — or a character read from a file
+ * a person holds the rights to (T-26). The catalogue of characters is what
+ * the enabled plugins contribute here, and nothing else; an application
+ * names one by id (`interface.assistant`).
+ */
+export type AssistantCharacterContribution = {
+    /** Stable id, what an application names. */
+    id: string;
+    character: AssistantCharacter | AssistantCharacterData;
+};
+export declare const LoopAssistantCharacter: import("@datalayer/reactor").ContributionPoint<AssistantCharacterContribution>;
 /**
  * The per-example chat extras a host feeds the loop's conversation live.
  *

package/lib/loop/core/index.js

@@ -141,6 +141,7 @@ export const LoopChatComposer = defineContributionPoint('loop.chat.composer');
 export const LoopChatHeader = defineContributionPoint('loop.chat.header');
 export const LoopAgentBlueprint = defineContributionPoint('loop.agent.blueprint');
 export const LoopChatSuggestion = defineContributionPoint('loop.chat.suggestion');
+export const LoopAssistantCharacter = defineContributionPoint('loop.assistant.character');
 export const LoopChatExtras = defineContributionPoint('loop.chat.extras');
 export const LoopOpeningNotebook = defineContributionPoint('loop.notebook.opening');
 export const LoopOpeningDocument = defineContributionPoint('loop.document.opening');

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();