@datalayer/agent-runtimes 1.3.28 → 1.3.30

package/lib/loop/embed/embedConfig.js

@@ -0,0 +1,148 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { APP_ACCENTS, APP_EMBED_MODES } from '../apps/appspec';
+/** The element's name: the one a host writes. */
+export const EMBED_TAG = 'datalayer-app';
+/** Where the script is served on a Datalayer origin; the stylesheet beside it. */
+export const EMBED_SCRIPT_PATH = '/embed/datalayer-app.js';
+export 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 const EMBED_ATTRIBUTES = {
+    app: 'The application’s id on Datalayer.',
+    origin: 'Where Datalayer is; the origin the script was loaded from by default.',
+    token: 'An embed token for an application that is not public, issued to your server for each visit.',
+    spec: 'The address of an Appspec (YAML or JSON) to run, in place of `app`.',
+    mode: 'inline, bubble, panel or assistant; the Appspec’s `deployment.embedded.mode` by default, then inline.',
+    accent: 'green, rose, sky, lime, sun or violet; the Appspec’s `interface.accent` by default.',
+    theme: 'light, dark or auto (the visitor’s system); auto by default.',
+    font: 'A CSS font family for the application’s text; Inter, then the system’s sans-serif, by default.',
+    server: 'An agent-runtimes server the application’s agent runs on; a Datalayer runtime by default.',
+    api: 'Datalayer’s API, where an application is read with its token; the platform’s by default.',
+    height: 'The height of an inline application, in pixels; 640 by default.',
+};
+/** Every attribute the element watches. */
+export const EMBED_OBSERVED_ATTRIBUTES = Object.keys(EMBED_ATTRIBUTES);
+/**
+ * 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 const EMBED_HOST_VARIABLES = {
+    accent: '--datalayer-app-accent',
+    font: '--datalayer-app-font',
+    theme: '--datalayer-app-theme',
+};
+export const EMBED_COLOR_MODES = ['light', 'dark', 'auto'];
+/**
+ * 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 const EMBED_FLOATING_VIEWS = {
+    bubble: 'floating-small',
+    panel: 'panel',
+    assistant: 'assistant',
+};
+/** The chat a mode floats in; none for inline. */
+export function floatingViewOf(mode) {
+    return mode === 'inline' ? undefined : EMBED_FLOATING_VIEWS[mode];
+}
+/** A value the element refuses, said in a sentence for the page to show. */
+export class EmbedAttributeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EmbedAttributeError';
+    }
+}
+const listed = (values) => `${values.slice(0, -1).join(', ')} or ${values[values.length - 1]}`;
+function oneOf(value, allowed, what) {
+    const text = value?.trim();
+    if (!text) {
+        return undefined;
+    }
+    if (!allowed.includes(text)) {
+        throw new EmbedAttributeError(`datalayer-app: "${text}" is not ${what}; it is ${listed(allowed)}.`);
+    }
+    return text;
+}
+/**
+ * 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 function checkedFont(value) {
+    const text = value?.trim() ?? '';
+    if (!text) {
+        return '';
+    }
+    if (!/^[\w\s,"'.-]+$/u.test(text)) {
+        throw new EmbedAttributeError(`datalayer-app: the font "${text}" is not a font family; write it as a CSS font-family is written, such as "Georgia, serif".`);
+    }
+    return text;
+}
+/**
+ * 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 function embedLookOf(inputs, app) {
+    const { attributes, variables = {} } = inputs;
+    const mode = oneOf(attributes.mode, APP_EMBED_MODES, 'a mode') ??
+        app?.deployment?.embedded?.mode ??
+        'inline';
+    const accent = oneOf(attributes.accent, APP_ACCENTS, 'an accent') ??
+        oneOf(variables.accent, APP_ACCENTS, 'an accent') ??
+        app?.interface?.accent ??
+        'green';
+    const colorMode = oneOf(attributes.theme, EMBED_COLOR_MODES, 'a theme') ??
+        oneOf(variables.theme, EMBED_COLOR_MODES, 'a theme') ??
+        'auto';
+    const font = checkedFont(attributes.font) || checkedFont(variables.font);
+    return { mode, accent, colorMode, font };
+}
+/** The height of an inline application, in pixels. */
+export function inlineHeightOf(value) {
+    const height = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(height) && height >= 240 ? height : 640;
+}
+const attributeValue = (value) => value
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+/**
+ * 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 function embedSnippetOf(options) {
+    const origin = options.origin.replace(/\/+$/, '');
+    const attributes = [
+        ['app', options.app],
+        ['origin', origin],
+        ['mode', options.mode],
+        ['accent', options.accent],
+        ['theme', options.theme],
+        ['font', options.font ? checkedFont(options.font) : undefined],
+        ['token', options.token],
+    ];
+    const written = attributes
+        .filter((entry) => Boolean(entry[1]))
+        .map(([name, value]) => ` ${name}="${attributeValue(value)}"`)
+        .join('');
+    return [
+        `<script src="${attributeValue(origin + EMBED_SCRIPT_PATH)}" async></script>`,
+        `<${EMBED_TAG}${written}></${EMBED_TAG}>`,
+    ].join('\n');
+}

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

@@ -0,0 +1,24 @@
+import { type ThemeStyles } from '@datalayer/primer-addons';
+import type { AppAccent } from '../../types/agentspecs';
+/**
+ * The `loop` theme as the embed wears it: the application's accent over it
+ * in both modes (T-05), and the host's face when it named one.
+ */
+export declare function embedThemeStyles({ accent, font, }: {
+    accent: AppAccent;
+    font?: string;
+}): ThemeStyles;
+/**
+ * The element's own stylesheet, written into its shadow root.
+ *
+ * `all: initial` on the host: nothing the host page sets — a font, a colour,
+ * a line height, a text alignment — is inherited by the application. The
+ * theme's custom properties are set again inside, on the provider's element,
+ * so a host's variable of the same name never reaches what the application
+ * draws. A floating mode takes no room in the page: what it draws is fixed to
+ * the viewport.
+ *
+ * With the theme's own stylesheet, scoped to the provider's element in this
+ * root.
+ */
+export declare function embedShadowCss(themeCss?: string): string;

