@datalayer/agent-runtimes 1.3.114 → 1.5.0

package/lib/chat/base/ChatBase.js

@@ -19,6 +19,8 @@ import { useContext } from 'react';
 import React, { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
 import { Text, Spinner, IconButton } from '@primer/react';
 import { ReactorLazy } from '@datalayer/reactor/react';
+import { ANSWER_ACTION, emptyUiModel, isFileRef, uploadFile, } from '@datalayer/reactor/ui';
+import { UiSocket } from '@datalayer/reactor/ui/ws';
 import { SkeletonText } from '@primer/react/experimental';
 import { SidebarExpandIcon } from '@primer/octicons-react';
 import { notebookStore, JupyterReactTheme } from '@datalayer/jupyter-react';
@@ -70,10 +72,11 @@ const ephemeralNotebookRefused = lazyViewRefused('notebook');
 import { useNotebookTools } from '../../tools/adapters/agent-runtimes/notebookHooks';
 import { useAgentInspectorTracer } from '../../components/inspector/agentSpans';
 import { chatSpanRecorder, } from '../../components/inspector/chatSpans';
-import { loopMessageChange, speakerOf, withLoopMessage } from './loopMessage';
-import { loopStepOf, withLoopStep } from './loopStep';
-import { applyLoopElement, loopElementChange } from './loopElement';
-import { loopWindowMessage, tellLoopWindow } from './loopWindow';
+import { isStepDisplay, withLoopStep } from './loopStep';
+import { applyLoopElement } from './loopElement';
+import { tellLoopWindow } from './loopWindow';
+import { displayPressOf, placeable, routeUiOp, withPress, withUiOp, } from './uiOps';
+import { namesFiles, withUploadedFiles, } from './uiFiles';
 import { useChatWords } from '../ChatLanguage';
 // Tracks pending prompts already auto-sent for a given conversation scope.
 // This prevents layout-driven unmount/remount cycles from re-sending prompts.
@@ -1196,6 +1199,10 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     const [historyLoaded, setHistoryLoaded] = useState(!historyScopeId);
     const [historyRefreshTick, setHistoryRefreshTick] = useState(0);
     const historyRetryAttemptsRef = useRef(new Map());
+    // The steps of an application's code shown so far, as displays (patched
+    // as they stream), and the elements it showed (REACTOR_UI RU-3).
+    const uiStepsRef = useRef(emptyUiModel());
+    const uiElementsRef = useRef(new Set());
     // Adapter-ready flag — flipped to true once the protocol adapter is initialised
     const [adapterReady, setAdapterReady] = useState(false);
     // Guard so each distinct pending prompt is sent at most once. Stores the
@@ -1578,6 +1585,187 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             threadGivenRef.current?.onStarted?.(id);
         }
     }, []);
