@datalayer/agent-runtimes 1.3.82 → 1.3.84

package/lib/chat/base/ChatBase.js

@@ -62,6 +62,8 @@ import { useAgentInspectorSink } from '../../components/inspector/agentInspector
 import { chatInspectorRecorder, } from '../../components/inspector/chatInspect';
 import { loopMessageChange, speakerOf, withLoopMessage } from './loopMessage';
 import { loopStepOf, withLoopStep } from './loopStep';
+import { applyLoopElement, loopElementChange } from './loopElement';
+import { loopWindowMessage, tellLoopWindow } from './loopWindow';
 // Tracks pending prompts already auto-sent for a given conversation scope.
 // This prevents layout-driven unmount/remount cycles from re-sending prompts.
 const sentPendingPromptKeys = new Set();
@@ -2724,6 +2726,20 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                         setDisplayItems(prev => withLoopStep(prev, step));
                         break;
                     }
+                    // What its code tells the page it sits in, outside the
+                    // conversation (LOOP P-25): handed to whoever listens.
+                    const windowMessage = loopWindowMessage(event.activity);
+                    if (windowMessage) {
+                        tellLoopWindow(windowMessage.data);
+                        break;
+                    }
+                    // An element its code opened in a side panel or on a page of its
+                    // own, changed or closed (LOOP P-18): kept for whoever draws them.
+                    const element = loopElementChange(event.activity);
+                    if (element) {
+                        applyLoopElement(element);
+                        break;
+                    }
                     // An application's code changed a message it sent: its author
                     // said, or the message taken away (LOOP P-15).
                     const change = loopMessageChange(event.activity);

package/lib/chat/base/loopElement.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Where an element of an application's code shows (LOOP P-18): in a side
+ * panel beside the conversation, or on a page of its own over it. Inline,
+ * an element is a message, and the chat draws it as one (P-04).
+ *
+ * The session API says it with a `CUSTOM` event named `loop.element` —
+ * `{id, where, title, shows}`, `shows` the A2UI surface an answer's
+ * components are drawn from, or `{id, closed: true}` — which the AG-UI
+ * adapter hands on as an `activity`. The chat does not draw it: it keeps
+ * what is open here, and whoever draws panels and pages (the `app-elements`
+ * plugin) listens. One store per page, as there is one chat per
+ * application on it.
+ */
+/** The `CUSTOM` event's name. */
+export declare const LOOP_ELEMENT = "loop.element";
+/** Where an element opens, besides inline. */
+export type LoopElementWhere = 'panel' | 'page';
+/** An element open in a side panel or on a page. */
+export type LoopElement = {
+    id: string;
+    where: LoopElementWhere;
+    title: string;
+    /** The surface it draws: what `render_a2ui_surface` returns. */
+    shows: unknown;
+};
+/** What an event says: an element opened or changed, or one closed. */
+export type LoopElementChange = LoopElement | {
+    id: string;
+    closed: true;
+};
+/** The change an activity says, or `null` when it says none. */
+export declare function loopElementChange(activity: {
+    type: string;
+    data: unknown;
+} | undefined): LoopElementChange | null;
+/**
+ * The elements open with a change applied: one opened is added last, one
+ * changed is replaced where it is, one closed is taken away.
+ */
+export declare function withLoopElement(open: readonly LoopElement[], change: LoopElementChange): LoopElement[];
+/** The elements open now, in the order they opened. */
+export declare const openLoopElements: () => LoopElement[];
+/** Apply a change, and tell whoever draws them. */
+export declare function applyLoopElement(change: LoopElementChange): void;
+/**
+ * Close an element on this screen: the person closed it. The code is not
+ * told; it may show it again.
+ */
+export declare const closeLoopElement: (id: string) => void;
+/** Close every element: a new conversation starts with none. */
+export declare function clearLoopElements(): void;
+/** Listen for what is open. Returns the unsubscribe. */
+export declare function onLoopElements(listener: (open: LoopElement[]) => void): () => void;