package/lib/loop/embed/embedTheme.js

@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { loopAccentStyles, loopFontFamily, loopThemeStyles, scopeThemeCss, THEME_SCOPE_ATTRIBUTE, } from '@datalayer/primer-addons';
+/** One mode's properties, with the theme's face replaced by the host's. */
+function withFace(styles, font) {
+    if (!font) {
+        return styles;
+    }
+    return Object.fromEntries(Object.entries(styles).map(([name, value]) => [
+        name,
+        typeof value === 'string'
+            ? value.split(loopFontFamily).join(font)
+            : value,
+    ]));
+}
+/**
+ * The `loop` theme as the embed wears it: the application's accent over it
+ * in both modes (T-05), and the host's face when it named one.
+ */
+export function embedThemeStyles({ accent, font = '', }) {
+    const mode = (which) => withFace({
+        ...loopThemeStyles[which],
+        ...loopAccentStyles(accent, which),
+    }, font);
+    return {
+        ...loopThemeStyles,
+        light: mode('light'),
+        dark: mode('dark'),
+    };
+}
+/**
+ * The element's own stylesheet, written into its shadow root.
+ *
+ * `all: initial` on the host: nothing the host page sets — a font, a colour,
+ * a line height, a text alignment — is inherited by the application. The
+ * theme's custom properties are set again inside, on the provider's element,
+ * so a host's variable of the same name never reaches what the application
+ * draws. A floating mode takes no room in the page: what it draws is fixed to
+ * the viewport.
+ *
+ * With the theme's own stylesheet, scoped to the provider's element in this
+ * root.
+ */
+export function embedShadowCss(themeCss) {
+    const own = `
+:host {
+  all: initial;
+  display: block;
+  position: relative;
+  width: 100%;
+}
+:host([hidden]) {
+  display: none;
+}
+:host(:not([data-embed-mode="inline"])) {
+  width: 0;
+  height: 0;
+}
+.datalayer-app-root,
+.datalayer-app-portal {
+  font-family: var(--fontStack-sansSerif, system-ui, sans-serif);
+}
+.datalayer-app-said {
+  font: 14px/1.5 system-ui, sans-serif;
+  padding: 12px 16px;
+  border: 1px solid #d0d7de;
+  border-radius: 12px;
+  color: #1f2328;
+  background: #ffffff;
+}
+iframe.datalayer-app-frame {
+  display: block;
+  width: 100%;
+  border: 0;
+  min-height: 240px;
+}
+`;
+    return themeCss
+        ? `${own}\n${scopeThemeCss(themeCss, [`[${THEME_SCOPE_ATTRIBUTE}]`])}`
+        : own;
+}