+    /*
+     * The conversation's ui channel (REACTOR_UI RU-W): one WebSocket per
+     * conversation, its thread the scope, opened once its session is there
+     * (the first event of its first run, or a thread reopened). What its
+     * messages show, its steps, its elements, its authors and its window
+     * messages arrive here as `reactor.ui` ops; the presses of what they
+     * offered go up it. An op about a message the run stream has not brought
+     * yet — they are two connections — waits for it (`placeable`).
+     */
+    const uiSocketRef = useRef(null);
+    const parkedUiOpsRef = useRef([]);
+    const historyStepsRef = useRef(new Set());
+    const displayItemsRef = useRef([]);
+    const uiSocketUrl = protocol?.uiSocket;
+    const uiSocketTokenRef = useRef(protocol?.authToken);
+    uiSocketTokenRef.current = protocol?.authToken;
+    /*
+     * Its files (REACTOR_UI RU-6): uploaded to its runtime before the run or
+     * the press that names them, the conversation's thread their scope; the
+     * run carries the ref, never the bytes.
+     */
+    const uiFilesUrl = protocol?.uiFiles;
+    const uploadToConversation = useCallback(file => {
+        if (!uiFilesUrl) {
+            return Promise.reject(new Error('This conversation takes no file.'));
+        }
+        return uploadFile(file, {
+            url: uiFilesUrl,
+            scope: threadIdRef.current,
+            token: uiSocketTokenRef.current,
+        });
+    }, [uiFilesUrl]);
+    const applyToMessages = useCallback((op) => {
+        const apply = (items) => {
+            try {
+                return withUiOp(items, op);
+            }
+            catch (error) {
+                console.error('[ChatBase] reactor.ui op not applied:', error);
+                return items;
+            }
+        };
+        setDisplayItems(prev => apply(prev));
+        if (useStoreMode) {
+            const store = useChatStore.getState();
+            store.setMessages(apply(store.messages));
+        }
+    }, [useStoreMode]);
+    const applySocketOp = useCallback((op, history) => {
+        // The past is drawn again, never acted on: a window message is not
+        // raised again, and the steps of turns long over are not drawn again.
+        if (history) {
+            if (op.op === 'window')
+                return;
+            if ((op.op === 'show' || op.op === 'ask') && isStepDisplay(op.body)) {
+                historyStepsRef.current.add(op.body.id);
+                return;
+            }
+            if ((op.op === 'patch' || op.op === 'append') &&
+                historyStepsRef.current.has(op.id)) {
+                return;
+            }
+        }
+        let next;
+        try {
+            next = routeUiOp(op, uiStepsRef.current, uiElementsRef.current);
+        }
+        catch (error) {
+            console.error('[ChatBase] reactor.ui op not applied:', error);
+            return;
+        }
+        uiStepsRef.current = next.steps;
+        const routed = next.routed;
+        if (routed.to === 'window') {
+            // For the page it sits in, outside the conversation (LOOP P-25).
+            tellLoopWindow(routed.data);
+        }
+        else if (routed.to === 'step') {
+            // A step of its code, drawn as it runs (LOOP P-16).
+            const step = routed.step;
+            setDisplayItems(prev => withLoopStep(prev, step));
+        }
+        else if (routed.to === 'element') {
+            // In a side panel or on a page of its own (LOOP P-18).
+            uiElementsRef.current.add(routed.change.id);
+            applyLoopElement(routed.change);
+        }
+        else if (!placeable(displayItemsRef.current, routed.op)) {
+            const under = routed.op.op === 'show' || routed.op.op === 'ask'
+                ? routed.op.body.data?.message_id
+                : undefined;
+            if (history && typeof under === 'string') {
+                // Shown in the past under a message that said nothing: the
+                // thread did not draw it, the chat draws it for what it showed.
+                const placeholder = {
+                    id: under,
+                    role: 'assistant',
+                    content: '',
+                    createdAt: new Date(),
+                };
+                displayItemsRef.current = [...displayItemsRef.current, placeholder];
+                setDisplayItems(prev => prev.some(item => item.id === under)
+                    ? prev
+                    : [...prev, placeholder]);
+                if (useStoreMode)
+                    useChatStore.getState().addMessage(placeholder);
+                applyToMessages(routed.op);
+            }
+            else {
+                parkedUiOpsRef.current.push(routed.op);
+            }
+        }
+        else {
+            applyToMessages(routed.op);
+        }
+    }, [applyToMessages, useStoreMode]);
+    const applySocketOpRef = useRef(applySocketOp);
+    applySocketOpRef.current = applySocketOp;
+    // What waited for its message, applied once the message is here.
+    useEffect(() => {
+        displayItemsRef.current = displayItems;
+        if (parkedUiOpsRef.current.length === 0)
+            return;
+        const parked = parkedUiOpsRef.current.splice(0);
+        let items = displayItems;
+        for (const op of parked) {
+            if (!placeable(items, op)) {
+                parkedUiOpsRef.current.push(op);
+                continue;
+            }
+            try {
+                items = withUiOp(items, op);
+            }
+            catch {
+                // Said by `applyToMessages`, which refuses it the same way.
+            }
+            applyToMessages(op);
+        }
+    }, [displayItems, applyToMessages]);
+    /** The conversation's ui socket, opened for its thread when it is not yet. */
+    const ensureUiSocket = useCallback(() => {
+        if (!uiSocketUrl)
+            return null;
+        const scope = threadIdRef.current;
+        const open = uiSocketRef.current;
+        if (open && open.scope === scope)
+            return open.socket;
+        // Another conversation: what the last one showed goes with it.
+        open?.socket.close();
+        uiStepsRef.current = emptyUiModel();
+        uiElementsRef.current = new Set();
+        parkedUiOpsRef.current = [];
+        historyStepsRef.current = new Set();
+        const socket = new UiSocket({
+            url: uiSocketUrl,
+            scope,
+            token: () => uiSocketTokenRef.current ?? '',
+            onOp: (op, _seq, history) => applySocketOpRef.current(op, history),
+            onStatus: (status, reason) => {
+                if (status === 'refused' || status === 'gone') {
+                    console.error(`[ChatBase] ui socket ${status}: ${reason ?? ''}`);
+                }
+            },
+        });
+        uiSocketRef.current = { socket, scope };
+        socket.connect();
+        return socket;
+    }, [uiSocketUrl]);
+    const ensureUiSocketRef = useRef(ensureUiSocket);
+    ensureUiSocketRef.current = ensureUiSocket;
+    // A thread reopened has its session already: its socket opens now.
+    useEffect(() => {
+        if (thread?.messages.length)
+            ensureUiSocketRef.current();
+        return () => {
+            uiSocketRef.current?.socket.close();
+            uiSocketRef.current = null;
+        };
+        // At mount: the thread it was given.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
     const messagesContainerRef = useRef(null);
     const messagesEndRef = useRef(null);
     const inputRef = useRef(null);
@@ -2378,6 +2566,8 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         adapterRef.current = adapter;
         setAdapterReady(true);
         unsubscribeRef.current = adapter.subscribe((event) => {
+            // The run's session is there once it answers: its ui socket opens.
+            ensureUiSocketRef.current();
             /*
              * Nothing more from a turn the reader has stopped.
              *
@@ -2707,45 +2897,11 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                         }
                     }
                     break;
-                case 'activity': {
-                    // A step of an application's code, drawn as it runs (LOOP P-16).
-                    const step = loopStepOf(event.activity);
-                    if (step) {
-                        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);
-                    if (!change)
-                        break;
-                    setDisplayItems(prev => withLoopMessage(prev, change));
-                    if (useStoreMode) {
-                        if ('removed' in change) {
-                            useChatStore.getState().deleteMessage(change.id);
-                        }
-                        else {
-                            useChatStore.getState().updateMessage(change.id, {
-                                speaker: speakerOf(change.author),
-                            });
-                        }
-                    }
+                case 'activity':
+                    // What the server says besides the conversation's text comes on
+                    // the ui socket (REACTOR_UI RU-W); the run's other activities —
+                    // `loop.session`, `loop.page` — are their readers'.
                     break;
-                }
                 case 'done':
                     /*
                      * What the turn cost, when nobody else is counting.
@@ -2949,6 +3105,38 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             return;
         if (!adapterRef.current && !onSendMessage)
             return;
+        // Its files are uploaded first: the run names their refs (RU-6).
+        if (forwardedPropsGiven && namesFiles(forwardedPropsGiven)) {
+            try {
+                forwardedPropsGiven = await withUploadedFiles(forwardedPropsGiven, uploadToConversation);
+            }
+            catch (failure) {
+                setError(failure instanceof Error ? failure : new Error(String(failure)));
+                return;
+            }
+        }
+        // A press of what a display offered goes up the ui socket, checked
+        // there; the run that answers it names it only (REACTOR_UI RU-W).
+        const pressed = displayPressOf(forwardedPropsGiven);
+        if (pressed && forwardedPropsGiven) {
+            const socket = uiSocketRef.current?.socket;
+            if (!socket) {
+                setError(new Error('This conversation’s ui channel is not open.'));
+                return;
+            }
+            try {
+                const result = await socket.act(pressed);
+                if (!result.ok) {
+                    setError(new Error(result.detail || `The press was refused (${result.status}).`));
+                    return;
+                }
+                forwardedPropsGiven = withPress(forwardedPropsGiven, result.value);
+            }
+            catch (failure) {
+                setError(failure instanceof Error ? failure : new Error(String(failure)));
+                return;
+            }
+        }
         stoppedRef.current = false;
         inspectAnswerRef.current = '';
         recorderRef.current?.recorder.turnStarted(messageContent, selectedModel || undefined);
@@ -3099,6 +3287,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         getEnabledSkillIds,
         noteThreadStarted,
         chatText,
+        uploadToConversation,
     ]);
     // Send pending prompt once history loaded and adapter/handler available
     useEffect(() => {
@@ -3221,6 +3410,38 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         protocol?.authToken,
         protocol?.agentId,
     ]);
+    /*
+     * How a message's display presses what it offered (REACTOR_UI RU-4,
+     * RU-W): with the token of the offer, as the run's press — which
+     * `handleSend` sends up the ui socket before the run, the run naming it
+     * only. An answer is the person's words in the conversation; any other
+     * press, the action's name.
+     */
+    const actOnDisplay = useCallback((display) => async (action) => {
+        const offer = display.actions?.find(one => one.name === action.action);
+        if (!offer) {
+            throw new Error(`“${action.action}” was not offered here.`);
+        }
+        const value = action.payload
+            ?.value;
+        const words = action.action === ANSWER_ACTION
+            ? typeof value === 'string'
+                ? value
+                : isFileRef(value)
+                    ? value.name
+                    : 'Answered.'
+            : action.action;
+        await handleSend(words, {
+            loop: {
+                action: {
+                    name: action.action,
+                    display_id: display.id,
+                    token: offer.token,
+                    payload: action.payload ?? {},
+                },
+            },
+        });
+    }, [handleSend]);
     // ---- handleNewChat ----
     const handleNewChat = useCallback(() => {
         setDisplayItems([]);
@@ -3618,7 +3839,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             rows inside carry their own horizontal padding, which becomes the
             margin once the cap does bind.
           */
-        width: "100%", maxWidth: 920, mx: "auto", bg: "canvas.default", children: [_jsx(ChatMessageList, { displayItems: welcomedItems, isLoading: isLoading, isStreaming: isStreaming, showLoadingIndicator: showLoadingIndicator, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: defaultAvatarConfig, padding: padding, 
+        width: "100%", maxWidth: 920, mx: "auto", bg: "canvas.default", children: [_jsx(ChatMessageList, { displayItems: welcomedItems, actOn: protocol?.uiSocket ? actOnDisplay : undefined, upload: protocol?.uiFiles ? uploadToConversation : undefined, isLoading: isLoading, isStreaming: isStreaming, showLoadingIndicator: showLoadingIndicator, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: defaultAvatarConfig, padding: padding, 
                 // Tool calls are drawn by the page's Reactor plugins; a named
                 // notebook's cell surfaces stand in for the default row of its tools,
                 // so every chat with a headless notebook gets the same transcript.

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

@@ -3,16 +3,14 @@
  * 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 session API shows it as a `reactor.ui` display that says where it
+ * shows in its data (`where: "panel" | "page"`, with its `title`) — an
+ * answer's display (REACTOR_UI RU-2) — and closes it with a `remove` of its
+ * id (RU-3). 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";
+import type { Display } from '@datalayer/reactor/ui';
 /** Where an element opens, besides inline. */
 export type LoopElementWhere = 'panel' | 'page';
 /** An element open in a side panel or on a page. */
@@ -20,19 +18,20 @@ export type LoopElement = {
     id: string;
     where: LoopElementWhere;
     title: string;
-    /** The surface it draws: what `render_a2ui_surface` returns. */
-    shows: unknown;
+    /** The display it draws: what an answer shows (`AnswerShows`). */
+    shows: Display;
 };
-/** What an event says: an element opened or changed, or one closed. */
+/** What changed: 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 element a display is, or `null` for one shown inline, under its
+ * message: a display is an element when it says it shows in a panel or on
+ * a page.
+ */
+export declare function elementOfDisplay(display: Display): LoopElement | 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.

package/lib/chat/base/loopElement.js

@@ -3,36 +3,20 @@
  * 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 element a display is, or `null` for one shown inline, under its
+ * message: a display is an element when it says it shows in a panel or on
+ * a page.
  */
-/** 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')
+export function elementOfDisplay(display) {
+    const where = display.data?.where;
+    if (where !== 'panel' && where !== 'page')
         return null;
+    const title = display.data?.title;
     return {
-        id: data.id,
-        where: data.where,
-        title: typeof data.title === 'string' ? data.title : '',
-        shows: data.shows ?? null,
+        id: display.id,
+        where,
+        title: typeof title === 'string' ? title : '',
+        shows: display,
     };
 }
 /**

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

@@ -3,18 +3,19 @@
  * (LOOP P-16): the chain of thought.
  *
  * AG-UI's `STEP_STARTED` and `STEP_FINISHED` carry a step's name only; the
- * session API says the step whole beside them, with a `CUSTOM` event named
- * `loop.step` — `{id, name, kind, parent_id, input, output, error,
- * started_at, ended_at}` — which the AG-UI adapter hands on as an
- * `activity`. A step is drawn as the chat draws a tool call: one row,
- * collapsed, its input and output inside, running until it ends; a nested
- * step says the step it is in. A step that streams its output (LOOP P-31)
- * is said again as it writes, its output so far, and drawn in place.
+ * session API shows the step whole beside them as a `reactor.ui` display of
+ * type `application/vnd.datalayer.loop.step+json` (REACTOR_UI RU-3) — its
+ * data `{name, kind, parent_id, input, output, error, started_at,
+ * ended_at}`, its id the step's — shown as it starts and again as it ends,
+ * its output patched in as it streams (LOOP P-31). A step is drawn as the
+ * chat draws a tool call: one row, collapsed, its input and output inside,
+ * running until it ends; a nested step says the step it is in.
  */
+import type { Display } from '@datalayer/reactor/ui';
 import type { DisplayItem, ToolCallMessage } from '../../types/chat';
-/** The `CUSTOM` event's name. */
-export declare const LOOP_STEP = "loop.step";
-/** A step, as the event says it. */
+/** The display type of a step. */
+export declare const STEP_DISPLAY_TYPE = "application/vnd.datalayer.loop.step+json";
+/** A step, as its display says it. */
 export type LoopStep = {
     id: string;
     name: string;
@@ -25,11 +26,10 @@ export type LoopStep = {
     error: string;
     ended: boolean;
 };
-/** The step an activity says, or `null` when it says none. */
-export declare function loopStepOf(activity: {
-    type: string;
-    data: unknown;
-} | undefined): LoopStep | null;
+/** Whether a display is a step's. */
+export declare const isStepDisplay: (display: Display) => boolean;
+/** The step a step's display says. Throws for one that is not a step's. */
+export declare function stepOfDisplay(display: Display): LoopStep;
 /** The id of the row a step is drawn as. */
 export declare const stepCallId: (id: string) => string;
 /** A step as the row the chat draws a tool call as. */

package/lib/chat/base/loopStep.js

@@ -2,21 +2,18 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/** The `CUSTOM` event's name. */
-export const LOOP_STEP = 'loop.step';
-/** The step an activity says, or `null` when it says none. */
-export function loopStepOf(activity) {
-    if (!activity || activity.type !== LOOP_STEP)
-        return null;
-    const data = activity.data;
-    if (!data ||
-        typeof data.id !== 'string' ||
-        !data.id ||
-        typeof data.name !== 'string') {
-        return null;
+/** The display type of a step. */
+export const STEP_DISPLAY_TYPE = 'application/vnd.datalayer.loop.step+json';
+/** Whether a display is a step's. */
+export const isStepDisplay = (display) => display.type === STEP_DISPLAY_TYPE;
+/** The step a step's display says. Throws for one that is not a step's. */
+export function stepOfDisplay(display) {
+    const data = display.data ?? {};
+    if (!isStepDisplay(display) || typeof data.name !== 'string') {
+        throw new Error(`Display ${display.id} is not a step`);
     }
     return {
-        id: data.id,
+        id: display.id,
         name: data.name,
         kind: typeof data.kind === 'string' ? data.kind : 'run',
         parentId: typeof data.parent_id === 'string' && data.parent_id

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

@@ -2,30 +2,25 @@
  * 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 session says it with a `reactor.ui` `window` op named `message`, its
+ * `args` `{data}` (REACTOR_UI RU-3), on the conversation's ui socket (RU-W). 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. A window op of another name is
+ * not one this page acts on: refused, it throws.
  */
-/** 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;
+import { type WindowOp } from '@datalayer/reactor/ui';
+/** The name of the window op that hands the page a message. */
+export declare const WINDOW_MESSAGE = "message";
+/** What a window op hands the page. Throws for a window op of another name. */
+export declare function windowMessageOf(op: WindowOp): unknown;
 /** 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.
+ * Why the turn a window message posted by the page ran failed — its
+ * `RUN_ERROR`'s sentence — or `null`. What its code tells the page back comes
+ * on the conversation's ui socket (REACTOR_UI RU-W), never on this stream: a
+ * `reactor.ui` event here is refused.
  */
-export declare function windowTurnOf(stream: string): {
-    said: unknown[];
-    error: string | null;
-};
+export declare function windowTurnErrorOf(stream: string): string | null;