@datalayer/agent-runtimes 1.4.0 → 1.5.1

package/lib/apps/plugins/app-page/pageRun.js

@@ -7,8 +7,8 @@
  *
  * The page opens a session of the application's agent on its runtime
  * (`POST /api/v1/apps/sessions`), then, each time an input changes, sends
- * them all as the session's `page` action (`POST …/sessions/{uid}/actions`,
- * `{name: "page", payload: {inputs}}`). The runtime checks them against the
+ * them all to its page (`POST …/sessions/{uid}/page`, `{inputs}`) — not an
+ * action of its code (REACTOR_UI RU-5). The runtime checks them against the
  * page's form — refused with 422 and a sentence — runs its code's
  * `@app.page` on them, and answers its outputs as a `CUSTOM` event named
  * `loop.page`, `{inputs, outputs}`, which the page shows in place. Nothing is
@@ -98,7 +98,7 @@ export async function openPageSession(context) {
  */
 export async function runPageIn(context, uid, inputs) {
     try {
-        const stream = await posted(context, `${base(context)}/${encodeURIComponent(uid)}/actions`, { name: 'page', payload: { inputs } });
+        const stream = await posted(context, `${base(context)}/${encodeURIComponent(uid)}/page`, { inputs });
         return pageTurnOf(stream);
     }
     catch (error) {

package/lib/apps/plugins/chat/ChatView.js

@@ -6,7 +6,7 @@ import { ScreenFullIcon, ScreenNormalIcon } from '@primer/octicons-react';
 import { computed, signal } from '@datalayer/reactor';
 /* A signal to read when the layout publishes no live stance: the hook needs one. */
 const NO_STANCE = signal(undefined);
-import { useContributions, useSignalValue, useGate, useReactorPlatform, ReactorLazy, ReactorSlot, useSlotComponents, } from '@datalayer/reactor/react';
+import { useAgentToolBundles, useContributions, useSignalValue, useGate, useReactorPlatform, ReactorLazy, ReactorSlot, useSlotComponents, } from '@datalayer/reactor/react';
 import { ChatBase } from '../../../chat/base/ChatBase';
 import { useChatAvailability } from '../../../chat/base/ChatAvailability';
 import { offeredModels as offeredModelsFor, readServerCatalogue, readServerDecisions, } from '../../../chat/base/modelChoice';
@@ -45,7 +45,7 @@ import { AI_MODEL_CATALOGUE, isChatModel } from '../../../specs/models';
 import { LoopAgentBlueprint, LoopAgentGate, LoopChatComposer, LoopChatExtras, LoopChatHeader, LoopChatLayout, LoopChatSuggestion, LoopChatSurface, LoopChatTurn, LoopCommand, LoopFrontendTool, LoopRunProps, LoopSlots, agentServerOf, noRuntimeSaid, canOpenView, runForwardedProps, onPromptFocusRequest, onSurfaceRequest, useLoopPromptStore, } from '../../core';
 import { messageText, turnWritersOf } from './turnState';
 import { isInactiveSurfaceContribution, orderToolContributions, toolsForChatView, } from './chatViewTools';
-import { useAgentCommandTools } from '../../../tools/adapters/commands';
+import { agentBundleToolDefinitions, useAgentCommandTools, } from '../../../tools/adapters/commands';
 import { NONE_EDITOR, seedEditorChoice, setEditorOptions, } from '../shell/editorChoice';
 import { generateMessageId } from '../../../types/messages';
 import { openThread, THREAD_WORDS } from '../../apps/threads';
@@ -982,6 +982,23 @@ export default function ChatView({ workspace }) {
             ...commandTools.filter(tool => !taken.has(tool.name)),
         ];
     }, [notebookTools, commandTools]);
+    /*
+     * The page's own tools for an agent on a server: a host example's, and
+     * the tools of the `AgentTools` bundles its extras name (REACTOR_UI RU-7:
+     * the host page's functions, `host_<name>`, each running its command on
+     * this reactor). An in-page agent has every bundle already (above).
+     */
+    const bundles = useAgentToolBundles();
+    const handedBundles = chatExtras.agentToolBundles;
+    const pageTools = useMemo(() => {
+        const own = chatExtras.frontendTools ?? [];
+        if (!handedBundles?.length) {
+            return chatExtras.frontendTools;
+        }
+        const handed = agentBundleToolDefinitions(bundles.filter(bundle => handedBundles.includes(bundle.id)), reactor);
+        const taken = new Set(own.map(tool => tool.name));
+        return [...own, ...handed.filter(tool => !taken.has(tool.name))];
+    }, [chatExtras.frontendTools, handedBundles, bundles, reactor]);
     // The page's sandbox, while the agent turned here runs its code in it.
     pageSandboxRef.current =
         inPage && agentTools.some(tool => tool.name === BROWSER_CODE_TOOL)
@@ -1379,6 +1396,8 @@ export default function ChatView({ workspace }) {
                 ...(runsApp
                     ? {
                         uiSocket: `${agentServerUrl.replace(/^http/, 'ws')}/api/v1/apps/ui`,
+                        // Its files, uploaded before what names them (RU-6).
+                        uiFiles: `${agentServerUrl}/api/v1/apps/agents/${encodeURIComponent(agentId)}/files`,
                     }
                     : {}),
                 agentId,
@@ -1731,7 +1750,7 @@ export default function ChatView({ workspace }) {
                           embedded application's run carried no tool at all (seen
                           2026-10-10: `toolsForRequest: []`).
                         */
-                        frontendTools: inPage ? undefined : chatExtras.frontendTools, 
+                        frontendTools: inPage ? undefined : pageTools, 
                         /*
                           The model this view is on, as the chat's opening pick.
           

package/lib/chat/base/ChatBase.js

@@ -19,7 +19,7 @@ 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, } from '@datalayer/reactor/ui';
+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';
@@ -76,6 +76,7 @@ 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.
@@ -1600,6 +1601,22 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     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 {
@@ -3088,6 +3105,16 @@ 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);
@@ -3260,6 +3287,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         getEnabledSkillIds,
         noteThreadStarted,
         chatText,
+        uploadToConversation,
     ]);
     // Send pending prompt once history loaded and adapter/handler available
     useEffect(() => {
@@ -3399,7 +3427,9 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         const words = action.action === ANSWER_ACTION
             ? typeof value === 'string'
                 ? value
-                : 'Answered.'
+                : isFileRef(value)
+                    ? value.name
+                    : 'Answered.'
             : action.action;
         await handleSend(words, {
             loop: {
@@ -3809,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, actOn: protocol?.uiSocket ? actOnDisplay : undefined, 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/uiFiles.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A conversation's files as references (REACTOR_UI RU-6).
+ *
+ * What the page holds of a file it was given — File upload and the composer
+ * read it as `{name, type, data_url}` — is uploaded to the application's
+ * runtime before the run that names it (Reactor's `uploadFile`), and the run
+ * carries the ref it answers (`forwardedProps.loop.files`): a file's bytes
+ * never ride in the run.
+ *
+ * @module chat/base/uiFiles
+ */
+import { type FileRef } from '@datalayer/reactor/ui';
+/** How a file is uploaded to the conversation: its ref. */
+export type UploadToConversation = (file: Blob & {
+    name: string;
+}) => Promise<FileRef>;
+/** A file's bytes from the data URL the page read it as. */
+export declare function blobOfDataUrl(dataUrl: string, name: string, type?: string): Blob & {
+    name: string;
+};
+/** Whether a run's `forwardedProps` names files. */
+export declare function namesFiles(forwardedProps: Record<string, unknown> | undefined): boolean;
+/**
+ * The run's `forwardedProps` with its files uploaded: each file the page
+ * holds replaced by the ref its upload answered, a ref kept as it is.
+ *
+ * @throws for a file that is neither, or an upload refused (its sentence).
+ */
+export declare function withUploadedFiles(forwardedProps: Record<string, unknown>, upload: UploadToConversation): Promise<Record<string, unknown>>;

package/lib/chat/base/uiFiles.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A conversation's files as references (REACTOR_UI RU-6).
+ *
+ * What the page holds of a file it was given — File upload and the composer
+ * read it as `{name, type, data_url}` — is uploaded to the application's
+ * runtime before the run that names it (Reactor's `uploadFile`), and the run
+ * carries the ref it answers (`forwardedProps.loop.files`): a file's bytes
+ * never ride in the run.
+ *
+ * @module chat/base/uiFiles
+ */
+import { isFileRef } from '@datalayer/reactor/ui';
+/** A file's bytes from the data URL the page read it as. */
+export function blobOfDataUrl(dataUrl, name, type) {
+    const [head, body] = [
+        dataUrl.slice(0, dataUrl.indexOf(',')),
+        dataUrl.slice(dataUrl.indexOf(',') + 1),
+    ];
+    if (!head.startsWith('data:') || dataUrl.indexOf(',') < 0) {
+        throw new Error(`${name} could not be read: it is not a data URL.`);
+    }
+    const mediaType = type || head.slice('data:'.length).split(';')[0];
+    // Backed by an ArrayBuffer, as Blob takes it (a SharedArrayBuffer-backed view it refuses).
+    let bytes;
+    if (head.endsWith(';base64')) {
+        const binary = atob(body);
+        bytes = new Uint8Array(binary.length);
+        for (let index = 0; index < binary.length; index += 1) {
+            bytes[index] = binary.charCodeAt(index);
+        }
+    }
+    else {
+        bytes = new TextEncoder().encode(decodeURIComponent(body));
+    }
+    return Object.assign(new Blob([bytes], { type: mediaType }), { name });
+}
+/** Whether a run's `forwardedProps` names files. */
+export function namesFiles(forwardedProps) {
+    const files = forwardedProps?.loop
+        ?.files;
+    return Array.isArray(files) && files.length > 0;
+}
+/**
+ * The run's `forwardedProps` with its files uploaded: each file the page
+ * holds replaced by the ref its upload answered, a ref kept as it is.
+ *
+ * @throws for a file that is neither, or an upload refused (its sentence).
+ */
+export async function withUploadedFiles(forwardedProps, upload) {
+    const loop = forwardedProps.loop;
+    const files = loop.files;
+    const refs = [];
+    for (const given of files) {
+        if (isFileRef(given)) {
+            refs.push(given);
+            continue;
+        }
+        const held = given;
+        if (typeof held.name !== 'string' || typeof held.data_url !== 'string') {
+            throw new Error('A file given is neither the page’s nor a ref.');
+        }
+        refs.push(await upload(blobOfDataUrl(held.data_url, held.name, typeof held.type === 'string' ? held.type : undefined)));
+    }
+    return { ...forwardedProps, loop: { ...loop, files: refs } };
+}

package/lib/chat/messages/ChatMessageList.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode, type RefObject } from 'react';
-import { type Display, type UiAct } from '@datalayer/reactor/ui';
+import { type Display, type UiAct, type UiUpload } from '@datalayer/reactor/ui';
 import { type ChatDensity } from './ChatMarkdown';
 import { type MarkedMcpServer } from '../marks';
 import type { DisplayItem, AvatarConfig } from '../../types/chat';
@@ -20,6 +20,11 @@ export interface ChatMessageListProps {
      * displays offer nothing to press.
      */
     actOn?: (display: Display) => UiAct;
+    /**
+     * How a message's display uploads a file the person chose (REACTOR_UI
+     * RU-6): its ref, to press with. Absent, nothing is uploaded.
+     */
+    upload?: UiUpload;
     /** Whether the agent is loading */
     isLoading: boolean;
     /** Whether the agent is currently streaming */
@@ -104,5 +109,5 @@ export interface SubagentChatPanelProps {
  * approval decisions are sent over the shared monitoring socket.
  */
 export declare function SubagentChatPanel({ toolCallId, subagentName: subagentNameHint, height, avatarConfig, }: SubagentChatPanelProps): React.ReactElement | null;
-export declare function ChatMessageList({ displayItems, actOn, isLoading, isStreaming, showLoadingIndicator, hideMessagesAfterToolUI, avatarConfig, padding, notebookToolSurfacesId, emptyContent, messagesEndRef, onRespond, approvalConfig, showTurnFooters, agentUsage, onRemoveItems, renderMessageFooter, mcpServers, density, }: ChatMessageListProps): import("react").JSX.Element;
+export declare function ChatMessageList({ displayItems, actOn, upload, isLoading, isStreaming, showLoadingIndicator, hideMessagesAfterToolUI, avatarConfig, padding, notebookToolSurfacesId, emptyContent, messagesEndRef, onRespond, approvalConfig, showTurnFooters, agentUsage, onRemoveItems, renderMessageFooter, mcpServers, density, }: ChatMessageListProps): import("react").JSX.Element;
 export {};

package/lib/chat/messages/ChatMessageList.js

@@ -366,7 +366,7 @@ function DefaultToolCallRenderer({ item, onRespond, mcpServers, density, }) {
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export function ChatMessageList({ displayItems, actOn, isLoading, isStreaming, showLoadingIndicator, hideMessagesAfterToolUI, avatarConfig, padding, notebookToolSurfacesId, emptyContent, messagesEndRef, onRespond, approvalConfig, showTurnFooters = false, agentUsage, onRemoveItems, renderMessageFooter, mcpServers, density = 'comfortable', }) {
+export function ChatMessageList({ displayItems, actOn, upload, isLoading, isStreaming, showLoadingIndicator, hideMessagesAfterToolUI, avatarConfig, padding, notebookToolSurfacesId, emptyContent, messagesEndRef, onRespond, approvalConfig, showTurnFooters = false, agentUsage, onRemoveItems, renderMessageFooter, mcpServers, density = 'comfortable', }) {
     /*
      * Who draws a tool call: the Reactor plugins of the page, when it has a
      * platform. Each plugin binds its own tools (`ToolBindings`) and renders its
@@ -611,7 +611,7 @@ export function ChatMessageList({ displayItems, actOn, isLoading, isStreaming, s
                                                 whiteSpace: 'pre-wrap',
                                                 wordBreak: 'break-word',
                                             }, children: [message.metadata?.input === 'voice' ? (_jsx(Box, { as: "span", "data-spoken": "", title: "Said aloud", "aria-label": "Said aloud:", display: "inline-flex", verticalAlign: "text-bottom", mr: 1, opacity: 0.85, children: _jsx(MicrophoneIcon, { size: 14, "aria-hidden": "true" }) })) : null, text] }));
-                                    })()) : message.live && !getMessageText(message) ? (_jsx(TypingDots, { size: 6 })) : (_jsx(ChatMarkdown, { density: density, text: getMessageText(message) || (isStreaming ? '...' : '') }))] }), message.displays?.length ? (_jsx(Box, { "data-chat-displays": "", display: "flex", flexDirection: "column", gap: 2, mt: 2, width: "100%", children: message.displays.map(display => platform ? (_jsx(ReactorDisplay, { display: display, act: actOn?.(display) }, display.id)) : (_jsx(DisplayText, { display: display }, display.id))) })) : null, renderMessageFooter ? (_jsx(Box, { display: "flex", gap: 2, alignItems: "center", mt: 1, flexWrap: "wrap", flexDirection: isUser ? 'row-reverse' : 'row', children: renderMessageFooter(message) })) : null] })] }) }, message.id));
+                                    })()) : message.live && !getMessageText(message) ? (_jsx(TypingDots, { size: 6 })) : (_jsx(ChatMarkdown, { density: density, text: getMessageText(message) || (isStreaming ? '...' : '') }))] }), message.displays?.length ? (_jsx(Box, { "data-chat-displays": "", display: "flex", flexDirection: "column", gap: 2, mt: 2, width: "100%", children: message.displays.map(display => platform ? (_jsx(ReactorDisplay, { display: display, act: actOn?.(display), upload: upload }, display.id)) : (_jsx(DisplayText, { display: display }, display.id))) })) : null, renderMessageFooter ? (_jsx(Box, { display: "flex", gap: 2, alignItems: "center", mt: 1, flexWrap: "wrap", flexDirection: isUser ? 'row-reverse' : 'row', children: renderMessageFooter(message) })) : null] })] }) }, message.id));
     };
     return (_jsxs(_Fragment, { children: [displayItems.map((item, index) => {
                 const itemUI = renderItem(item, index);

package/lib/examples/ProtocolSignedRequestsExample.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Signed requests (Web Bot Auth) in the browser (AGENT_PROTOCOLS EX-10): a
+ * key generated in the page signs one request; the page shows the three
+ * headers, the signature base the key signed, and what a website's check
+ * finds — verified, then the same request replayed and one with its path
+ * changed, both refused. The key never leaves the page and is never shown.
+ */
+import React from 'react';
+declare const ProtocolSignedRequestsExample: React.FC;
+export default ProtocolSignedRequestsExample;

package/lib/examples/ProtocolSignedRequestsExample.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Signed requests (Web Bot Auth) in the browser (AGENT_PROTOCOLS EX-10): a
+ * key generated in the page signs one request; the page shows the three
+ * headers, the signature base the key signed, and what a website's check
+ * finds — verified, then the same request replayed and one with its path
+ * changed, both refused. The key never leaves the page and is never shown.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { Box, setupPrimerPortals } from '@datalayer/primer-addons';
+import { Button, Flash, Heading, Label, Text } from '@primer/react';
+import { ThemedProvider } from './utils/themedProvider';
+import { signedRequestDemo, } from './protocols/signedRequestsDemo';
+setupPrimerPortals();
+const Mono = ({ children, label, }) => (_jsxs(Box, { mb: 3, children: [_jsx(Text, { as: "div", sx: { fontWeight: 'semibold', fontSize: 1, mb: 1 }, children: label }), _jsx(Box, { as: "pre", p: 2, m: 0, bg: "canvas.subtle", borderRadius: 2, sx: { fontSize: 0, whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: children })] }));
+const OUTCOME_VARIANT = {
+    verified: 'success',
+    invalid: 'danger',
+    unverified: 'attention',
+};
+const ProtocolSignedRequestsExample = () => {
+    const [demo, setDemo] = useState(null);
+    const [error, setError] = useState('');
+    const run = useCallback(() => {
+        setError('');
+        signedRequestDemo()
+            .then(setDemo)
+            .catch(failure => setError(String(failure?.message ?? failure)));
+    }, []);
+    useEffect(run, [run]);
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { p: 4, maxWidth: 880, mx: "auto", children: [_jsx(Heading, { as: "h2", sx: { fontSize: 3, mb: 1 }, children: "Signed requests" }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', mt: 0 }, children: "Web Bot Auth (draft-ietf-webbotauth-httpsig-protocol-00): a key generated in this page signs a request to a shop; the shop checks it against the agent's key directory. The private key is never shown." }), _jsx(Button, { onClick: run, sx: { mb: 3 }, children: "Sign again with a new key" }), error ? _jsx(Flash, { variant: "danger", children: error }) : null, demo ? (_jsxs(_Fragment, { children: [_jsxs(Mono, { label: "Request", children: ["GET ", demo.url] }), _jsx(Mono, { label: "Signature-Agent", children: demo.headers['Signature-Agent'] }), _jsx(Mono, { label: "Signature-Input", children: demo.headers['Signature-Input'] }), _jsx(Mono, { label: "Signature", children: demo.headers.Signature }), _jsx(Mono, { label: "Signature base (what the key signed)", children: demo.base }), _jsx(Mono, { label: "Public key in the directory (keyid: its thumbprint)", children: JSON.stringify(demo.publicJwk, null, 2) }), _jsx(Box, { display: "grid", gap: 2, children: [
+                                ['The shop checks it', demo.verified],
+                                ['The same request again', demo.replayed],
+                                ['Its path changed', demo.tampered],
+                            ].map(([what, found]) => (_jsxs(Box, { display: "flex", gap: 2, alignItems: "baseline", children: [_jsx(Label, { variant: OUTCOME_VARIANT[found.outcome], children: found.outcome }), _jsxs(Text, { sx: { fontSize: 1 }, children: [what, found.reason ? `: ${found.reason}` : ''] })] }, what))) })] })) : null] }) }));
+};
+export default ProtocolSignedRequestsExample;