package/lib/loop/index.d.ts

@@ -16,7 +16,7 @@ export { ChatHeaderPlugin, CHAT_HEADER_PLUGIN_NAME, } from './plugins/chat-heade
 export { InputPromptPlugin, INPUT_PROMPT_PLUGIN_NAME, type InputPromptPluginConfig, } from './plugins/input-prompt';
 export { createChatExtrasPlugin, CHAT_EXTRAS_PLUGIN_NAME, type ChatExtrasHandle, } from './plugins/chat-extras';
 export { LoopChatExtras, LoopChatLayout, LoopChatTurn, LoopOpeningDocument, LoopOpeningNotebook, LoopPromptPanel, type ChatLayoutContribution, type ChatLayoutParts, type ChatTurnContribution, type ChatTurnSnapshot, type ChatTurnStatus, type LoopChatExtrasValue, type OpeningDocumentContribution, type OpeningNotebookContribution, type PromptPanelContribution, } from './core';
-export { LoopPageLayoutPlugin, LOOP_PAGE_LAYOUT_PLUGIN_NAME, openConversationPanel, pageLayoutSheet, pageLayoutPanelOpen, setPageLayoutChatMode, type LoopPageLayoutConfig, } from './plugins/page-layout';
+export { LoopPageLayoutPlugin, LOOP_PAGE_LAYOUT_PLUGIN_NAME, openConversationPanel, pageLayoutSheet, pageLayoutPanelOpen, setPageLayoutChatMode, SplitLayout, type LoopPageLayoutConfig, } from './plugins/page-layout';
 export { useOptionalTeamSelection } from './plugins/agents/useTeamSelection';
 export type { TeamMember, TeamSelection } from './plugins/agents/team';
 export { ChatViewPlugin, CHAT_VIEW_PLUGIN_NAME } from './plugins/chat-view';
@@ -50,6 +50,7 @@ export { SANDBOX_CAPACITIES, SandboxCapacityPlugins, } from './plugins/agent-cod
 export { AgentA2uiPlugin, AGENT_A2UI_PLUGIN_NAME } from './plugins/agent-a2ui';
 export { AgentA2uiJupyterOutputPlugin, AGENT_A2UI_JUPYTER_OUTPUT_PLUGIN_NAME, } from './plugins/agent-a2ui-jupyter-output';
 export { defineA2uiScenePlugin, type A2uiSceneOptions, } from './plugins/a2ui-scene';
+export { APP_KIND_PATHS, APP_PAGE_PLUGIN_NAME, APP_PAGE_SURFACE, AppPage, appKindPaths, appPageAction, appPageData, defineAppPagePlugin, hasAppPage, surfaceUnshown, type AppKindPaths, type AppPageAction, type AppPageKind, type AppPagePath, } from './plugins/app-page';
 export { GraphViewPlugin, GRAPH_PLUGIN_NAME, GRAPH_VIEW_TYPE, } from './plugins/graph';
 export { PluginsPanelPlugin, PLUGINS_PANEL_PLUGIN_NAME, PluginsPanel, } from './plugins/plugins-panel';
 export { AGENTS_PLUGIN_NAME, AgentsPlugin, SandboxSelector, browserSource, createBrowserSandboxService, createServerSandboxService, createSwitchableSandboxService, suppliedSource, useOptionalSandboxService, useSandboxService, type AgentsConfig, type AgentsOutput, type SandboxExecution, type SandboxService, type SandboxTarget, type ServiceManagerSource, type SwitchableSandboxService, } from './plugins/agents';
