@datalayer/agent-runtimes 1.3.83 → 1.3.85

package/lib/loop/embed/element.js

@@ -36,7 +36,15 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * agent calls as `host_open_ticket`, each as the rule naming it decides; the
  * element raises `message` when the application has answered and `action`
  * when it called a function of the page, beside `decision` and
- * `token-expired`.
+ * `token-expired`. Who its user is, when it matters (LOOP D-21): the page
+ * sets `user-token` (or `element.userToken`) to the token its server signed
+ * naming the user, sent with every run of an application that says
+ * `user: signed`.
+ *
+ * Window messages (LOOP P-25), on the host's own server: the element raises
+ * `window-message` (`detail.data`) when the application's code tells the page
+ * something outside the conversation (`session.send_window_message`), and
+ * `element.postWindowMessage(data)` hands the page's to its `@app.window`.
  *
  * On the host's server (`server`) with the visit's embed token, the
  * session the application opens is kept in the page's `localStorage`, under
@@ -54,7 +62,8 @@ import { coreStore } from '@datalayer/core/lib/state/substates/CoreState';
 import { parseAppspec } from '../apps/appspec';
 import { readAppspecYaml } from '../apps/yaml';
 import { AppEmbed, embedAssistantCharacter } from './AppEmbed';
-import { EMBED_HOST_VARIABLES, EMBED_OBSERVED_ATTRIBUTES, EMBED_TAG, EmbedAttributeError, embedLookOf, inlineHeightOf, resumeOf, } from './embedConfig';
+import { WINDOW_NOT_YET } from './embedSession';
+import { EMBED_HOST_VARIABLES, EMBED_OBSERVED_ATTRIBUTES, EMBED_TAG, EmbedAttributeError, embedLookOf, inlineHeightOf, languageOf, resumeOf, } from './embedConfig';
 import { embedShadowCss } from './embedTheme';
 /** What the framed run page and the element say to each other. */
 export const EMBED_MESSAGES = {
@@ -116,6 +125,18 @@ export function frameSrcOf(origin, app, token = '') {
     // and no access log.
     return `${origin.replace(/\/+$/, '')}/public/apps/${encodeURIComponent(app)}/run?embed=1${token ? `#token=${encodeURIComponent(token)}` : ''}`;
 }
+/**
+ * A framed run page told the visitor's language (P-26): `language=` in its
+ * query, before the fragment that holds the token.
+ */
+export function frameInLanguage(src, language) {
+    if (!language) {
+        return src;
+    }
+    const at = src.indexOf('#');
+    const [page, fragment] = at < 0 ? [src, ''] : [src.slice(0, at), src.slice(at)];
+    return `${page}${page.includes('?') ? '&' : '?'}language=${encodeURIComponent(language)}${fragment}`;
+}
 /**
  * An application on Datalayer, read with its embed token: what the space
  * keeps of it (`model_s`, the stored definition), whose `spec` is the
@@ -193,10 +214,17 @@ export function defineDatalayerAppElement(options = {}) {
         passed = {};
         /** One object, its functions replaced in place: the host below holds it. */
         offered = {};
+        /** How a window message reaches the application's session, once it can (P-25). */
+        windowPort = null;
         /** What the page gives the application, read at each call (D-10). */
         host = {
             context: () => this.passed,
+            // Read as each run is sent (D-21): a renewed one goes with the next.
+            userToken: () => this.getAttribute('user-token') || undefined,
             functions: this.offered,
+            onWindowPort: post => {
+                this.windowPort = post;
+            },
             onEvent: event => this.dispatchEvent(new CustomEvent(event.type, {
                 detail: event.detail,
                 bubbles: true,
@@ -210,6 +238,18 @@ export function defineDatalayerAppElement(options = {}) {
         set context(value) {
             this.passed = { ...(value ?? {}) };
         }
+        /**
+         * Post a window message to the application (LOOP P-25): its code's
+         * `@app.window` reads it, and what it answers is raised as
+         * `window-message` events. Refused, in a sentence, before its
+         * conversation has started or off the host's own server.
+         */
+        postWindowMessage(data) {
+            const post = this.windowPort;
+            return post
+                ? post(data)
+                : Promise.reject(new Error(`datalayer-app: ${WINDOW_NOT_YET}`));
+        }
         /** The page's functions the application may call, by name (D-10). */
         get functions() {
             return this.offered;
@@ -237,6 +277,22 @@ export function defineDatalayerAppElement(options = {}) {
                 this.removeAttribute('token');
             }
         }
+        /**
+         * The token the host's server signed naming its user (LOOP D-21), the
+         * `user-token` attribute's: what an application that says `user: signed`
+         * opens its session with. Set it to hand a new one over.
+         */
+        get userToken() {
+            return this.getAttribute('user-token') ?? '';
+        }
+        set userToken(value) {
+            if (value) {
+                this.setAttribute('user-token', String(value));
+            }
+            else {
+                this.removeAttribute('user-token');
+            }
+        }
         connectedCallback() {
             window.addEventListener('message', this.onMessage);
             void this.load();
@@ -249,6 +305,11 @@ export function defineDatalayerAppElement(options = {}) {
             if (!this.isConnected || before === after) {
                 return;
             }
+            // The user's signed token is read as each run is sent (D-21): nothing
+            // is drawn again for a new one.
+            if (name === 'user-token') {
+                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) {
@@ -256,7 +317,15 @@ export function defineDatalayerAppElement(options = {}) {
                 return;
             }
             // How it looks is drawn again; what it is, read again.
-            if (['mode', 'accent', 'theme', 'font', 'height', 'resume'].includes(name)) {
+            if ([
+                'mode',
+                'accent',
+                'theme',
+                'font',
+                'height',
+                'resume',
+                'language',
+            ].includes(name)) {
                 this.draw();
                 return;
             }
@@ -388,11 +457,19 @@ export function defineDatalayerAppElement(options = {}) {
                 return;
             }
             if (source.kind === 'frame') {
+                let framedLanguage;
+                try {
+                    framedLanguage = languageOf(this.getAttribute('language'));
+                }
+                catch (error) {
+                    this.say(error.message);
+                    return;
+                }
                 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.src = frameInLanguage(source.src, framedLanguage);
                 frame.title = 'Datalayer app';
                 frame.style.height = `${inlineHeightOf(this.getAttribute('height'))}px`;
                 frame.setAttribute('allow', 'clipboard-write');
@@ -402,9 +479,11 @@ export function defineDatalayerAppElement(options = {}) {
             }
             let look;
             let resume;
+            let language;
             try {
                 look = embedLookOf(this.inputs(), source.app);
                 resume = resumeOf(this.getAttribute('resume'));
+                language = languageOf(this.getAttribute('language'));
             }
             catch (error) {
                 this.say(error.message);
@@ -431,7 +510,7 @@ export function defineDatalayerAppElement(options = {}) {
             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, ...(server && this.token ? { embedToken: this.token } : {}), height: inlineHeightOf(this.getAttribute('height')), ownPortal: true, host: this.host, 
                     // The visit's session kept in the page's storage, and picked
                     // up again after a reload, unless the host says not (D-13).
-                    resume: resume }) }));
+                    resume: resume, ...(language ? { language } : {}) }) }));
         }
         onMessage(event) {
             if (!this.frame || event.source !== this.frame.contentWindow) {

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

@@ -34,6 +34,8 @@ export declare const EMBED_ATTRIBUTES: {
     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.";
     readonly resume: "true or false: whether a visit’s conversation is picked up again after the page reloads, kept in the page’s storage; true by default.";
+    readonly language: "The language the visitor reads the application in, as BCP 47 tags it (fr, pt-BR): its translation into it, and the chat’s own words; the visitor’s browser’s by default.";
+    readonly 'user-token': "A token your server signed with the deployment’s secret, naming your user (HS256: sub, name, exp at most an hour away): what an application that says user: signed opens its session with.";
 };
 export type EmbedAttribute = keyof typeof EMBED_ATTRIBUTES;
 /** Every attribute the element watches. */
@@ -103,6 +105,12 @@ export declare function embedLookOf(inputs: EmbedInputs, app?: Pick<AppSpec, 'in
  * refused in a sentence.
  */
 export declare function resumeOf(value: string | null | undefined): boolean;
+/**
+ * The language a host says its visitor reads (LOOP P-26), checked: a BCP 47
+ * tag (`fr`, `pt-BR`), else refused in a sentence. Unsaid, none: the
+ * visitor's browser's.
+ */
+export declare function languageOf(value: string | null | undefined): string | undefined;
 /** 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. */

package/lib/loop/embed/embedConfig.js

@@ -3,6 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { APP_ACCENTS, APP_EMBED_MODES } from '../apps/appspec';
+import { LANGUAGE_TAG } from '../apps/language';
 /** 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. */
@@ -25,6 +26,8 @@ export const EMBED_ATTRIBUTES = {
     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.',
     resume: 'true or false: whether a visit’s conversation is picked up again after the page reloads, kept in the page’s storage; true by default.',
+    language: 'The language the visitor reads the application in, as BCP 47 tags it (fr, pt-BR): its translation into it, and the chat’s own words; the visitor’s browser’s by default.',
+    'user-token': 'A token your server signed with the deployment’s secret, naming your user (HS256: sub, name, exp at most an hour away): what an application that says user: signed opens its session with.',
 };
 /** Every attribute the element watches. */
 export const EMBED_OBSERVED_ATTRIBUTES = Object.keys(EMBED_ATTRIBUTES);
@@ -120,6 +123,21 @@ export function embedLookOf(inputs, app) {
 export function resumeOf(value) {
     return (oneOf(value, ['true', 'false'], 'a value of resume') !== 'false');
 }
+/**
+ * The language a host says its visitor reads (LOOP P-26), checked: a BCP 47
+ * tag (`fr`, `pt-BR`), else refused in a sentence. Unsaid, none: the
+ * visitor's browser's.
+ */
+export function languageOf(value) {
+    const text = value?.trim();
+    if (!text) {
+        return undefined;
+    }
+    if (!LANGUAGE_TAG.test(text)) {
+        throw new EmbedAttributeError(`datalayer-app: "${text}" is not a language as BCP 47 tags it, such as fr or pt-BR.`);
+    }
+    return text;
+}
 /** The height of an inline application, in pixels. */
 export function inlineHeightOf(value) {
     const height = Number.parseInt(value ?? '', 10);

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

@@ -75,5 +75,19 @@ export declare function reattachSession({ serverUrl, uid, token, fetcher, }: {
     token: string;
     fetcher?: typeof fetch;
 }): Promise<Reattached>;
+/** Said when a window message is posted before the conversation has started. */
+export declare const WINDOW_NOT_YET = "The application takes a window message once its conversation has started, on its own server (the \"server\" attribute).";
+/**
+ * Post a window message to a session (LOOP P-25): its code's `@app.window`
+ * runs on it. Returns what the code told the page back; refused — the
+ * runtime's sentence — when the session or its code takes none.
+ */
+export declare function postWindowMessage({ serverUrl, uid, token, data, fetcher, }: {
+    serverUrl: string;
+    uid: string;
+    token?: string;
+    data: unknown;
+    fetcher?: typeof fetch;
+}): Promise<unknown[]>;
 /** What the page says, once, when the conversation it kept is gone. */
 export declare const sessionGoneSentence: (name: string) => string;

package/lib/loop/embed/embedSession.js

@@ -2,6 +2,7 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+import { windowTurnOf } from '../../chat/base/loopWindow';
 /** Where a visit's session is kept in the host's storage: `<prefix>:<app>:<visit>`. */
 export const EMBED_SESSION_KEY_PREFIX = 'datalayer-app:session';
 /**
@@ -132,5 +133,38 @@ export async function reattachSession({ serverUrl, uid, token, fetcher = fetch,
         return { kind: 'gone', uid };
     }
 }
+/** Said when a window message is posted before the conversation has started. */
+export const WINDOW_NOT_YET = 'The application takes a window message once its conversation has started, on its own server (the "server" attribute).';
+/**
+ * Post a window message to a session (LOOP P-25): its code's `@app.window`
+ * runs on it. Returns what the code told the page back; refused — the
+ * runtime's sentence — when the session or its code takes none.
+ */
+export async function postWindowMessage({ serverUrl, uid, token, data, fetcher = fetch, }) {
+    const response = await fetcher(`${serverUrl.replace(/\/+$/, '')}/api/v1/apps/sessions/${encodeURIComponent(uid)}/window`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: JSON.stringify({ data }),
+    });
+    if (!response.ok) {
+        let detail = '';
+        try {
+            const body = (await response.json());
+            detail = typeof body.detail === 'string' ? body.detail : '';
+        }
+        catch {
+            // No sentence: the status says it.
+        }
+        throw new Error(detail || `The window message was refused (${response.status}).`);
+    }
+    const turn = windowTurnOf(await response.text());
+    if (turn.error) {
+        throw new Error(turn.error);
+    }
+    return turn.said;
+}
 /** What the page says, once, when the conversation it kept is gone. */
 export const sessionGoneSentence = (name) => `Your earlier conversation with ${name} has ended, so this is a new one.`;

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

@@ -6,9 +6,26 @@
  * its Appspec names (`deployment.embedded.host.context`).
  *
  * Out: what the application does, as events — `message` when it has said
- * something, `action` when it called a function of the page — beside the
+ * something, `action` when it called a function of the page,
+ * `window-message` when its code told the page something outside the
+ * conversation (LOOP P-25, `session.send_window_message`) — beside the
  * `decision` and `token-expired` the element raises already.
  *
+ * Window messages, in (P-25): the page posts one with
+ * `element.postWindowMessage(data)`; its code's `@app.window` reads it, on
+ * the host's own server (`server`), and what it answers comes back as
+ * `window-message` events.
+ *
+ * Who its user is (LOOP D-21): what the page says as `user` is a claim.
+ * An application whose Appspec says `deployment.embedded.host.user: signed`
+ * takes only a token the host's **server** signed with the deployment's
+ * secret (HS256: `sub`, `name`, `exp` at most an hour away), which the page
+ * hands over as `userToken` (the element's `user-token`). It goes with every
+ * run as `forwardedProps.loop.user_token` (`hostUserRunProps`); the runtime
+ * verifies it where the session opens, refuses the session without it, and
+ * answers `host_context`'s `user` with the user it names. The secret never
+ * reaches the page.
+ *
  * Offered: the functions of the page its Appspec names
  * (`deployment.embedded.host.functions`), each called by its agent as the
  * tool `host_<name>`. Every one of these tools is decided in the page by
@@ -23,8 +40,9 @@
  */
 import type { AppSpec } from '../../types/agentspecs';
 import type { FrontendToolDefinition } from '../../types/tools';
-import { HOST_CONTEXT_TOOL, HOST_NAME, hostTool, hostToolsOf } from '../apps/hostTools';
-export { HOST_CONTEXT_TOOL, HOST_NAME, hostTool, hostToolsOf };
+import type { RunPropsContribution } from '../core';
+import { HOST_CONTEXT_TOOL, HOST_NAME, hostTool, hostToolsOf, signedUser } from '../apps/hostTools';
+export { HOST_CONTEXT_TOOL, HOST_NAME, hostTool, hostToolsOf, signedUser };
 /** What the application tells the page it sits in. */
 export type HostEvent = {
     type: 'message';
@@ -42,13 +60,27 @@ export type HostEvent = {
         result?: unknown;
         error?: string;
     };
+} | {
+    type: 'window-message';
+    /** What its code told the page (LOOP P-25): anything JSON writes. */
+    detail: {
+        data: unknown;
+    };
 };
+/** Posts a window message to the application's session (LOOP P-25). */
+export type WindowPost = (data: unknown) => Promise<void>;
 /** A function of the page, as the page gives it. */
 export type HostFunction = (args: Record<string, unknown>) => unknown | Promise<unknown>;
 /** What the page gives an embedded application (LOOP D-10). */
 export type AppEmbedHost = {
     /** What the page passes now: its visitor (`user`), itself (`page`), values of its own. */
     context?: () => Record<string, unknown>;
+    /**
+     * The token the host's server signed naming its user (LOOP D-21), read as
+     * each run is sent: what an application that says `user: signed` opens its
+     * session with. Never the deployment's secret.
+     */
+    userToken?: () => string | undefined;
     /** The page's functions, by the names the Appspec gives them. */
     functions?: Record<string, HostFunction>;
     /** Told what the application does: `message`, `action`. */
@@ -58,6 +90,12 @@ export type AppEmbedHost = {
      * may be made; the browser's `confirm` when the page gives none.
      */
     ask?: (question: HostQuestion) => boolean | Promise<boolean>;
+    /**
+     * Handed how a window message is posted to the application's session once
+     * the embed can (LOOP P-25) — on the host's own server, its conversation
+     * started — and `null` when it no longer can.
+     */
+    onWindowPort?: (post: WindowPost | null) => void;
 };
 /** What the person is asked before a call of the page is made. */
 export type HostQuestion = {
@@ -77,3 +115,12 @@ export declare const hostNotAllowed: (tool: string) => string;
  * `host` is read at each call, so that what the page passes is the newest.
  */
 export declare function hostFrontendTools(app: Pick<AppSpec, 'connections' | 'rules' | 'deployment'>, host: () => AppEmbedHost): FrontendToolDefinition[];
+/**
+ * What goes with every run for the host's user (LOOP D-21): the token the
+ * host's server signed, as `forwardedProps.loop.user_token`, for an
+ * application that says `user: signed` — read at each run, so that the
+ * newest is sent; nothing when the page gives none, and the runtime refuses
+ * the session in a sentence. `undefined` for an application that takes what
+ * the page says.
+ */
+export declare function hostUserRunProps(app: Pick<AppSpec, 'deployment'>, host: () => AppEmbedHost): RunPropsContribution | undefined;

package/lib/loop/embed/hostBridge.js

@@ -3,8 +3,8 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { behaviourFor } from '../apps/rules';
-import { HOST_CONTEXT_TOOL, HOST_NAME, hostTool, hostToolsOf, } from '../apps/hostTools';
-export { HOST_CONTEXT_TOOL, HOST_NAME, hostTool, hostToolsOf };
+import { HOST_CONTEXT_TOOL, HOST_NAME, hostTool, hostToolsOf, signedUser, } from '../apps/hostTools';
+export { HOST_CONTEXT_TOOL, HOST_NAME, hostTool, hostToolsOf, signedUser };
 /** The sentence a call is refused with when no rule names its tool. */
 export const hostRefused = (tool) => `No rule of this application names ${tool}: it is left to the person, and the page was not called.`;
 /** The sentence a call is refused with when the person did not allow it. */
@@ -102,3 +102,23 @@ export function hostFrontendTools(app, host) {
     }
     return tools;
 }
+/**
+ * What goes with every run for the host's user (LOOP D-21): the token the
+ * host's server signed, as `forwardedProps.loop.user_token`, for an
+ * application that says `user: signed` — read at each run, so that the
+ * newest is sent; nothing when the page gives none, and the runtime refuses
+ * the session in a sentence. `undefined` for an application that takes what
+ * the page says.
+ */
+export function hostUserRunProps(app, host) {
+    if (!signedUser(app.deployment.embedded?.host)) {
+        return undefined;
+    }
+    return {
+        id: 'host-user',
+        props: () => {
+            const token = host().userToken?.()?.trim();
+            return token ? { loop: { user_token: token } } : {};
+        },
+    };
+}

package/lib/loop/index.d.ts

@@ -51,6 +51,7 @@ 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 { appComponentsPluginName, defineAppComponentsPlugin, hasCustomComponents, } from './plugins/app-components';
 export { APP_RULES_PLUGIN_NAME, APP_RULES_WORDS, AppRulesCard, defineAppRulesPlugin, } from './plugins/app-rules';
 export { APP_ACTIVITY_PLUGIN_NAME, APP_ACTIVITY_WORDS, AppActivity, defineAppActivityPlugin, } from './plugins/app-activity';
 export { APP_COMPUTER_PLUGIN_NAME, AppComputer, defineAppComputerPlugin, } from './plugins/app-computer';
@@ -69,10 +70,10 @@ export { PromptPlugin, PROMPT_PLUGIN_NAME } from './plugins/prompt';
 export { LoopEmbed, type LoopEmbedProps } from './embed/LoopEmbed';
 export { AppEmbed, AppFloating, embedAssistantCharacter, type AppEmbedProps, type AppFloatingProps, type EmbedSession, useEmbedSession, useHostBridge, } from './embed/AppEmbed';
 export { EMBED_SESSION_KEY_PREFIX, embedSessionKey, visitOfToken, } from './embed/embedSession';
-export { HOST_CONTEXT_TOOL, hostFrontendTools, hostNotAllowed, hostRefused, hostTool, hostToolsOf, type AppEmbedHost, type HostEvent, type HostFunction, type HostQuestion, } from './embed/hostBridge';
+export { HOST_CONTEXT_TOOL, hostFrontendTools, hostNotAllowed, hostRefused, hostTool, hostToolsOf, hostUserRunProps, signedUser, type AppEmbedHost, type HostEvent, type HostFunction, type HostQuestion, } from './embed/hostBridge';
 export { defineDatalayerAppElement, type DatalayerAppElementOptions, } from './embed/element';
-export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, resumeOf, type EmbedLook, type EmbedSnippetOptions, } from './embed/embedConfig';
+export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, languageOf, resumeOf, 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, isOrganizationFrame, ORGANIZATION_FRAME_PREFIX, type AppCheck, type CheckContext, defineAppPlugin, type AppRendererProps, type AppInstance, appLayoutOptions, 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, isOrganizationFrame, ORGANIZATION_FRAME_PREFIX, type AppCheck, type CheckContext, defineAppPlugin, type AppRendererProps, type AppInstance, appLayoutOptions, readAppspecYaml, writeAppspecYaml, type ParsedAppspec, appComponents, customComponentEntry, customComponentOf, customComponentProblems, customComponentsProblems, pageOutputShows, } from './apps';

package/lib/loop/index.js

@@ -64,6 +64,7 @@ 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 { appComponentsPluginName, defineAppComponentsPlugin, hasCustomComponents, } from './plugins/app-components';
 export { APP_RULES_PLUGIN_NAME, APP_RULES_WORDS, AppRulesCard, defineAppRulesPlugin, } from './plugins/app-rules';
 export { APP_ACTIVITY_PLUGIN_NAME, APP_ACTIVITY_WORDS, AppActivity, defineAppActivityPlugin, } from './plugins/app-activity';
 export { APP_COMPUTER_PLUGIN_NAME, AppComputer, defineAppComputerPlugin, } from './plugins/app-computer';
@@ -90,9 +91,9 @@ export { LoopEmbed } from './embed/LoopEmbed';
 export { AppEmbed, AppFloating, embedAssistantCharacter, useEmbedSession, useHostBridge, } from './embed/AppEmbed';
 export { EMBED_SESSION_KEY_PREFIX, embedSessionKey, visitOfToken, } from './embed/embedSession';
 // The host page and an embedded application, talking (LOOP D-10).
-export { HOST_CONTEXT_TOOL, hostFrontendTools, hostNotAllowed, hostRefused, hostTool, hostToolsOf, } from './embed/hostBridge';
+export { HOST_CONTEXT_TOOL, hostFrontendTools, hostNotAllowed, hostRefused, hostTool, hostToolsOf, hostUserRunProps, signedUser, } from './embed/hostBridge';
 export { defineDatalayerAppElement, } from './embed/element';
-export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, resumeOf, } from './embed/embedConfig';
+export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, languageOf, resumeOf, } 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.
@@ -102,4 +103,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, isOrganizationFrame, ORGANIZATION_FRAME_PREFIX, defineAppPlugin, appLayoutOptions, 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, isOrganizationFrame, ORGANIZATION_FRAME_PREFIX, defineAppPlugin, appLayoutOptions, readAppspecYaml, writeAppspecYaml, appComponents, customComponentEntry, customComponentOf, customComponentProblems, customComponentsProblems, pageOutputShows, } from './apps';

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

@@ -28,7 +28,7 @@ type Surface = InlineSurfaceModel;
 export declare const SURFACE_CATALOG_ID: string;
 /** Values to publish into a surface, by path. */
 export type InlineSurfaceData = Record<string, unknown>;
-export declare function InlineSurface({ messages, onAction, validationError, data, catalog, }: {
+export declare function InlineSurface({ messages, onAction, validationError, data, catalog, onSurface, }: {
     messages: A2uiMessage[];
     /** What it draws with, read once: Datalayer's catalog unless given. */
     catalog?: Catalog<ReactComponentImplementation>;
@@ -41,5 +41,11 @@ export declare function InlineSurface({ messages, onAction, validationError, dat
      * changed is written: what a person typed elsewhere in the model stays.
      */
     data?: InlineSurfaceData;
+    /**
+     * Told of each surface once it is created, for a host that reads what a
+     * person writes as they write it — a widget's page run again as an input
+     * changes (LOOP P-05) — rather than when a button is pressed.
+     */
+    onSurface?: (surface: Surface) => void;
 }): JSX.Element | null;
 export default InlineSurface;

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

@@ -11,7 +11,7 @@ const INHERIT_THEME = {
     ['--a2ui-color-primary']: 'var(--fgColor-accent)',
     ['--a2ui-color-outline']: 'var(--borderColor-default)',
 };
-export function InlineSurface({ messages, onAction, validationError, data, catalog = datalayerCatalog, }) {
+export function InlineSurface({ messages, onAction, validationError, data, catalog = datalayerCatalog, onSurface, }) {
     // 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);
@@ -23,8 +23,13 @@ export function InlineSurface({ messages, onAction, validationError, data, catal
     const processorRef = useRef(undefined);
     processorRef.current = processor;
     const [surfaces, setSurfaces] = useState([]);
+    const onSurfaceRef = useRef(onSurface);
+    onSurfaceRef.current = onSurface;
     useEffect(() => {
-        const created = processor.onSurfaceCreated(surface => setSurfaces(previous => [...previous, surface]));
+        const created = processor.onSurfaceCreated(surface => {
+            setSurfaces(previous => [...previous, surface]);
+            onSurfaceRef.current?.(surface);
+        });
         const deleted = processor.onSurfaceDeleted(id => setSurfaces(previous => previous.filter(surface => surface.id !== id)));
         return () => {
             created.unsubscribe();

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

@@ -4,6 +4,7 @@ import { Spinner, Text } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { encodeFormSubmission } from '../../../chat/messages/formSubmission';
 import { InlineSurface, SURFACE_CATALOG_ID } from './InlineSurface';
+import { useOwnCatalog } from './ownComponents';
 import { answerAction, readA2uiToolResult, validateA2uiSubmission, } from './toolResult';
 export function SurfaceToolResult({ context, send, onRendered, onSubmitted, }) {
     const parsed = useMemo(() => context.status === 'complete'
@@ -11,6 +12,8 @@ export function SurfaceToolResult({ context, send, onRendered, onSubmitted, }) {
         : null, [context.status, context.result]);
     const title = parsed?.title ?? 'the form';
     const [validationError, setValidationError] = useState(null);
+    // With the components the application's developer wrote (LOOP P-17).
+    const catalog = useOwnCatalog();
     // Told once per result, when it is there to be told about.
     useEffect(() => {
         if (parsed?.messages && parsed.messages.length > 0) {
@@ -65,6 +68,6 @@ export function SurfaceToolResult({ context, send, onRendered, onSubmitted, }) {
                 gap: 2,
             }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Rendering A2UI surface..." })] }));
     }
-    return (_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsx(Text, { sx: { fontWeight: 'bold' }, children: title }), _jsx(InlineSurface, { messages: parsed.messages, onAction: handleAction, validationError: validationError })] }));
+    return (_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsx(Text, { sx: { fontWeight: 'bold' }, children: title }), _jsx(InlineSurface, { messages: parsed.messages, onAction: handleAction, validationError: validationError, catalog: catalog })] }));
 }
 export default SurfaceToolResult;

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

@@ -0,0 +1,6 @@
+import type { ReactComponentImplementation } from '@a2ui/react/v0_9';
+import type { Catalog } from '@a2ui/web_core/v0_9';
+/** The renderers the workspace's application contributes, in contribution order. */
+export declare function useOwnComponents(): ReactComponentImplementation[];
+/** Datalayer's catalog with the workspace's application's own components. */
+export declare function useOwnCatalog(): Catalog<ReactComponentImplementation>;

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

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The components the application of this workspace adds to the catalog it
+ * is drawn with (LOOP P-17, `loop.a2ui.component`): what its answers, its
+ * elements and its page draw beside Datalayer's catalog. None outside an
+ * application's workspace, or in one whose developer wrote none.
+ *
+ * @module loop/plugins/a2ui-surface/ownComponents
+ */
+import { useMemo } from 'react';
+import { useOptionalReactorPlatform } from '@datalayer/reactor/react';
+import { catalogWithOwn } from '../../../components/a2ui';
+import { LoopA2uiComponent } from '../../core/a2uiComponents';
+/** The renderers the workspace's application contributes, in contribution order. */
+export function useOwnComponents() {
+    const reactor = useOptionalReactorPlatform();
+    return useMemo(() => reactor
+        ? reactor
+            .getContributions(LoopA2uiComponent)
+            .map(entry => entry.value.implementation)
+        : [], [reactor]);
+}
+/** Datalayer's catalog with the workspace's application's own components. */
+export function useOwnCatalog() {
+    const own = useOwnComponents();
+    return useMemo(() => catalogWithOwn(own), [own]);
+}

package/lib/loop/plugins/app-components/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `app-components` — the components an application's developer wrote (LOOP
+ * P-17), registered as that application's A2UI contributions: each a block
+ * of its Canvas's palette (`loop.canvas.block`, as a UI plugin's components
+ * are) and a renderer of the catalog its page, its elements and its answers
+ * are drawn with (`loop.a2ui.component`). One plugin per application, in its
+ * workspace's preset only: the catalog grows for it, it does not open.
+ *
+ * Its components are reviewed before they get here — `checkAppspec` refuses
+ * an invalid declaration — and drawn in a sandboxed frame of no origin
+ * (`components/a2ui/custom`).
+ *
+ * @module loop/plugins/app-components
+ */
+import { type ReactorPlugin } from '@datalayer/reactor';
+import type { AppSpec } from '../../../types/agentspecs';
+/** The name of the plugin that contributes an application's own components. */
+export declare const appComponentsPluginName: (appId: string) => string;
+/** Whether an application's developer wrote components of its own. */
+export declare const hasCustomComponents: (app: Pick<AppSpec, "interface">) => boolean;
+/**
+ * The plugin contributing the components an application's developer wrote:
+ * a block and a renderer for each. `fetcher` is how their modules are
+ * fetched; the page's `fetch` unless given (tests).
+ */
+export declare function defineAppComponentsPlugin(app: Pick<AppSpec, 'id' | 'name' | 'version' | 'interface'>, fetcher?: typeof fetch): ReactorPlugin<Record<string, never>, unknown, unknown>;