@datalayer/agent-runtimes 1.3.84 → 1.3.86

package/lib/loop/embed/element.js

@@ -36,7 +36,10 @@ 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
@@ -60,7 +63,7 @@ import { parseAppspec } from '../apps/appspec';
 import { readAppspecYaml } from '../apps/yaml';
 import { AppEmbed, embedAssistantCharacter } from './AppEmbed';
 import { WINDOW_NOT_YET } from './embedSession';
-import { EMBED_HOST_VARIABLES, EMBED_OBSERVED_ATTRIBUTES, EMBED_TAG, EmbedAttributeError, embedLookOf, inlineHeightOf, resumeOf, } from './embedConfig';
+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 = {
@@ -122,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
@@ -204,6 +219,8 @@ export function defineDatalayerAppElement(options = {}) {
         /** 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;
@@ -260,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();
@@ -272,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) {
@@ -279,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;
             }
@@ -411,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');
@@ -425,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);
@@ -454,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/hostBridge.d.ts

@@ -16,6 +16,16 @@
  * 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
@@ -30,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';
@@ -64,6 +75,12 @@ export type HostFunction = (args: Record<string, unknown>) => unknown | Promise<
 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`. */
@@ -98,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>;

package/lib/loop/plugins/app-components/index.js

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * `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 { contribution, definePlugin, } from '@datalayer/reactor';
+import { customImplementation } from '../../../components/a2ui/custom';
+import { customComponentEntry } from '../../apps/customComponents';
+import { LoopA2uiComponent } from '../../core/a2uiComponents';
+import { LoopCanvasBlock } from '../../core/canvasBlocks';
+/** The name of the plugin that contributes an application's own components. */
+export const appComponentsPluginName = (appId) => `@datalayer/loop-plugin-app-components-${appId}`;
+/** Whether an application's developer wrote components of its own. */
+export const hasCustomComponents = (app) => (app.interface.customComponents ?? []).length > 0;
+/**
+ * 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 function defineAppComponentsPlugin(app, fetcher) {
+    const own = app.interface.customComponents ?? [];
+    if (own.length === 0) {
+        throw new Error(`“${app.name}” has no component of its own to contribute.`);
+    }
+    return definePlugin({
+        name: appComponentsPluginName(app.id),
+        displayName: `${app.name}'s components`,
+        description: `The components ${app.name}'s developer wrote: ${own.map(component => component.name).join(', ')}.`,
+        octicon: 'apps',
+        contributes: own.flatMap(component => [
+            contribution(LoopCanvasBlock, {
+                id: component.name,
+                uiPlugin: `app:${app.id}`,
+                component: customComponentEntry(component, app.version),
+            }, { id: component.name }),
+            contribution(LoopA2uiComponent, {
+                id: component.name,
+                app: app.id,
+                implementation: customImplementation(component, app.version, fetcher),
+            }, { id: component.name }),
+        ]),
+    });
+}

package/lib/loop/plugins/app-elements/AppElements.js

@@ -6,6 +6,7 @@ import { Box } from '@datalayer/primer-addons';
 import { closeLoopElement, onLoopElements, openLoopElements, } from '../../../chat/base/loopElement';
 import { InlineSurface, SURFACE_CATALOG_ID, } from '../a2ui-surface/InlineSurface';
 import { answerAction, readA2uiToolResult } from '../a2ui-surface/toolResult';
+import { useOwnCatalog } from '../a2ui-surface/ownComponents';
 /** How wide the side panel is, at most. */
 export const APP_PANEL_WIDTH = 380;
 /** What is open now: the panels in the order they opened, and the last page. */
@@ -18,6 +19,8 @@ export function elementsByPlace(open) {
 }
 function ElementBody({ element, send, }) {
     const parsed = useMemo(() => readA2uiToolResult(element.shows, SURFACE_CATALOG_ID), [element.shows]);
+    // With the components its developer wrote (P-17).
+    const catalog = useOwnCatalog();
     const onAction = (action) => {
         // A button of what its code shows: its action goes to the application,
         // as a button of an answer does (LOOP P-04).
@@ -30,7 +33,7 @@ function ElementBody({ element, send, }) {
     }
     return (_jsx(InlineSurface
     // Drawn again whole when the code changes it.
-    , { messages: parsed.messages, onAction: onAction }, JSON.stringify(element.shows)));
+    , { messages: parsed.messages, onAction: onAction, catalog: catalog }, JSON.stringify(element.shows)));
 }
 function ElementHeader({ element }) {
     return (_jsxs(Box, { sx: {

package/lib/loop/plugins/app-page/AppPage.d.ts

@@ -9,12 +9,21 @@
  * palette (`loop.canvas.block`, R-01b) and nothing else, so that what the
  * Canvas can place and what the page can draw are one list: a page that
  * uses a block no enabled plugin contributes says so, in place of the page.
+ * The components its developer wrote (LOOP P-17) are among them, contributed
+ * by its own plugin (`app-components`) with their renderers.
+ *
+ * A widget's page written in its code (LOOP P-05) runs in a session of its
+ * own, beside the conversation: as an input changes, the page sends them all
+ * to the session's `page` action and shows what its code answered at
+ * `/outputs/<name>`, in place — no message is sent (`./pageRun`).
  *
  * @module loop/plugins/app-page/AppPage
  */
 import type { JSX } from 'react';
 import type { AppSpec } from '../../../types/agentspecs';
 import { type LoopWorkspaceContext } from '../../core';
+/** How long the page waits after an input changed before it runs (P-05). */
+export declare const PAGE_RUN_DELAY_MS = 300;
 /** The components a page's messages place, each once. */
 export declare function componentsOnPage(messages: readonly unknown[]): string[];
 /**