@@ -63,7 +64,10 @@ export { WindowFrame, WindowFramePlugin, WINDOW_ACTIONS_SLOT, WINDOW_CONTROLS_SL
 export { LoopCommandsPlugin, COMMANDS_PLUGIN_NAME } from './plugins/commands';
 export { PromptPlugin, PROMPT_PLUGIN_NAME } from './plugins/prompt';
 export { LoopEmbed, type LoopEmbedProps } from './embed/LoopEmbed';
+export { AppEmbed, type AppEmbedProps } from './embed/AppEmbed';
+export { defineDatalayerAppElement, type DatalayerAppElementOptions, } from './embed/element';
+export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, type EmbedLook, type EmbedSnippetOptions, } from './embed/embedConfig';
 export { SubagentActivityPlugin, SubagentPulse, SUBAGENT_ACTIVITY_PLUGIN_NAME, } from './plugins/subagent-activity';
 export { loopPlugins, type LoopPresetOptions } from './presets';
 export { DocumentExtension, NotebookExtension } from './extensions';
-export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, type BehaviourOptions, type ToolArguments, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, type AppCheck, defineAppPlugin, type AppRendererProps, type AppInstance, readAppspecYaml, writeAppspecYaml, type ParsedAppspec, } from './apps';
+export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, type BehaviourOptions, type ToolArguments, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, type AppCheck, defineAppPlugin, type AppRendererProps, type AppInstance, appLayoutOptions, readAppspecYaml, writeAppspecYaml, type ParsedAppspec, } from './apps';

package/lib/loop/index.js

@@ -29,7 +29,7 @@ export { LoopChatExtras, LoopChatLayout, LoopChatTurn, LoopOpeningDocument, Loop
 export { LoopPageLayoutPlugin, LOOP_PAGE_LAYOUT_PLUGIN_NAME, openConversationPanel, pageLayoutSheet, pageLayoutPanelOpen, 
 // How a host moves the composer: `sidebar` stands it in the conversation
 // panel, under what was said, and opens the panel to show it.
-setPageLayoutChatMode, } from './plugins/page-layout';
+setPageLayoutChatMode, SplitLayout, } from './plugins/page-layout';
 export { useOptionalTeamSelection } from './plugins/agents/useTeamSelection';
 export { ChatViewPlugin, CHAT_VIEW_PLUGIN_NAME } from './plugins/chat-view';
 export { NotebookViewPlugin, NOTEBOOK_VIEW_PLUGIN_NAME, } from './plugins/notebook-view';
@@ -63,6 +63,7 @@ export { SANDBOX_CAPACITIES, SandboxCapacityPlugins, } from './plugins/agent-cod
 export { AgentA2uiPlugin, AGENT_A2UI_PLUGIN_NAME } from './plugins/agent-a2ui';
 export { AgentA2uiJupyterOutputPlugin, AGENT_A2UI_JUPYTER_OUTPUT_PLUGIN_NAME, } from './plugins/agent-a2ui-jupyter-output';
 export { defineA2uiScenePlugin, } from './plugins/a2ui-scene';
+export { APP_KIND_PATHS, APP_PAGE_PLUGIN_NAME, APP_PAGE_SURFACE, AppPage, appKindPaths, appPageAction, appPageData, defineAppPagePlugin, hasAppPage, surfaceUnshown, } from './plugins/app-page';
 export { GraphViewPlugin, GRAPH_PLUGIN_NAME, GRAPH_VIEW_TYPE, } from './plugins/graph';
 export { PluginsPanelPlugin, PLUGINS_PANEL_PLUGIN_NAME, PluginsPanel, } from './plugins/plugins-panel';
 export { AGENTS_PLUGIN_NAME, AgentsPlugin, SandboxSelector, browserSource, createBrowserSandboxService, createServerSandboxService, createSwitchableSandboxService, suppliedSource, useOptionalSandboxService, useSandboxService, } from './plugins/agents';
@@ -81,6 +82,11 @@ export { LoopCommandsPlugin, COMMANDS_PLUGIN_NAME } from './plugins/commands';
 export { PromptPlugin, PROMPT_PLUGIN_NAME } from './plugins/prompt';
 // Loop, ready to drop into somebody else's page.
 export { LoopEmbed } from './embed/LoopEmbed';
+// An application in another product's page: the React component, the
+// `<datalayer-app>` element, and the snippet a host pastes (LOOP D-07 to D-09).
+export { AppEmbed } from './embed/AppEmbed';
+export { defineDatalayerAppElement, } from './embed/element';
+export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, } from './embed/embedConfig';
 export { SubagentActivityPlugin, SubagentPulse, SUBAGENT_ACTIVITY_PLUGIN_NAME, } from './plugins/subagent-activity';
 // The set a workspace normally has, so a host starts from a working Loop
 // rather than assembling one — and never from the example.