package/lib/examples/ProtocolUcpCheckoutExample.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A UCP checkout approved as a card (AGENT_PROTOCOLS EX-10, after EX-04):
+ * the UCP client buys from *Example Store*, the local test merchant running
+ * in the page. The exact purchase is proposed; completing it asks the
+ * approver — the card below — once; approving buys once, and the same
+ * proposal is refused after. The test payment's token is never shown.
+ */
+import React from 'react';
+declare const ProtocolUcpCheckoutExample: React.FC;
+export default ProtocolUcpCheckoutExample;

package/lib/examples/ProtocolUcpCheckoutExample.js

@@ -0,0 +1,59 @@
+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.
+ */
+/**
+ * A UCP checkout approved as a card (AGENT_PROTOCOLS EX-10, after EX-04):
+ * the UCP client buys from *Example Store*, the local test merchant running
+ * in the page. The exact purchase is proposed; completing it asks the
+ * approver — the card below — once; approving buys once, and the same
+ * proposal is refused after. The test payment's token is never shown.
+ */
+import { useMemo, useRef, useState } from 'react';
+import { Box, setupPrimerPortals } from '@datalayer/primer-addons';
+import { Button, Flash, Heading, Text } from '@primer/react';
+import { ThemedProvider } from './utils/themedProvider';
+import { buy, proposeTea, ucpCheckoutDemo } from './protocols/ucpCheckoutDemo';
+setupPrimerPortals();
+const ProtocolUcpCheckoutExample = () => {
+    const answer = useRef(null);
+    const [asking, setAsking] = useState(false);
+    const demo = useMemo(() => ucpCheckoutDemo(() => new Promise(resolve => {
+        answer.current = resolve;
+        setAsking(true);
+    })), []);
+    const [proposal, setProposal] = useState(null);
+    const [said, setSaid] = useState([]);
+    const [working, setWorking] = useState(false);
+    const propose = async () => {
+        setWorking(true);
+        try {
+            setProposal(await proposeTea(demo));
+        }
+        catch (error) {
+            setSaid(s => [
+                ...s,
+                { ok: false, says: String(error.message) },
+            ]);
+        }
+        finally {
+            setWorking(false);
+        }
+    };
+    const complete = async () => {
+        if (!proposal)
+            return;
+        setWorking(true);
+        const outcome = await buy(demo, proposal.proposal);
+        setSaid(s => [...s, outcome]);
+        setWorking(false);
+    };
+    const decide = (approved) => {
+        setAsking(false);
+        answer.current?.(approved);
+        answer.current = null;
+    };
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { p: 4, maxWidth: 720, mx: "auto", children: [_jsx(Heading, { as: "h2", sx: { fontSize: 3, mb: 1 }, children: "UCP checkout" }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', mt: 0 }, children: "Universal Commerce Protocol 2026-08-25, against Example Store, a test merchant running in this page. Nothing is bought without the card below, and a proposal buys once." }), _jsxs(Box, { display: "flex", gap: 2, mb: 3, flexWrap: "wrap", children: [_jsx(Button, { onClick: propose, disabled: working || asking, children: "Propose 2 \u00D7 Sencha green tea" }), _jsx(Button, { variant: "primary", onClick: complete, disabled: !proposal || working, children: "Complete the purchase" })] }), proposal && asking ? (_jsxs(Box, { p: 3, mb: 3, border: "1px solid", borderColor: "attention.emphasis", borderRadius: 2, role: "dialog", "aria-label": "Approve this purchase", children: [_jsx(Text, { as: "p", sx: { fontWeight: 'semibold', mt: 0 }, children: "Approve this purchase?" }), _jsx(Text, { as: "p", children: proposal.says }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', fontSize: 0 }, children: ["Revision ", proposal.proposal.revision.slice(0, 12), "\u2026 \u2014 if the basket changes, it is proposed again."] }), _jsxs(Box, { display: "flex", gap: 2, children: [_jsx(Button, { variant: "primary", onClick: () => decide(true), children: "Approve" }), _jsx(Button, { onClick: () => decide(false), children: "Decline" })] })] })) : proposal ? (_jsxs(Text, { as: "p", sx: { fontSize: 1 }, children: ["Proposed: ", proposal.says] })) : null, said.map((each, index) => (_jsx(Flash, { variant: each.ok ? 'success' : 'warning', sx: { mb: 2 }, children: each.says }, index))), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', fontSize: 0 }, children: ["Orders at the store: ", demo.orders.length] })] }) }));
+};
+export default ProtocolUcpCheckoutExample;

