@datalayer/agent-runtimes 1.3.10 → 1.3.13

package/lib/loop/core/index.d.ts

@@ -183,12 +183,25 @@ export type LoopWorkspaceContext = {
  * publishes, a mounted view subscribes, and neither imports the other.
  */
 export type PromptChannel = {
-    /** Publish a prompt. Returns whether anything was listening. */
+    /**
+     * Publish a prompt. Returns whether it will be answered: `false` only when
+     * nothing is listening and nothing is coming — a view that has not mounted
+     * yet holds the message instead (see {@link createPromptChannel}).
+     */
     submit: (message: string) => boolean;
     /** Listen for prompts. Returns an unsubscribe. */
     subscribe: (listener: (message: string) => void) => () => void;
 };
-/** Create a prompt channel. The shell owns one per workspace. */
+/**
+ * Create a prompt channel. The shell owns one per workspace.
+ *
+ * The shell's composer is on screen before the view that answers it: the
+ * editor and its sandbox are megabytes and take a moment, and the prompt is
+ * ready to type into immediately. A message sent in that moment used to be
+ * dropped — it appeared in the conversation and was never answered, and the
+ * only way to find out was to send it again — so an unheard message is held
+ * and handed to the first view that subscribes, in the order it was sent.
+ */
 export declare function createPromptChannel(): PromptChannel;
 /**
  * What the active view tells the shell about itself.
@@ -205,6 +218,15 @@ export type ViewControls = {
     stop?: () => void;
     /** Start the view's work over — the chat resets its conversation. */
     newChat?: () => void;
+    /**
+     * Say something as the reader: the chat sends it as the next turn.
+     *
+     * For whatever speaks on the reader's behalf — a form pressed on a
+     * rendered surface, whose values the agent should answer. The chat had
+     * this control from the start and kept it to itself; a host with a
+     * message had no way in.
+     */
+    send?: (message: string) => void;
 };
 /** Props every view receives. */
 export type LoopViewProps = {
@@ -548,6 +570,15 @@ export type LoopChatExtrasValue = {
      * on the chip's text, which is how the chat tells openers apart already.
      */
     hiddenOpeners?: string[];
+    /**
+     * Every opener off, however many there are.
+     *
+     * `hiddenOpeners` takes a page's exceptions by name; this is the page that
+     * wants none of them — a landing page whose composer has moved under a
+     * conversation that has started, where a row of openers over it would be
+     * offering a first question to somebody who has already asked one.
+     */
+    hideOpeners?: boolean;
     /**
      * Told what the agent has used, each time the chat learns it.
      *
@@ -824,14 +855,23 @@ export type ChatLayoutContribution = {
     /**
      * How this layout wants the composer built.
      *
-     * `floating-top` is a floating card anchored to the top edge rather than
+     * `floating-top` and `floating-bottom` are a floating card anchored to
+     * that edge of the layout rather than
      * the bottom — a command line over the document, sized by the card.
      * `docked-top` is that same command line standing in the flow instead: the
      * layout gives it a mount point and the composer fills it, so its width is
      * the layout's to decide and the page below starts under it rather than
      * behind it.
      */
-    prompt?: 'docked' | 'floating' | 'floating-top' | 'docked-top';
+    prompt?: 'docked' | 'floating' | 'floating-top' | 'floating-bottom' | 'docked-top';
+    /**
+     * The same, live, for a layout whose stance changes while it is on
+     * screen — the page layout moves the composer between a floating card
+     * and its side panel as the person picks a display mode. Read over
+     * `prompt` by the chat view whenever it is given; `prompt` is then only
+     * the stance the layout starts in.
+     */
+    promptStance?: ReadonlySignal<'docked' | 'floating' | 'floating-top' | 'floating-bottom' | 'docked-top'>;
 };
 export declare const LoopChatLayout: import("@datalayer/reactor").ContributionPoint<ChatLayoutContribution>;
 /**

package/lib/loop/core/index.js

@@ -71,13 +71,27 @@ export const IDLE_SANDBOX_TARGET_SIGNAL = {
 export function loopSurfaceId(sessionId) {
     return `loop-${sessionId || 'default'}`;
 }
-/** Create a prompt channel. The shell owns one per workspace. */
+/**
+ * Create a prompt channel. The shell owns one per workspace.
+ *
+ * The shell's composer is on screen before the view that answers it: the
+ * editor and its sandbox are megabytes and take a moment, and the prompt is
+ * ready to type into immediately. A message sent in that moment used to be
+ * dropped — it appeared in the conversation and was never answered, and the
+ * only way to find out was to send it again — so an unheard message is held
+ * and handed to the first view that subscribes, in the order it was sent.
+ */
 export function createPromptChannel() {
     const listeners = new Set();
+    /** Said before anything was listening, waiting for the first view. */
+    const waiting = [];
     return {
         submit(message) {
             if (listeners.size === 0) {
-                return false;
+                waiting.push(message);
+                // Heard, as far as the sender is concerned: it is going to be
+                // answered, so the composer clears and no failure is reported.
+                return true;
             }
             for (const listener of [...listeners]) {
                 listener(message);
@@ -86,6 +100,19 @@ export function createPromptChannel() {
         },
         subscribe(listener) {
             listeners.add(listener);
+            if (waiting.length > 0) {
+                const held = waiting.splice(0, waiting.length);
+                /*
+                 * Next tick, not now: `subscribe` is called from an effect as the
+                 * view mounts, and a listener that started answering inside it would
+                 * be setting state on a component in the middle of mounting.
+                 */
+                queueMicrotask(() => {
+                    for (const message of held) {
+                        listener(message);
+                    }
+                });
+            }
             return () => {
                 listeners.delete(listener);
             };

package/lib/loop/embed/LoopEmbed.js

@@ -66,6 +66,7 @@ export function LoopEmbed({ agentId = '', showHeader = false, chatHeaderActions,
         preset.defaultEditor,
         preset.showViewSelector,
         preset.hideChatHeader,
+        preset.chatHeaderButtons,
         preset.promptPlacement,
         preset.autoFocusPrompt,
         preset.fullScreenTopOffset,
@@ -77,6 +78,12 @@ export function LoopEmbed({ agentId = '', showHeader = false, chatHeaderActions,
         preset.pageLayoutTurnPanel,
         preset.pageLayoutTurnPanelFooter,
         preset.pageLayoutPrompt,
+        preset.pageLayoutPromptAnchor,
+        // By its fields: a host that writes the size inline hands over a new
+        // object every render, and the reactor must not be rebuilt for that.
+        preset.pageLayoutSize?.format,
+        preset.pageLayoutSize?.width,
+        preset.pageLayoutSize?.height,
         preset.localAgentSpec,
         preset.floatingPrompt,
         preset.editorSelector,

package/lib/loop/index.d.ts

@@ -16,7 +16,7 @@ export { ChatHeaderPlugin, CHAT_HEADER_PLUGIN_NAME, } from './plugins/chat-heade
 export { InputPromptPlugin, INPUT_PROMPT_PLUGIN_NAME, type InputPromptPluginConfig, } from './plugins/input-prompt';
 export { createChatExtrasPlugin, CHAT_EXTRAS_PLUGIN_NAME, type ChatExtrasHandle, } from './plugins/chat-extras';
 export { LoopChatExtras, LoopChatLayout, LoopChatTurn, LoopOpeningDocument, LoopOpeningNotebook, LoopPromptPanel, type ChatLayoutContribution, type ChatLayoutParts, type ChatTurnContribution, type ChatTurnSnapshot, type ChatTurnStatus, type LoopChatExtrasValue, type OpeningDocumentContribution, type OpeningNotebookContribution, type PromptPanelContribution, } from './core';
-export { LoopPageLayoutPlugin, LOOP_PAGE_LAYOUT_PLUGIN_NAME, openConversationPanel, pageLayoutSheet, pageLayoutPanelOpen, type LoopPageLayoutConfig, } from './plugins/page-layout';
+export { LoopPageLayoutPlugin, LOOP_PAGE_LAYOUT_PLUGIN_NAME, openConversationPanel, pageLayoutSheet, pageLayoutPanelOpen, setPageLayoutChatMode, type LoopPageLayoutConfig, } from './plugins/page-layout';
 export { useOptionalTeamSelection } from './plugins/agents/useTeamSelection';
 export type { TeamMember, TeamSelection } from './plugins/agents/team';
 export { ChatViewPlugin, CHAT_VIEW_PLUGIN_NAME } from './plugins/chat-view';

package/lib/loop/index.js

@@ -26,7 +26,10 @@ export { createChatExtrasPlugin, CHAT_EXTRAS_PLUGIN_NAME, } from './plugins/chat
 // read back: the chat extras, the opening notebook, and who the team is
 // talking to. A page composing panels around a `LoopEmbed` needs all three.
 export { LoopChatExtras, LoopChatLayout, LoopChatTurn, LoopOpeningDocument, LoopOpeningNotebook, LoopPromptPanel, } from './core';
-export { LoopPageLayoutPlugin, LOOP_PAGE_LAYOUT_PLUGIN_NAME, openConversationPanel, pageLayoutSheet, pageLayoutPanelOpen, } from './plugins/page-layout';
+export { LoopPageLayoutPlugin, LOOP_PAGE_LAYOUT_PLUGIN_NAME, openConversationPanel, pageLayoutSheet, pageLayoutPanelOpen, 
+// How a host moves the composer: `sidebar` stands it in the conversation
+// panel, under what was said, and opens the panel to show it.
+setPageLayoutChatMode, } from './plugins/page-layout';
 export { useOptionalTeamSelection } from './plugins/agents/useTeamSelection';
 export { ChatViewPlugin, CHAT_VIEW_PLUGIN_NAME } from './plugins/chat-view';
 export { NotebookViewPlugin, NOTEBOOK_VIEW_PLUGIN_NAME, } from './plugins/notebook-view';

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

@@ -0,0 +1,22 @@
+/**
+ * A generated A2UI surface, drawn inline where the agent's answer lands.
+ *
+ * Its own processor, so the surface can be filled in and submitted here
+ * whatever else is showing it. The basic catalogue draws from inherited
+ * `--a2ui-*` custom properties, so the surface follows the workspace's theme
+ * by inheriting rather than by being told — the same rule the Surface view
+ * follows, and what keeps a generated form from being the one light card in
+ * a dark workspace.
+ *
+ * @module loop/plugins/a2ui-surface/InlineSurface
+ */
+import type { JSX } from 'react';
+import { type A2uiClientAction, type A2uiMessage } from '@a2ui/web_core/v0_9';
+/** The catalogue a surface is rewritten to before it is drawn. */
+export declare const SURFACE_CATALOG_ID: string;
+export declare function InlineSurface({ messages, onAction, validationError, }: {
+    messages: A2uiMessage[];
+    onAction: (action: A2uiClientAction) => void;
+    validationError?: string | null;
+}): JSX.Element | null;
+export default InlineSurface;

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

@@ -0,0 +1,64 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Box } from '@datalayer/primer-addons';
+import { basicCatalog, } from '@a2ui/react/v0_9';
+import { MessageProcessor, } from '@a2ui/web_core/v0_9';
+import { A2UI_RENDER_SCOPE_SX, A2uiMarkdownProvider, A2uiSurfaceComposed, } from '../../../components/a2ui';
+/** The catalogue a surface is rewritten to before it is drawn. */
+export const SURFACE_CATALOG_ID = basicCatalog.id;
+const INHERIT_THEME = {
+    ['--a2ui-color-surface']: 'var(--bgColor-muted)',
+    ['--a2ui-color-on-surface']: 'var(--fgColor-default)',
+    ['--a2ui-color-primary']: 'var(--fgColor-accent)',
+    ['--a2ui-color-outline']: 'var(--borderColor-default)',
+};
+export function InlineSurface({ messages, onAction, validationError, }) {
+    // Reached through a ref: the processor is built once, and the handler it
+    // was built with must not go stale when the host's does not.
+    const onActionRef = useRef(onAction);
+    onActionRef.current = onAction;
+    const processor = useMemo(() => new MessageProcessor([basicCatalog], action => onActionRef.current(action)), []);
+    const [surfaces, setSurfaces] = useState([]);
+    useEffect(() => {
+        const created = processor.onSurfaceCreated(surface => setSurfaces(previous => [...previous, surface]));
+        const deleted = processor.onSurfaceDeleted(id => setSurfaces(previous => previous.filter(surface => surface.id !== id)));
+        return () => {
+            created.unsubscribe();
+            deleted.unsubscribe();
+        };
+    }, [processor]);
+    // Once: the messages are one tool result, processed when it arrives.
+    const processedRef = useRef(false);
+    useEffect(() => {
+        if (processedRef.current) {
+            return;
+        }
+        processedRef.current = true;
+        processor.processMessages(messages);
+    }, [messages, processor]);
+    if (surfaces.length === 0) {
+        return null;
+    }
+    return (_jsx(A2uiMarkdownProvider, { children: _jsxs(Box, { style: INHERIT_THEME, sx: {
+                ...A2UI_RENDER_SCOPE_SX,
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 2,
+            }, children: [validationError ? (_jsx(Box, { role: "alert", sx: {
+                        px: 3,
+                        py: 2,
+                        borderRadius: 2,
+                        bg: 'danger.subtle',
+                        border: '1px solid',
+                        borderColor: 'danger.muted',
+                        color: 'danger.fg',
+                        fontSize: 1,
+                    }, children: validationError })) : null, surfaces.map(surface => (_jsx(Box, { sx: {
+                        border: '1px solid',
+                        borderColor: 'border.default',
+                        borderRadius: 2,
+                        p: 3,
+                        bg: 'canvas.default',
+                    }, children: _jsx(A2uiSurfaceComposed, { surface: surface }) }, surface.id)))] }) }));
+}
+export default InlineSurface;

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

@@ -0,0 +1,38 @@
+/**
+ * One `render_a2ui_surface` result in the transcript: the surface, and what
+ * pressing its Submit does.
+ *
+ * The values are checked against the rules the tool sent with the surface —
+ * a missing required field is said under the form — and, when they pass,
+ * handed back to the agent as the reader's next turn, so the confirmation
+ * arrives in the conversation where the form was asked for. A host that
+ * wants to know is told too (`onRendered`, `onSubmitted`): the A2UI Agent
+ * example mirrors the surface on a canvas beside the chat.
+ *
+ * @module loop/plugins/a2ui-surface/SurfaceToolResult
+ */
+import type { JSX } from 'react';
+import type { A2uiMessage } from '@a2ui/web_core/v0_9';
+import type { ToolCallRenderContext } from '../../../types/chat';
+import { type A2uiToolResult } from './toolResult';
+export type SurfaceRendered = {
+    toolCallId: string;
+    surfaceId?: string;
+    title: string;
+    messages: A2uiMessage[];
+    result: A2uiToolResult;
+};
+export type SurfaceSubmitted = {
+    surfaceId: string;
+    title: string;
+    values: Record<string, unknown>;
+};
+export type SurfaceToolResultProps = {
+    context: ToolCallRenderContext;
+    /** Say something as the reader; `false` when the chat cannot take it. */
+    send: (message: string) => boolean;
+    onRendered?: (rendered: SurfaceRendered) => void;
+    onSubmitted?: (submitted: SurfaceSubmitted) => void;
+};
+export declare function SurfaceToolResult({ context, send, onRendered, onSubmitted, }: SurfaceToolResultProps): JSX.Element;
+export default SurfaceToolResult;

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

@@ -0,0 +1,64 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useState } from 'react';
+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 { readA2uiToolResult, validateA2uiSubmission, } from './toolResult';
+export function SurfaceToolResult({ context, send, onRendered, onSubmitted, }) {
+    const parsed = useMemo(() => context.status === 'complete'
+        ? readA2uiToolResult(context.result, SURFACE_CATALOG_ID)
+        : null, [context.status, context.result]);
+    const title = parsed?.title ?? 'the form';
+    const [validationError, setValidationError] = useState(null);
+    // Told once per result, when it is there to be told about.
+    useEffect(() => {
+        if (parsed?.messages && parsed.messages.length > 0) {
+            onRendered?.({
+                toolCallId: context.toolCallId,
+                surfaceId: parsed.surfaceId,
+                title,
+                messages: parsed.messages,
+                result: parsed,
+            });
+        }
+        // The result is what changes; the callback's identity is the host's.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [parsed, context.toolCallId]);
+    const handleAction = useCallback((action) => {
+        if (action.name !== 'submit_a2ui_form') {
+            return;
+        }
+        const values = (action.context ?? {});
+        const errors = validateA2uiSubmission(parsed?.fieldRules ?? [], values);
+        if (errors.length > 0) {
+            setValidationError(errors.join(' '));
+            return;
+        }
+        setValidationError(null);
+        onSubmitted?.({ surfaceId: action.surfaceId, title, values });
+        const sent = send(encodeFormSubmission({
+            title,
+            surfaceId: action.surfaceId,
+            values,
+        }));
+        if (!sent) {
+            setValidationError('The chat is not ready to take the submission yet.');
+        }
+    }, [parsed, title, send, onSubmitted]);
+    if (!parsed?.messages || parsed.messages.length === 0) {
+        return (_jsxs(Box, { sx: {
+                border: '1px solid',
+                borderColor: 'border.default',
+                borderRadius: 2,
+                px: 3,
+                py: 2,
+                bg: 'canvas.default',
+                display: 'flex',
+                alignItems: 'center',
+                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 })] }));
+}
+export default SurfaceToolResult;

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

@@ -0,0 +1,34 @@
+import type { ReactorPlugin } from '@datalayer/reactor';
+import { type SurfaceRendered, type SurfaceSubmitted } from './SurfaceToolResult';
+export declare const A2UI_SURFACE_PLUGIN_NAME = "@datalayer/loop-plugin-a2ui-surface";
+/** The renderer name a spec binds a tool to. */
+export declare const A2UI_SURFACE_RENDERER = "a2ui-surface";
+/**
+ * Every tool some spec binds to this renderer.
+ *
+ * Read from the specs rather than from the workspace's current agent: a
+ * tool result arrives named by its tool, and a name bound in any spec is a
+ * surface wherever it turns up.
+ */
+export declare function surfaceToolNames(): Set<string>;
+export type A2uiSurfacePluginOptions = {
+    /** Told when a surface has been drawn from a tool result. */
+    onRendered?: (rendered: SurfaceRendered) => void;
+    /** Told when a submission passed its checks and went to the agent. */
+    onSubmitted?: (submitted: SurfaceSubmitted) => void;
+};
+/**
+ * An instance of the plugin, with a host's callbacks.
+ *
+ * The chat reaches a workspace's `send` only through slot props, so the
+ * plugin keeps a silent component in the chat's title-bar slot — it draws
+ * nothing and holds the `send` of the workspace it is in. The slot is asked
+ * whether anyone contributed before it is drawn, so this costs the header
+ * no space.
+ */
+export declare function createA2uiSurfacePlugin(options?: A2uiSurfacePluginOptions): ReactorPlugin<Record<string, never>, unknown, unknown>;
+/** The instance the preset mounts: no host callbacks. */
+export declare const A2uiSurfacePlugin: ReactorPlugin<Record<string, never>, unknown, unknown>;
+export type { SurfaceRendered, SurfaceSubmitted } from './SurfaceToolResult';
+export { readA2uiToolResult, validateA2uiField, validateA2uiSubmission, type A2uiFieldRule, type A2uiToolResult, } from './toolResult';
+export default A2uiSurfacePlugin;

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

@@ -0,0 +1,91 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from 'react';
+import { contribution, definePlugin, signal } from '@datalayer/reactor';
+import { AGENTSPECS } from '../../../specs/agents';
+import { LoopChatExtras, LoopSlots, } from '../../core';
+import { SurfaceToolResult, } from './SurfaceToolResult';
+export const A2UI_SURFACE_PLUGIN_NAME = '@datalayer/loop-plugin-a2ui-surface';
+/** The renderer name a spec binds a tool to. */
+export const A2UI_SURFACE_RENDERER = 'a2ui-surface';
+/**
+ * Every tool some spec binds to this renderer.
+ *
+ * Read from the specs rather than from the workspace's current agent: a
+ * tool result arrives named by its tool, and a name bound in any spec is a
+ * surface wherever it turns up.
+ */
+export function surfaceToolNames() {
+    const names = new Set();
+    for (const spec of Object.values(AGENTSPECS)) {
+        for (const binding of spec.frontendRenderTools ?? []) {
+            if (binding.renderer === A2UI_SURFACE_RENDERER) {
+                names.add(binding.tool);
+            }
+        }
+    }
+    return names;
+}
+let counter = 0;
+/**
+ * An instance of the plugin, with a host's callbacks.
+ *
+ * The chat reaches a workspace's `send` only through slot props, so the
+ * plugin keeps a silent component in the chat's title-bar slot — it draws
+ * nothing and holds the `send` of the workspace it is in. The slot is asked
+ * whether anyone contributed before it is drawn, so this costs the header
+ * no space.
+ */
+export function createA2uiSurfacePlugin(options = {}) {
+    const id = `a2ui-surface-${(counter += 1)}`;
+    let currentSend;
+    const send = (message) => {
+        if (!currentSend) {
+            return false;
+        }
+        currentSend(message);
+        return true;
+    };
+    function Capture({ workspace, }) {
+        const workspaceSend = workspace?.viewControls.send;
+        useEffect(() => {
+            currentSend = workspaceSend;
+            return () => {
+                if (currentSend === workspaceSend) {
+                    currentSend = undefined;
+                }
+            };
+        }, [workspaceSend]);
+        return null;
+    }
+    const tools = surfaceToolNames();
+    // A failed call is the chat's to draw: its default card says what went
+    // wrong, and a spinner that never ends would say nothing at all. So is
+    // every tool that is not a surface: this renderer is the chat's only one,
+    // and returning nothing for a tool it does not own hid every other tool
+    // row — the notebook reads, the cell runs — from the transcript.
+    const renderToolResult = (context) => tools.has(context.toolName) && context.status !== 'error' ? (_jsx(SurfaceToolResult, { context: context, send: send, onRendered: options.onRendered, onSubmitted: options.onSubmitted }, context.toolCallId)) : (context.defaultUI);
+    const plugin = definePlugin({
+        name: counter === 1
+            ? A2UI_SURFACE_PLUGIN_NAME
+            : `${A2UI_SURFACE_PLUGIN_NAME}-${id}`,
+        displayName: 'A2UI surfaces',
+        description: 'Generated surfaces drawn in the transcript, and submitted back to the agent.',
+        octicon: 'browser',
+        emoji: '\u{1FA9F}',
+        contributes: [
+            contribution(LoopChatExtras, { id, extras: signal({ renderToolResult }) }, { id }),
+        ],
+        build() {
+            return {
+                components: [
+                    { slot: LoopSlots.chatHeader, id, Component: Capture },
+                ],
+            };
+        },
+    });
+    return plugin;
+}
+/** The instance the preset mounts: no host callbacks. */
+export const A2uiSurfacePlugin = createA2uiSurfacePlugin();
+export { readA2uiToolResult, validateA2uiField, validateA2uiSubmission, } from './toolResult';
+export default A2uiSurfacePlugin;

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

@@ -0,0 +1,52 @@
+/**
+ * What the `render_a2ui_surface` tool answers, read and checked.
+ *
+ * Pure: no React, no catalogue instance. What is here is what a test wants
+ * to reach without a chat around it — the shape of a result, the rules a
+ * surface ships for its own fields, and the verdict on a submission.
+ *
+ * @module loop/plugins/a2ui-surface/toolResult
+ */
+import type { A2uiMessage } from '@a2ui/web_core/v0_9';
+export type A2uiRequiredField = {
+    id: string;
+    label: string;
+};
+/**
+ * Per-field validation descriptor emitted by the backend tool. The rules
+ * gate a submission: required, email format, pattern, length, slider range.
+ */
+export type A2uiFieldRule = {
+    id: string;
+    label: string;
+    type?: string;
+    required?: boolean;
+    format?: 'email';
+    pattern?: string;
+    minLength?: number;
+    min?: number;
+    max?: number;
+};
+export type A2uiToolResult = {
+    surfaceId?: string;
+    title?: string;
+    messages?: A2uiMessage[];
+    requiredFields?: A2uiRequiredField[];
+    fieldRules?: A2uiFieldRule[];
+};
+/**
+ * Read a tool result — an object, or the JSON of one — as A2UI messages,
+ * with the catalogue id rewritten to `catalogId` so the frontend catalogue
+ * accepts what a backend named by its own id.
+ */
+export declare function readA2uiToolResult(result: unknown, catalogId: string): A2uiToolResult | null;
+/**
+ * Whether a submitted value counts as "not provided". Handles the shapes the
+ * basic catalogue emits: strings (text/email), arrays (choice), booleans
+ * (checkbox).
+ */
+export declare function isEmptyA2uiValue(value: unknown): boolean;
+/** One rule's complaint about one value, or `null` when it is acceptable. */
+export declare function validateA2uiField(rule: A2uiFieldRule, value: unknown): string | null;
+/** Every rule's complaint about a submission; empty when it passes. */
+export declare function validateA2uiSubmission(rules: A2uiFieldRule[], values: Record<string, unknown>): string[];

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

@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Read a tool result — an object, or the JSON of one — as A2UI messages,
+ * with the catalogue id rewritten to `catalogId` so the frontend catalogue
+ * accepts what a backend named by its own id.
+ */
+export function readA2uiToolResult(result, catalogId) {
+    if (!result) {
+        return null;
+    }
+    let obj = result;
+    if (typeof result === 'string') {
+        try {
+            obj = JSON.parse(result);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof obj !== 'object' ||
+        obj === null ||
+        !Array.isArray(obj.messages)) {
+        return null;
+    }
+    const parsed = obj;
+    const messages = (parsed.messages ?? []).map(message => {
+        const payload = message;
+        if (payload.createSurface &&
+            payload.createSurface.catalogId !== catalogId) {
+            return {
+                ...payload,
+                createSurface: { ...payload.createSurface, catalogId },
+            };
+        }
+        return message;
+    });
+    return { ...parsed, messages };
+}
+/**
+ * Whether a submitted value counts as "not provided". Handles the shapes the
+ * basic catalogue emits: strings (text/email), arrays (choice), booleans
+ * (checkbox).
+ */
+export function isEmptyA2uiValue(value) {
+    if (value === null || value === undefined) {
+        return true;
+    }
+    if (typeof value === 'string') {
+        return value.trim() === '';
+    }
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+    if (typeof value === 'boolean') {
+        return value === false;
+    }
+    return false;
+}
+/** Permissive on purpose: `local@domain.tld` with no spaces. */
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/** One rule's complaint about one value, or `null` when it is acceptable. */
+export function validateA2uiField(rule, value) {
+    if (isEmptyA2uiValue(value)) {
+        return rule.required ? `${rule.label} is required.` : null;
+    }
+    if (rule.format === 'email' &&
+        typeof value === 'string' &&
+        !EMAIL_PATTERN.test(value.trim())) {
+        return `${rule.label} must be a valid email address.`;
+    }
+    if (rule.pattern && typeof value === 'string') {
+        let matches;
+        try {
+            matches = new RegExp(rule.pattern).test(value.trim());
+        }
+        catch {
+            matches = true; // A malformed pattern blocks nothing.
+        }
+        if (!matches) {
+            return `${rule.label} is not in the expected format.`;
+        }
+    }
+    if (rule.minLength !== undefined &&
+        typeof value === 'string' &&
+        value.trim().length < rule.minLength) {
+        return `${rule.label} must be at least ${rule.minLength} characters.`;
+    }
+    if (rule.type === 'slider' && typeof value === 'number') {
+        if (rule.min !== undefined && value < rule.min) {
+            return `${rule.label} must be at least ${rule.min}.`;
+        }
+        if (rule.max !== undefined && value > rule.max) {
+            return `${rule.label} must be at most ${rule.max}.`;
+        }
+    }
+    return null;
+}
+/** Every rule's complaint about a submission; empty when it passes. */
+export function validateA2uiSubmission(rules, values) {
+    return rules
+        .map(rule => validateA2uiField(rule, values[rule.id]))
+        .filter((message) => message !== null);
+}