@@ -90,4 +96,4 @@ export { loopPlugins } from './presets';
 export { DocumentExtension, NotebookExtension } from './extensions';
 // Applications: what one does when its agent calls a tool — the rules a
 // person wrote, decided on what the tool does.
-export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, defineAppPlugin, readAppspecYaml, writeAppspecYaml, } from './apps';
+export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, defineAppPlugin, appLayoutOptions, readAppspecYaml, writeAppspecYaml, } from './apps';

package/lib/loop/plugins/a2ui-surface/InlineSurface.d.ts

@@ -8,15 +8,33 @@
  * follows, and what keeps a generated form from being the one light card in
  * a dark workspace.
  *
+ * The same renderer draws an application's page (`loop/plugins/app-page`):
+ * there the surface is fed live `data` by path as the conversation moves, and
+ * an action is handed the surface it came from, so that what a block wrote
+ * into its data model can be read when a button is pressed.
+ *
  * @module loop/plugins/a2ui-surface/InlineSurface
  */
 import type { JSX } from 'react';
-import { type A2uiClientAction, type A2uiMessage } from '@a2ui/web_core/v0_9';
+import { type ReactComponentImplementation } from '@a2ui/react/v0_9';
+import { type A2uiClientAction, type A2uiMessage, type SurfaceModel } from '@a2ui/web_core/v0_9';
+/** A surface as the renderer holds it: its data model is `dataModel`. */
+export type InlineSurfaceModel = SurfaceModel<ReactComponentImplementation>;
+type Surface = InlineSurfaceModel;
 /** The catalogue a surface is rewritten to before it is drawn. */
 export declare const SURFACE_CATALOG_ID: string;