package/lib/examples/example-selector.js

@@ -131,6 +131,8 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('AgentSubagentsExample', () => import('./AgentSubagentsExample'), 'Multi-agent delegation with the in-repo subagents capability.'),
     makeEntry('AgentA2AExample', () => import('./AgentA2AExample'), 'Delegation to separate agents over the A2A protocol, launched locally or on Datalayer runtimes.'),
     makeEntry('AgentA2ATeamExample', () => import('./AgentA2ATeamExample'), 'Two applications as a team over A2A: Sales in the browser (@a2a-js/sdk) asks Accounting on a runtime (fasta2a, Odoo read only), each an Office Assistant character.'),
+    makeEntry('ProtocolSignedRequestsExample', () => import('./ProtocolSignedRequestsExample'), 'Web Bot Auth in the browser: a key made in the page signs a request — its three headers and the signature base — verified, then a replay and a changed path refused.'),
+    makeEntry('ProtocolUcpCheckoutExample', () => import('./ProtocolUcpCheckoutExample'), 'A UCP checkout at a test store in the page: the exact purchase proposed, approved on a card once, bought once.'),
     makeEntry('PapCompanyDiscoveryExample', () => import('./PapCompanyDiscoveryExample'), 'Validate a PAP company document and reduce it to the public capabilities safe for an agent or UI.'),
     makeEntry('PapAgentIdentityExample', () => import('./PapAgentIdentityExample'), 'Verify personal-agent client metadata and signing policy without exposing JWK coordinates.'),
     makeEntry('PapAuthorizationBoundaryExample', () => import('./PapAuthorizationBoundaryExample'), 'Generate real Session and Direct Sign-In security material while showing only safe policy status.'),