package/lib/chat/base/loopElement.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Where an element of an application's code shows (LOOP P-18): in a side
+ * panel beside the conversation, or on a page of its own over it. Inline,
+ * an element is a message, and the chat draws it as one (P-04).
+ *
+ * The session API says it with a `CUSTOM` event named `loop.element` —
+ * `{id, where, title, shows}`, `shows` the A2UI surface an answer's
+ * components are drawn from, or `{id, closed: true}` — which the AG-UI
+ * adapter hands on as an `activity`. The chat does not draw it: it keeps
+ * what is open here, and whoever draws panels and pages (the `app-elements`
+ * plugin) listens. One store per page, as there is one chat per
+ * application on it.
+ */
+/** The `CUSTOM` event's name. */
+export const LOOP_ELEMENT = 'loop.element';
+/** The change an activity says, or `null` when it says none. */
+export function loopElementChange(activity) {
+    if (!activity || activity.type !== LOOP_ELEMENT)
+        return null;
+    const data = activity.data;
+    if (!data || typeof data.id !== 'string' || !data.id)
+        return null;
+    if (data.closed === true)
+        return { id: data.id, closed: true };
+    if (data.where !== 'panel' && data.where !== 'page')
+        return null;
+    return {
+        id: data.id,
+        where: data.where,
+        title: typeof data.title === 'string' ? data.title : '',
+        shows: data.shows ?? null,
+    };
+}
+/**
+ * The elements open with a change applied: one opened is added last, one
+ * changed is replaced where it is, one closed is taken away.
+ */
+export function withLoopElement(open, change) {
+    if ('closed' in change) {
+        return open.filter(element => element.id !== change.id);
+    }
+    const at = open.findIndex(element => element.id === change.id);
+    if (at < 0)
+        return [...open, change];
+    return open.map((element, index) => (index === at ? change : element));
+}
+let opened = [];
+const listeners = new Set();
+/** The elements open now, in the order they opened. */
+export const openLoopElements = () => opened;
+/** Apply a change, and tell whoever draws them. */
+export function applyLoopElement(change) {
+    opened = withLoopElement(opened, change);
+    for (const listener of [...listeners])
+        listener(opened);
+}
+/**
+ * Close an element on this screen: the person closed it. The code is not
+ * told; it may show it again.
+ */
+export const closeLoopElement = (id) => applyLoopElement({ id, closed: true });
+/** Close every element: a new conversation starts with none. */
+export function clearLoopElements() {
+    opened = [];
+    for (const listener of [...listeners])
+        listener(opened);
+}
+/** Listen for what is open. Returns the unsubscribe. */
+export function onLoopElements(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}

package/lib/chat/base/loopWindow.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Window messages (LOOP P-25): what an application's code tells the page it
+ * sits in, outside the conversation — ``session.send_window_message(data)``.
+ *
+ * The session API says it with a `CUSTOM` event named `loop.window` —
+ * `{data}` — which the AG-UI adapter hands on as an `activity`. The chat
+ * does not draw it: it hands it to whoever listens here — the embed's host
+ * bridge, which raises it on the element as its `window-message` event.
+ */
+/** The `CUSTOM` event's name. */
+export declare const LOOP_WINDOW = "loop.window";
+/** What an activity says to the page, or `null` when it is not a window message. */
+export declare function loopWindowMessage(activity: {
+    type: string;
+    data: unknown;
+} | undefined): {
+    data: unknown;
+} | null;
+/** Hand a window message to whoever listens. */
+export declare function tellLoopWindow(data: unknown): void;
+/** Listen for window messages. Returns the unsubscribe. */
+export declare function onLoopWindowMessage(listener: (data: unknown) => void): () => void;
+/**
+ * What a turn's stream says to the page — the `loop.window` events of the
+ * turn a window message posted by the page ran — and the sentence its
+ * `RUN_ERROR` said, if it failed.
+ */
+export declare function windowTurnOf(stream: string): {
+    said: unknown[];
+    error: string | null;
+};