-export declare function InlineSurface({ messages, onAction, validationError, }: {
+/** Values to publish into a surface, by path. */
+export type InlineSurfaceData = Record<string, unknown>;
+export declare function InlineSurface({ messages, onAction, validationError, data, }: {
     messages: A2uiMessage[];
-    onAction: (action: A2uiClientAction) => void;
+    /** Told of an action, with the surface it came from. */
+    onAction: (action: A2uiClientAction, surface?: Surface) => void;
     validationError?: string | null;
+    /**
+     * Values published into every surface's data model, by path, after the
+     * messages are processed and whenever one changes. Only a path whose value
+     * changed is written: what a person typed elsewhere in the model stays.
+     */
+    data?: InlineSurfaceData;
 }): JSX.Element | null;
 export default InlineSurface;

package/lib/loop/plugins/a2ui-surface/InlineSurface.js

@@ -12,12 +12,14 @@ const INHERIT_THEME = {
     ['--a2ui-color-primary']: 'var(--fgColor-accent)',
     ['--a2ui-color-outline']: 'var(--borderColor-default)',
 };
-export function InlineSurface({ messages, onAction, validationError, }) {
+export function InlineSurface({ messages, onAction, validationError, data, }) {
     // Reached through a ref: the processor is built once, and the handler it
     // was built with must not go stale when the host's does not.
     const onActionRef = useRef(onAction);
     onActionRef.current = onAction;
-    const processor = useMemo(() => new MessageProcessor([basicCatalog], action => onActionRef.current(action)), []);
+    const processor = useMemo(() => new MessageProcessor([basicCatalog], action => onActionRef.current(action, processorRef.current?.model.getSurface(action.surfaceId))), []);
+    const processorRef = useRef(undefined);
+    processorRef.current = processor;
     const [surfaces, setSurfaces] = useState([]);
     useEffect(() => {
         const created = processor.onSurfaceCreated(surface => setSurfaces(previous => [...previous, surface]));
@@ -28,15 +30,41 @@ export function InlineSurface({ messages, onAction, validationError, }) {
         };
     }, [processor]);
     // Once: the messages are one tool result, processed when it arrives.
+    // A tree the catalog refuses is said, where it would have been drawn,
+    // rather than thrown out of an effect and taking the page down with it.
     const processedRef = useRef(false);
+    const [processError, setProcessError] = useState(null);
     useEffect(() => {
         if (processedRef.current) {
             return;
         }
         processedRef.current = true;
-        processor.processMessages(messages);
+        try {
+            processor.processMessages(messages);
+        }
+        catch (error) {
+            setProcessError(`This surface could not be drawn: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }, [messages, processor]);
-    if (surfaces.length === 0) {
+    // After the messages: the surfaces exist by then, created synchronously.
+    const publishedRef = useRef({});
+    useEffect(() => {
+        if (!data) {
+            return;
+        }
+        const published = publishedRef.current;
+        for (const [path, value] of Object.entries(data)) {
+            if (Object.is(published[path], value)) {
+                continue;
+            }
+            published[path] = value;
+            for (const surface of processor.model.surfacesMap.values()) {
+                surface.dataModel.set(path, value);
+            }
+        }
+    }, [data, processor]);
+    const notice = validationError || processError;
+    if (surfaces.length === 0 && !notice) {
         return null;
     }
     return (_jsx(A2uiMarkdownProvider, { children: _jsxs(Box, { style: INHERIT_THEME, sx: {
@@ -44,7 +72,7 @@ export function InlineSurface({ messages, onAction, validationError, }) {
                 display: 'flex',
                 flexDirection: 'column',
                 gap: 2,
-            }, children: [validationError ? (_jsx(Box, { role: "alert", sx: {
+            }, children: [notice ? (_jsx(Box, { role: "alert", sx: {
                         px: 3,
                         py: 2,
                         borderRadius: 2,
@@ -53,7 +81,7 @@ export function InlineSurface({ messages, onAction, validationError, }) {
                         borderColor: 'danger.muted',
                         color: 'danger.fg',
                         fontSize: 1,
-                    }, children: validationError })) : null, surfaces.map(surface => (_jsx(Box, { sx: {
+                    }, children: notice })) : null, surfaces.map(surface => (_jsx(Box, { sx: {
                         border: '1px solid',
                         borderColor: 'border.default',
                         borderRadius: 2,

package/lib/loop/plugins/agent-capacity/index.d.ts

@@ -34,6 +34,10 @@ export type AgentCapacityOptions = {
     createPayload?: Record<string, unknown>;
     /** The openers the empty chat offers for this capacity. */
     suggestions?: ChatSuggestionItem[];
+    /** What the agent is told on top of its spec's prompt when the page turns it. */
+    instructions?: string;
+    /** The model it runs on in the page, in place of its spec's. */
+    model?: string;
 };
 export declare function defineAgentCapacityPlugin(options: AgentCapacityOptions): ReactorPlugin<Record<string, never>, unknown, unknown>;
 export default defineAgentCapacityPlugin;

package/lib/loop/plugins/agent-capacity/index.js

@@ -23,7 +23,7 @@
 import { contribution, definePlugin, } from '@datalayer/reactor';
 import { LoopAgentBlueprint, LoopChatSuggestion, } from '../../core';
 export function defineAgentCapacityPlugin(options) {
-    const { key, displayName, description, specId, octicon, emoji, codemode, createPayload, suggestions, } = options;
+    const { key, displayName, description, specId, octicon, emoji, codemode, createPayload, suggestions, instructions, model, } = options;
     return definePlugin({
         name: `@datalayer/loop-plugin-agent-${key}`,
         displayName,
@@ -40,6 +40,8 @@ export function defineAgentCapacityPlugin(options) {
                     enable_codemode: codemode ?? false,
                     ...createPayload,
                 },
+                ...(instructions ? { instructions } : {}),
+                ...(model ? { model } : {}),
             }, { id: key }),
             ...(suggestions && suggestions.length > 0
                 ? [

package/lib/loop/plugins/agents/switchable.d.ts

@@ -105,3 +105,10 @@ export type SwitchableConfig = {
     kernelSource?: ServiceManagerSource;
 };
 export declare function createSwitchableSandboxService({ serverUrl, initialTarget, kernelSource, localAgent, blueprint, }: SwitchableConfig): SwitchableSandboxService;
+/**
+ * Create the agent whose per-agent Jupyter sandbox backs Local, on the
+ * agent-runtimes server at `serverUrl`, unless it is there already — then
+ * only its sandbox is asked for. Exported for a host that addresses the
+ * agent without a workspace: the embed's floating modes (`AppEmbed`).
+ */
+export declare function ensureServerAgent(serverUrl: string, agentId: string | undefined, createPayload: Record<string, unknown>): Promise<void>;