package/lib/examples/exampleGroups.d.ts

@@ -5,5 +5,5 @@
  *
  * @module examples/exampleGroups
  */
-export declare const EXAMPLE_GROUP_ORDER: readonly ["Apps", "Assistant", "A2UI", "A2A", "Personal Agent Protocol", "AG-UI", "Chat", "Document", "Notebook", "Capabilities", "Cell", "CopilotKit"];
+export declare const EXAMPLE_GROUP_ORDER: readonly ["Apps", "Assistant", "A2UI", "A2A", "Personal Agent Protocol", "Agent protocols", "AG-UI", "Chat", "Document", "Notebook", "Capabilities", "Cell", "CopilotKit"];
 export declare const getExampleGroup: (id: string) => string;

package/lib/examples/exampleGroups.js

@@ -15,6 +15,7 @@ export const EXAMPLE_GROUP_ORDER = [
     'A2UI',
     'A2A',
     'Personal Agent Protocol',
+    'Agent protocols',
     'AG-UI',
     'Chat',
     'Document',
@@ -39,6 +40,9 @@ export const getExampleGroup = (id) => {
         return 'A2A';
     if (id.startsWith('Pap'))
         return 'Personal Agent Protocol';
+    // The other agent protocols' examples: signed requests, commerce (AGENT_PROTOCOLS EX-10).
+    if (id.startsWith('Protocol'))
+        return 'Agent protocols';
     if (id.startsWith('AgUi'))
         return 'AG-UI';
     if (id.startsWith('CopilotKit'))

package/lib/examples/index.d.ts

@@ -27,6 +27,8 @@ export { default as AgentCodemodeExample } from './AgentCodemodeExample';
 export { default as AgentCodeSandboxesExample } from './AgentCodeSandboxesExample';
 export { default as AgentDecideExample } from './AgentDecideExample';
 export { default as AgentA2ATeamExample } from './AgentA2ATeamExample';
+export { default as ProtocolSignedRequestsExample } from './ProtocolSignedRequestsExample';
+export { default as ProtocolUcpCheckoutExample } from './ProtocolUcpCheckoutExample';
 export { default as PapCompanyDiscoveryExample } from './PapCompanyDiscoveryExample';
 export { default as PapAgentIdentityExample } from './PapAgentIdentityExample';
 export { default as PapAuthorizationBoundaryExample } from './PapAuthorizationBoundaryExample';

package/lib/examples/index.js

@@ -33,6 +33,8 @@ export { default as AgentCodemodeExample } from './AgentCodemodeExample';
 export { default as AgentCodeSandboxesExample } from './AgentCodeSandboxesExample';
 export { default as AgentDecideExample } from './AgentDecideExample';
 export { default as AgentA2ATeamExample } from './AgentA2ATeamExample';
+export { default as ProtocolSignedRequestsExample } from './ProtocolSignedRequestsExample';
+export { default as ProtocolUcpCheckoutExample } from './ProtocolUcpCheckoutExample';
 export { default as PapCompanyDiscoveryExample } from './PapCompanyDiscoveryExample';
 export { default as PapAgentIdentityExample } from './PapAgentIdentityExample';
 export { default as PapAuthorizationBoundaryExample } from './PapAuthorizationBoundaryExample';

package/lib/examples/protocols/signedRequestsDemo.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The *Signed requests* gallery example's work (AGENT_PROTOCOLS EX-10): a
+ * fresh Ed25519 key generated in the page, one request signed with it
+ * (`signRequest`), the three headers and the signature base the signer was
+ * handed, then the request verified against the key's directory — and the
+ * same request replayed, and one with its path changed, both refused.
+ *
+ * The key never leaves the page and is never shown: only its public JWK and
+ * thumbprint are. No network: the directory is read from memory.
+ *
+ * @module examples/protocols/signedRequestsDemo
+ */
+import { type PublicJwk, type SignedHeaders, type Verification } from '../../protocols/web-bot-auth';
+export interface SignedRequestDemo {
+    /** The key's thumbprint, the `keyid` of the signature. */
+    keyid: string;
+    publicJwk: PublicJwk;
+    url: string;
+    headers: SignedHeaders;
+    /** The signature base, exactly as the signer signed it. */
+    base: string;
+    verified: Verification;
+    replayed: Verification;
+    tampered: Verification;
+}
+/** Sign one request with a fresh key, and verify it three ways. */
+export declare function signedRequestDemo(url?: string, agent?: string): Promise<SignedRequestDemo>;

package/lib/examples/protocols/signedRequestsDemo.js

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The *Signed requests* gallery example's work (AGENT_PROTOCOLS EX-10): a
+ * fresh Ed25519 key generated in the page, one request signed with it
+ * (`signRequest`), the three headers and the signature base the signer was
+ * handed, then the request verified against the key's directory — and the
+ * same request replayed, and one with its path changed, both refused.
+ *
+ * The key never leaves the page and is never shown: only its public JWK and
+ * thumbprint are. No network: the directory is read from memory.
+ *
+ * @module examples/protocols/signedRequestsDemo
+ */
+import { InMemoryNonceStore, generateLocalSigner, keyResolver, signRequest, verifyRequest, } from '../../protocols/web-bot-auth';
+/** A signer that keeps what it was asked to sign: the signature base. */
+function recording(signer) {
+    const bases = [];
+    return {
+        keyid: signer.keyid,
+        algorithm: signer.algorithm,
+        bases,
+        async sign(data) {
+            bases.push(new TextDecoder().decode(data));
+            return signer.sign(data);
+        },
+    };
+}
+/** Sign one request with a fresh key, and verify it three ways. */
+export async function signedRequestDemo(url = 'https://shop.example/products?q=tea', agent = 'https://agent.example') {
+    const { signer, publicJwk } = await generateLocalSigner();
+    const keeping = recording(signer);
+    const headers = await signRequest(new Request(url), keeping, { agent });
+    // The shop finds the agent's keys in its directory: here, in memory.
+    const resolver = keyResolver({
+        directory: { keys: async () => [publicJwk] },
+    });
+    const nonceStore = new InMemoryNonceStore();
+    const sent = (to) => new Request(to, { headers: { ...headers } });
+    const verified = await verifyRequest(sent(url), resolver, { nonceStore });
+    const replayed = await verifyRequest(sent(url), resolver, { nonceStore });
+    const changed = new URL(url);
+    changed.pathname = '/checkout';
+    const tampered = await verifyRequest(sent(changed.toString()), resolver, {
+        nonceStore: new InMemoryNonceStore(),
+    });
+    return {
+        keyid: signer.keyid,
+        publicJwk,
+        url,
+        headers,
+        base: keeping.bases[0] ?? '',
+        verified,
+        replayed,
+        tampered,
+    };
+}

package/lib/examples/protocols/ucpCheckoutDemo.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The *UCP checkout* gallery example's work (AGENT_PROTOCOLS EX-10, after
+ * EX-04): the UCP client buying from *Example Store*, the local test
+ * merchant running in the page (`protocols/ucp/merchant`). A checkout is
+ * proposed as an exact, revisioned purchase; completing it asks the host's
+ * approver — the page's card — once, and the proposal is spent whatever the
+ * answer. The payment is the test handler's; its token is never shown.
+ *
+ * @module examples/protocols/ucpCheckoutDemo
+ */
+import { type ReactorPlatform } from '@datalayer/reactor';
+import { UcpClient, type CheckoutProposal } from '../../protocols/ucp';
+export declare const STORE = "https://store.example";
+export declare const AGENT_PROFILE = "https://agent.example/.well-known/ucp";
+/** The test payment's token: held by the host, never in a summary or a proposal. */
+export declare const TEST_TOKEN = "tok_test_gallery_never_shown";
+export interface UcpCheckoutDemo {
+    client: UcpClient;
+    reactor: ReactorPlatform;
+    orders: Array<{
+        order: string;
+        checkout: string;
+    }>;
+}
+/** The client, the store, and a host whose approver is `decide`. */
+export declare function ucpCheckoutDemo(decide: (proposal: CheckoutProposal) => Promise<boolean>): UcpCheckoutDemo;
+/** Find the tea, put `quantity` in a checkout with the buyer's email, and propose it. */
+export declare function proposeTea(demo: UcpCheckoutDemo, quantity?: number, email?: string): Promise<{
+    proposal: CheckoutProposal;
+    says: string;
+}>;
+/** Complete the proposal: the approver is asked; the order, or why not. */
+export declare function buy(demo: UcpCheckoutDemo, proposal: CheckoutProposal): Promise<{
+    ok: boolean;
+    says: string;
+}>;