package/lib/chat/base/loopWindow.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Window messages (LOOP P-25): what an application's code tells the page it
+ * sits in, outside the conversation — ``session.send_window_message(data)``.
+ *
+ * The session API says it with a `CUSTOM` event named `loop.window` —
+ * `{data}` — which the AG-UI adapter hands on as an `activity`. The chat
+ * does not draw it: it hands it to whoever listens here — the embed's host
+ * bridge, which raises it on the element as its `window-message` event.
+ */
+/** The `CUSTOM` event's name. */
+export const LOOP_WINDOW = 'loop.window';
+/** What an activity says to the page, or `null` when it is not a window message. */
+export function loopWindowMessage(activity) {
+    if (!activity || activity.type !== LOOP_WINDOW)
+        return null;
+    const said = activity.data;
+    if (!said || typeof said !== 'object' || !('data' in said))
+        return null;
+    return { data: said.data };
+}
+const listeners = new Set();
+/** Hand a window message to whoever listens. */
+export function tellLoopWindow(data) {
+    for (const listener of [...listeners])
+        listener(data);
+}
+/** Listen for window messages. Returns the unsubscribe. */
+export function onLoopWindowMessage(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/**
+ * What a turn's stream says to the page — the `loop.window` events of the
+ * turn a window message posted by the page ran — and the sentence its
+ * `RUN_ERROR` said, if it failed.
+ */
+export function windowTurnOf(stream) {
+    const said = [];
+    let error = null;
+    for (const block of stream.split('\n\n')) {
+        const data = block
+            .split('\n')
+            .filter(line => line.startsWith('data:'))
+            .map(line => line.slice('data:'.length).trim())
+            .join('');
+        if (!data)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(data);
+        }
+        catch {
+            continue;
+        }
+        if (event.type === 'RUN_ERROR') {
+            error = String(event.message ?? 'The turn failed.');
+        }
+        else if (event.type === 'CUSTOM') {
+            const message = loopWindowMessage({
+                type: String(event.name),
+                data: event.value,
+            });
+            if (message)
+                said.push(message.data);
+        }
+    }
+    return { said, error };
+}

package/lib/components/a2ui/datalayer/FileUpload.d.ts

@@ -14,8 +14,16 @@ export type GivenFile = {
     size: number;
     data_url: string;
 };
-/** Why a file is refused, or `null` when it is taken. */
-export declare function refusal(file: Pick<File, 'name' | 'size'>, accept: string[] | undefined, maxMb: number): string | null;
+/**
+ * Why a file is refused, or `null` when it is taken: its kinds are
+ * extensions (`.csv`), media types (`application/pdf`) or families
+ * (`image/*`), as the Appspec's uploads say them (LOOP P-21).
+ */
+export declare function refusal(file: Pick<File, 'name' | 'size'> & {
+    type?: string;
+}, accept: string[] | undefined, maxMb: number): string | null;
+/** A file as the application receives it: its content as a data URL. */
+export declare const readFile: (file: File) => Promise<GivenFile>;
 export declare function FileUploadView({ props }: {
     props: FileUploadProps;
 }): import("react").JSX.Element;

package/lib/components/a2ui/datalayer/FileUpload.js

@@ -21,22 +21,25 @@ import { UploadIcon } from '@primer/octicons-react';
 import { Box } from '@datalayer/primer-addons';
 import { BlockFrame, CARD_RADIUS, Problem, Quiet, isRecord } from './parts';
 import { ownImplementation } from './implementation';
+import { acceptsFile } from '../../../loop/apps/uploads';
 /** The default the catalog gives `max_mb`. */
 const MAX_MB = 25;
-/** Why a file is refused, or `null` when it is taken. */
+/**
+ * Why a file is refused, or `null` when it is taken: its kinds are
+ * extensions (`.csv`), media types (`application/pdf`) or families
+ * (`image/*`), as the Appspec's uploads say them (LOOP P-21).
+ */
 export function refusal(file, accept, maxMb) {
-    if (accept?.length) {
-        const lower = file.name.toLowerCase();
-        if (!accept.some(extension => lower.endsWith(extension.toLowerCase()))) {
-            return `${file.name} is not one it takes (${accept.join(', ')}).`;
-        }
+    if (!acceptsFile(accept, { name: file.name, type: file.type ?? '' })) {
+        return `${file.name} is not one it takes (${(accept ?? []).join(', ')}).`;
     }
     if (file.size > maxMb * 1024 * 1024) {
         return `${file.name} is larger than ${maxMb} MB.`;
     }
     return null;
 }
-const readFile = (file) => new Promise((resolve, reject) => {
+/** A file as the application receives it: its content as a data URL. */
+export const readFile = (file) => new Promise((resolve, reject) => {
     const reader = new FileReader();
     reader.onload = () => resolve({
         name: file.name,

package/lib/components/a2ui/datalayer/Form.d.ts

@@ -2,6 +2,8 @@ import { type OwnCommon } from './implementation';
 export type FormProps = OwnCommon & {
     title?: string;
     schema: Record<string, unknown>;
+    /** How its fields are drawn: a uiSchema by field name (P-20). */
+    ui?: Record<string, unknown>;
     submit_label?: string;
     values?: unknown;
     setValues: (values: Record<string, unknown>) => void;

package/lib/components/a2ui/datalayer/Form.js

@@ -12,6 +12,15 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * its action is dispatched, so the action's context reads them. A form the
  * schema refuses says why beside each field and sends nothing.
  *
+ * A form without an action is a set of settings (C-16) — an application's
+ * `interface.settings` drawn beside its conversation: no button, its values
+ * written where `values` points as they are filled, for the next run to take;
+ * the runtime checks them against the same schema.
+ *
+ * Its `ui` says how its fields are drawn (LOOP P-20): a uiSchema by field
+ * name, `ui:widget` one of primer-rjsf's widgets or of `switch` and `tags`
+ * (`formWidgets`) — the nine inputs a setting is drawn with.
+ *
  * @module components/a2ui/datalayer/Form
  */
 import { useEffect, useMemo, useState } from 'react';
@@ -19,6 +28,7 @@ import { Form as SchemaForm } from '@datalayer/primer-rjsf';
 import validator from '@rjsf/validator-ajv8';
 import { BlockFrame, Problem, isRecord } from './parts';
 import { ownImplementation } from './implementation';
+import { FORM_WIDGETS } from './formWidgets';
 /** The default the catalog gives `submit_label`. */
 const SUBMIT_LABEL = 'Send';
 export function FormView({ props }) {
@@ -34,11 +44,25 @@ export function FormView({ props }) {
     useEffect(() => {
         setLocal(JSON.parse(shownKey));
     }, [shownKey]);
-    const uiSchema = useMemo(() => ({ 'ui:submitButtonOptions': { submitText: submitLabel } }), [submitLabel]);
+    // Without an action, nothing is sent: no button, the values written as filled.
+    const live = action === undefined;
+    const drawn = JSON.stringify(props.ui ?? {});
+    const uiSchema = useMemo(() => ({
+        ...JSON.parse(drawn),
+        'ui:submitButtonOptions': live
+            ? { norender: true }
+            : { submitText: submitLabel },
+    }), [drawn, live, submitLabel]);
     const problem = schema.type !== undefined && schema.type !== 'object'
         ? 'Its fields are not an object schema: a form asks for several named values.'
         : null;
-    return (_jsx(BlockFrame, { title: title, label: "Form", weight: props.weight, testId: "a2ui-form", children: problem ? (_jsx(Problem, { children: problem })) : (_jsx(SchemaForm, { schema: schema, uiSchema: uiSchema, formData: values, validator: validator, liveValidate: touched, onBlur: () => setTouched(true), onError: () => setTouched(true), showErrorList: false, onChange: event => setLocal((event.formData ?? {})), onSubmit: event => {
+    return (_jsx(BlockFrame, { title: title, label: "Form", weight: props.weight, testId: "a2ui-form", children: problem ? (_jsx(Problem, { children: problem })) : (_jsx(SchemaForm, { schema: schema, uiSchema: uiSchema, widgets: FORM_WIDGETS, formData: values, validator: validator, liveValidate: touched, onBlur: () => setTouched(true), onError: () => setTouched(true), showErrorList: false, onChange: event => {
+                const filled = (event.formData ?? {});
+                setLocal(filled);
+                if (live) {
+                    setValues(filled);
+                }
+            }, onSubmit: event => {
                 setValues((event.formData ?? {}));
                 action?.();
             } })) }));

package/lib/components/a2ui/datalayer/formWidgets.d.ts

@@ -0,0 +1,19 @@
+/** What rjsf gives a widget, of what these two read. */
+export type WidgetProps = {
+    id: string;
+    value: unknown;
+    label: string;
+    disabled?: boolean;
+    readonly?: boolean;
+    placeholder?: string;
+    onChange: (value: unknown) => void;
+};
+/** A `boolean` as a toggle switch. */
+export declare function SwitchWidget({ id, value, label, disabled, readonly, onChange, }: WidgetProps): import("react").JSX.Element;
+/** An `array` of `string` items as tokens: typed, then Enter or a comma. */
+export declare function TagsWidget({ id, value, label, disabled, readonly, placeholder, onChange, }: WidgetProps): import("react").JSX.Element;
+/** What a form's uiSchema may name besides primer-rjsf's own widgets. */
+export declare const FORM_WIDGETS: {
+    switch: typeof SwitchWidget;
+    tags: typeof TagsWidget;
+};

package/lib/components/a2ui/datalayer/formWidgets.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The two inputs of the nine (LOOP P-20) that `@datalayer/primer-rjsf` does
+ * not draw itself, as rjsf widgets a form's uiSchema names (`ui:widget`):
+ *
+ * - `switch` — a `boolean` as Primer's toggle switch;
+ * - `tags` — an `array` of `string` items as words in a field, each a token:
+ *   Enter or a comma adds what is typed, a token's cross takes it away.
+ *
+ * The seven others are primer-rjsf's: Select (an `enum`), Slider (`range`),
+ * TextInput (a `string`, or `textarea`), Checkbox (a `boolean`), DatePicker
+ * (`format: date`), MultiSelect (an `array` of `enum` items, or
+ * `checkboxes`) and RadioGroup (`radio`).
+ *
+ * @module components/a2ui/datalayer/formWidgets
+ */
+import { useState } from 'react';
+import { Box, FormControl, Text, TextInputWithTokens, ToggleSwitch, } from '@primer/react';
+/** A `boolean` as a toggle switch. */
+export function SwitchWidget({ id, value, label, disabled, readonly, onChange, }) {
+    return (_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 1 }, children: [_jsx(Text, { as: "span", id: `${id}-label`, sx: { fontWeight: 'semibold' }, children: label }), _jsx(ToggleSwitch, { size: "small", "aria-labelledby": `${id}-label`, checked: Boolean(value), disabled: disabled || readonly, onClick: () => onChange(!value) })] }));
+}
+/** An `array` of `string` items as tokens: typed, then Enter or a comma. */
+export function TagsWidget({ id, value, label, disabled, readonly, placeholder, onChange, }) {
+    const tags = Array.isArray(value) ? value.map(String) : [];
+    const [typed, setTyped] = useState('');
+    const add = () => {
+        const word = typed.trim();
+        if (word && !tags.includes(word)) {
+            onChange([...tags, word]);
+        }
+        setTyped('');
+    };
+    return (_jsxs(FormControl, { id: id, disabled: disabled || readonly, children: [_jsx(FormControl.Label, { children: label }), _jsx(TextInputWithTokens, { block: true, placeholder: placeholder, tokens: tags.map((text, index) => ({ id: index, text })), value: typed, onChange: event => setTyped(event.target.value.replace(',', '')), onKeyDown: event => {
+                    if (event.key === 'Enter' || event.key === ',') {
+                        event.preventDefault();
+                        add();
+                    }
+                }, onBlur: add, onTokenRemove: index => {
+                    onChange(tags.filter((_, at) => at !== index));
+                } })] }));
+}
+/** What a form's uiSchema may name besides primer-rjsf's own widgets. */
+export const FORM_WIDGETS = {
+    switch: SwitchWidget,
+    tags: TagsWidget,
+};

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

@@ -9,17 +9,52 @@
  *   one menu each; the option picked goes with every run as
  *   `forwardedProps.loop.modes` (`LoopRunProps`), and the runtime tells the
  *   agent its instructions, on the model it names, for that run.
+ * - What a person may **send** without being asked (LOOP P-21,
+ *   `interface.uploads`): a paper clip beside the composer takes images,
+ *   files and recordings of the kinds and sizes the Appspec says — one it
+ *   does not take is refused in a sentence and never read — and the files
+ *   held go with the next message as `forwardedProps.loop.files`, then are
+ *   let go. The runtime refuses again what was sent all the same.
+ * - Its **profiles** (LOOP P-20, `interface.profiles`): a picker beside the
+ *   composer, on the first unless another is picked. The profile picked goes
+ *   with every run as `forwardedProps.loop.profile`, and its starters (else
+ *   the application's) are what the empty chat offers, by category
+ *   (`LoopChatExtras.openers`). Once the first message is sent, the
+ *   conversation keeps its profile: the picker says so and picks no other.
+ *
+ * Given the application as the person reads it (`translatedAppspec`, LOOP
+ * P-26), its words are theirs; the composer's own, `language`'s.
  *
  * @module loop/apps/AppComposer
  */
-import type { JSX } from 'react';
-import type { AppSpec } from '../../types/agentspecs';
+import { type JSX } from 'react';
+import type { AppSpec, AppStarterSpec } from '../../types/agentspecs';
+import { type GivenFile } from '../../components/a2ui/datalayer/FileUpload';
+import { type ChatSuggestionItem } from '../core';
+/** What the composer holds to send: the files, and why the last were refused. */
+export type HeldUploads = {
+    files: GivenFile[];
+    refused: string | null;
+};
+/**
+ * Files chosen in the composer, held for the next message: the refusal the
+ * runtime would say for what the application does not take, else the files
+ * read. Nothing is read when one is refused.
+ */
+export declare function holdUploads(app: Pick<AppSpec, 'name' | 'interface'>, held: readonly GivenFile[], chosen: readonly File[], read?: (file: File) => Promise<GivenFile>): Promise<HeldUploads>;
 /** The plugin's name, before the application's id. */
 export declare const APP_COMPOSER_PLUGIN_NAME = "@datalayer/loop-plugin-app-composer";
+/** Starters as the empty chat offers them: each under its category (P-20). */
+export declare function startersAsOpeners(starters: readonly AppStarterSpec[]): ChatSuggestionItem[];
+/**
+ * Whether an application needs its composer plugin: commands, modes,
+ * uploads or profiles to offer there.
+ */
+export declare const needsAppComposer: (app: AppSpec) => boolean;
 /**
  * The plugin that puts an application's commands in the composer's `/` menu
- * and its modes beside the composer. Nothing for an application with
- * neither: its plugin contributes nothing.
+ * and its modes, its profiles and its paper clip beside the composer.
+ * Nothing for an application with none: its plugin contributes nothing.
  */
 export declare function defineAppComposerPlugin(app: AppSpec): import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, {
     components: {