@datalayer/agent-runtimes 1.3.86 → 1.3.88

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

@@ -46,6 +46,8 @@ import { messageText, turnWritersOf } from './turnState';
 import { isInactiveSurfaceContribution, orderToolContributions, toolsForChatView, } from './chatViewTools';
 import { 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';
 import { FaceDrawing, PresenceFace, PresenceLine, } from '../../../chat/presence/Presence';
 import { presenceState, presenceToolOf, } from '../../../chat/presence/presenceStatus';
 import { latestSaying, newestIsAnswer, } from '../../../chat/assistant/state';
@@ -1180,6 +1182,74 @@ export default function ChatView({ workspace }) {
     // not know (LOOP R-20): it runs a session of its deployment, and no more.
     const embedToken = reactor.getConfig(AGENTS_PLUGIN_NAME)?.embedToken;
     const iamToken = visitors ? visitor.token : embedToken || memberToken;
+    /*
+     * A thread opened from the person's history (LOOP P-24): its conversation
+     * read from the runtime once it answers — held there, else resumed from
+     * its record — then drawn and gone on with on the same thread. One that
+     * cannot be opened is said, and a new one starts.
+     */
+    const givenThread = config?.thread;
+    const [openedThread, setOpenedThread] = useState(null);
+    const opening = Boolean(givenThread?.fromRuntime && openedThread?.given !== givenThread.id);
+    useEffect(() => {
+        if (!givenThread?.fromRuntime || !runsApp || !agentServerUrl) {
+            return;
+        }
+        let current = true;
+        void (async () => {
+            let failure = '';
+            for (let attempt = 0; attempt < 4 && current; attempt += 1) {
+                try {
+                    const messages = await openThread({
+                        agentBaseUrl: agentServerUrl,
+                        agentId,
+                        uid: givenThread.id,
+                        token: iamToken,
+                    });
+                    if (current) {
+                        setOpenedThread({
+                            given: givenThread.id,
+                            thread: { ...givenThread, fromRuntime: false, messages },
+                        });
+                    }
+                    return;
+                }
+                catch (error) {
+                    failure = error instanceof Error ? error.message : String(error);
+                    // The runtime may still be making the application's agent.
+                    await new Promise(resolve => setTimeout(resolve, 1500));
+                }
+            }
+            if (current) {
+                setOpenedThread({
+                    given: givenThread.id,
+                    thread: {
+                        id: generateMessageId(),
+                        messages: [],
+                        onStarted: givenThread.onStarted,
+                    },
+                    said: THREAD_WORDS.notOpened(failure),
+                });
+            }
+        })();
+        return () => {
+            current = false;
+        };
+        // By the thread's id: its object is the host's.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        givenThread?.id,
+        givenThread?.fromRuntime,
+        runsApp,
+        agentServerUrl,
+        agentId,
+        iamToken,
+    ]);
+    const chatThread = givenThread?.fromRuntime
+        ? openedThread?.given === givenThread.id
+            ? openedThread.thread
+            : undefined
+        : givenThread;
     const protocol = useMemo(() => inPage
         ? browserProtocolConfig({
             agentId: member?.specId ?? agentId,
@@ -1561,44 +1631,42 @@ export default function ChatView({ workspace }) {
                         borderColor: chatExtras.errorBanner.variant === 'warning'
                             ? 'attention.muted'
                             : 'danger.muted',
-                    }, children: chatExtras.errorBanner.message })) : null, _jsx(Box, { sx: { flex: '1 1 auto', minHeight: 0, display: 'flex' }, children: _jsx(ChatBase
+                    }, children: chatExtras.errorBanner.message })) : null, openedThread?.said && openedThread.given === givenThread?.id ? (_jsx(Text, { as: "p", role: "status", sx: { m: 0, px: 3, py: 2, fontSize: 1, color: 'fg.muted' }, children: openedThread.said })) : null, _jsx(Box, { sx: { flex: '1 1 auto', minHeight: 0, display: 'flex' }, children: opening ? (_jsx(Text, { as: "p", role: "status", sx: { m: 0, p: 3, fontSize: 1, color: 'fg.muted' }, children: THREAD_WORDS.opening })) : (_jsx(ChatBase
                     // The theme it wears, when the host names one (an application's).
                     , { 
                         // The theme it wears, when the host names one (an application's).
-                        themeVariant: config?.themeVariant, themeOverrides: config?.themeOverrides, colorMode: config?.colorMode, 
-                        // The session an embed goes on with after a reload (LOOP D-13).
-                        thread: config?.thread, 
+                        themeVariant: config?.themeVariant, themeOverrides: config?.themeOverrides, colorMode: config?.colorMode, thread: chatThread, 
                         // The header says why, beside the title, for the same reason the
                         // placeholder does: a dead control with no explanation is worse
                         // than an absent one.
                         disabled: chatDisabled, disableReason: disabledReason, protocol: protocol, 
                         /*
-                            The model this view is on, as the chat's opening pick.
-            
-                            `ChatBase` keeps the model it sends with, and opened on the
-                            first row of whatever catalogue it had before the server
-                            answered — Alibaba — while the footer, drawn from
-                            `activeModel`, said Claude. Told the same model, both agree
-                            from the first message.
-                        */
+                          The model this view is on, as the chat's opening pick.
+          
+                          `ChatBase` keeps the model it sends with, and opened on the
+                          first row of whatever catalogue it had before the server
+                          answered — Alibaba — while the footer, drawn from
+                          `activeModel`, said Claude. Told the same model, both agree
+                          from the first message.
+                      */
                         initialModel: activeModel || undefined, 
                         /*
-                            Who is answering, in the words its spec uses.
-            
-                            `ChatBase` falls back to "Start a conversation with the AI
-                            agent", which is true of every chat ever built and says
-                            nothing about this one. The empty state is the first thing a
-                            person sees and the only place the agent introduces itself.
-                          */
+                          Who is answering, in the words its spec uses.
+          
+                          `ChatBase` falls back to "Start a conversation with the AI
+                          agent", which is true of every chat ever built and says
+                          nothing about this one. The empty state is the first thing a
+                          person sees and the only place the agent introduces itself.
+                        */
                         title: presence?.name ?? member?.name ?? spec?.name ?? agentId, description: presence?.welcome ?? spec?.description, 
                         /*
-                            Two sizes, because it is drawn in two places.
-            
-                            The header wants a mark beside a line of text; the empty state
-                            wants the thing a person's eye lands on first. One `brandIcon`
-                            served both, so a 48px icon meant for the empty state sat in
-                            the header at three times the height of the words next to it.
-                          */
+                          Two sizes, because it is drawn in two places.
+          
+                          The header wants a mark beside a line of text; the empty state
+                          wants the thing a person's eye lands on first. One `brandIcon`
+                          served both, so a 48px icon meant for the empty state sat in
+                          the header at three times the height of the words next to it.
+                        */
                         // Big enough to read as the agent's mark rather than as
                         // punctuation before its name, and still short enough not to
                         // set the header's height.
@@ -1615,11 +1683,11 @@ export default function ChatView({ workspace }) {
                             // conversation".
                             title: presence?.name ?? member?.name ?? spec?.name ?? agentId,
                             /*
-                              Two levels when there is a team: the team first — its name,
-                              what it is for, what it can be asked — and under it the
-                              member being addressed, with its own description and its
-                              own openers. The groups match the ones the openers carry.
-                            */
+                            Two levels when there is a team: the team first — its name,
+                            what it is for, what it can be asked — and under it the
+                            member being addressed, with its own description and its
+                            own openers. The groups match the ones the openers carry.
+                          */
                             ...(team && member
                                 ? {
                                     sections: [
@@ -1640,11 +1708,11 @@ export default function ChatView({ workspace }) {
                                 : null),
                         }, 
                         /*
-                            And what it can be asked. From the team rather than the
-                            member: the supervisor answers first, and somebody who has
-                            just opened the workspace does not yet know there are two
-                            agents behind it.
-                          */
+                          And what it can be asked. From the team rather than the
+                          member: the supervisor answers first, and somebody who has
+                          just opened the workspace does not yet know there are two
+                          agents behind it.
+                        */
                         // With the prompt on top the openers are already chips under
                         // it; the empty state repeating them was the same three buttons
                         // twice on one screen.
@@ -1652,11 +1720,11 @@ export default function ChatView({ workspace }) {
                             ? []
                             : chatSuggestions, 
                         /*
-                            The title bar arrives as a plugin: the chat-header plugin
-                            contributes the component, this view hands it the assembled
-                            props through `renderHeader`. No contribution — or a host
-                            that set `hideHeader` — means no bar.
-                          */
+                          The title bar arrives as a plugin: the chat-header plugin
+                          contributes the component, this view hands it the assembled
+                          props through `renderHeader`. No contribution — or a host
+                          that set `hideHeader` — means no bar.
+                        */
                         showHeader: !config?.hideHeader && !!HeaderComponent, 
                         // The `+` and the bin in the title bar, when the host asked for
                         // them; the header draws whatever `ChatBase` assembles here.
@@ -1667,19 +1735,19 @@ export default function ChatView({ workspace }) {
                             ? headerProps => (_jsx(HeaderComponent, { workspace: workspace, header: headerProps }))
                             : undefined, 
                         /*
-                            The (i), which opens the agent's details over the transcript.
-                            
-                            Worth having here in particular: this workspace can be moved
-                            between four runtimes and several agents, and the details pane
-                            is the only place that says which one is actually answering
-                            and where it is running.
-                          */
+                          The (i), which opens the agent's details over the transcript.
+                          
+                          Worth having here in particular: this workspace can be moved
+                          between four runtimes and several agents, and the details pane
+                          is the only place that says which one is actually answering
+                          and where it is running.
+                        */
                         showInformation: true, 
                         /*
-                            Full screen: this view, on the whole screen, editor and all.
-                            See `toggleFullScreen` for why it is the browser's API rather
-                            than a big box.
-                          */
+                          Full screen: this view, on the whole screen, editor and all.
+                          See `toggleFullScreen` for why it is the browser's API rather
+                          than a big box.
+                        */
                         headerActions: _jsxs(Box, { sx: { display: 'inline-flex', alignItems: 'center', gap: 2 }, children: [workspace.chatHeaderActions, chatHeaderItems.length > 0 ? (_jsx(ReactorSlot, { slot: LoopSlots.chatHeader, props: { workspace } })) : null, _jsx(IconButton, { icon: fullScreen ? ScreenNormalIcon : ScreenFullIcon, "aria-label": fullScreen ? 'Exit full screen' : 'Enter full screen', variant: "invisible", size: "small", onClick: () => {
                                         // Whether or not it takes, the hint has been answered:
                                         // they found the control, which is all it was for.
@@ -1688,62 +1756,62 @@ export default function ChatView({ workspace }) {
                                     }, sx: hintFullScreen
                                         ? {
                                             /*
-                                                Colour and opacity, never geometry.
-                  
-                                                The colour is the theme's own `primary` — the
-                                                same brand the page around this workspace is
-                                                already using — because a grey icon in a row of
-                                                grey icons cannot be picked out however hard it
-                                                fades. Colour is what makes it findable; the
-                                                fade is what makes it look like it is asking.
-                  
-                                                It never fades to nothing: a control that
-                                                vanishes and returns reads as a rendering fault,
-                                                not an invitation. And nothing here moves or
-                                                resizes, so the header does not reflow and the
-                                                controls beside it stay where a reader last saw
-                                                them.
-                                              */
+                                              Colour and opacity, never geometry.
+                
+                                              The colour is the theme's own `primary` — the
+                                              same brand the page around this workspace is
+                                              already using — because a grey icon in a row of
+                                              grey icons cannot be picked out however hard it
+                                              fades. Colour is what makes it findable; the
+                                              fade is what makes it look like it is asking.
+                
+                                              It never fades to nothing: a control that
+                                              vanishes and returns reads as a rendering fault,
+                                              not an invitation. And nothing here moves or
+                                              resizes, so the header does not reflow and the
+                                              controls beside it stay where a reader last saw
+                                              them.
+                                            */
                                             '@keyframes dla-fullscreen-hint': {
                                                 '0%, 100%': { opacity: 1 },
                                                 '50%': { opacity: 0.4 },
                                             },
                                             /* `&&` doubles the specificity, because Primer
-                                                 ships Button as a CSS module and
-                                                 `prc-Button-*` outranks a single generated
-                                                 class — without it the keyframes register and
-                                                 the button sits there at `animation: none`.
-                                                 The colour needs the same treatment: an
-                                                 invisible IconButton sets `color` itself.
-                  
-                                                 And no `:focus` or `:hover` clause to stop it:
-                                                 anything that matches the button while it is
-                                                 being pointed at would cancel the pointing —
-                                                 which is exactly how the first version of this
-                                                 silently did nothing. It ends when the reader
-                                                 takes the offer, or arrives without it. */
+                                               ships Button as a CSS module and
+                                               `prc-Button-*` outranks a single generated
+                                               class — without it the keyframes register and
+                                               the button sits there at `animation: none`.
+                                               The colour needs the same treatment: an
+                                               invisible IconButton sets `color` itself.
+                
+                                               And no `:focus` or `:hover` clause to stop it:
+                                               anything that matches the button while it is
+                                               being pointed at would cancel the pointing —
+                                               which is exactly how the first version of this
+                                               silently did nothing. It ends when the reader
+                                               takes the offer, or arrives without it. */
                                             '&&': {
                                                 /*
-                                                    The brand on the box, not on the glyph.
-                    
-                                                    Painting the icon `palette.primary` was the
-                                                    obvious reading and it is measurably
-                                                    backwards: in the theme this workspace ships
-                                                    on, `primary` is #FFC107, which sits at 1.55
-                                                    contrast against the header — where the
-                                                    icon's ordinary olive sits at 5.07. Recolouring
-                                                    the stroke made the control roughly three
-                                                    times harder to see, and at the bottom of the
-                                                    fade it was 1.2 and simply gone.
-                    
-                                                    A ring and a wash carry the same colour on a
-                                                    far larger area, and they do it without asking
-                                                    the glyph to be legible in a brand colour that
-                                                    changes with every theme — this palette has
-                                                    six, from a dark teal to this amber, and a
-                                                    rule that works for one fails for another. The
-                                                    glyph keeps the colour it can be read in.
-                                                  */
+                                                  The brand on the box, not on the glyph.
+                  
+                                                  Painting the icon `palette.primary` was the
+                                                  obvious reading and it is measurably
+                                                  backwards: in the theme this workspace ships
+                                                  on, `primary` is #FFC107, which sits at 1.55
+                                                  contrast against the header — where the
+                                                  icon's ordinary olive sits at 5.07. Recolouring
+                                                  the stroke made the control roughly three
+                                                  times harder to see, and at the bottom of the
+                                                  fade it was 1.2 and simply gone.
+                  
+                                                  A ring and a wash carry the same colour on a
+                                                  far larger area, and they do it without asking
+                                                  the glyph to be legible in a brand colour that
+                                                  changes with every theme — this palette has
+                                                  six, from a dark teal to this amber, and a
+                                                  rule that works for one fails for another. The
+                                                  glyph keeps the colour it can be read in.
+                                                */
                                                 bg: `color-mix(in srgb, ${palette.primary} 16%, transparent)`,
                                                 boxShadow: `inset 0 0 0 1.5px ${palette.primary}`,
                                                 animation: `dla-fullscreen-hint ${FULLSCREEN_HINT_PERIOD_MS}ms ease-in-out infinite`,
@@ -1761,18 +1829,18 @@ export default function ChatView({ workspace }) {
                         // second one: two input boxes on one screen is one too many.
                         showInput: false, onSendReady: handleSendReady, 
                         /*
-                            The notebook tools' results, drawn into the transcript — the
-                            chat's own machinery, switched on only while no editor is on
-                            screen: the hidden notebook is where the agent works, and the
-                            transcript is then the one place the reader can see what a
-                            tool did. With an editor open the change is visible where it
-                            happened, and the default tool row is enough.
-                          */
+                          The notebook tools' results, drawn into the transcript — the
+                          chat's own machinery, switched on only while no editor is on
+                          screen: the hidden notebook is where the agent works, and the
+                          transcript is then the one place the reader can see what a
+                          tool did. With an editor open the change is visible where it
+                          happened, and the default tool row is enough.
+                        */
                         notebookToolSurfacesId: active ? undefined : workspace.surfaceId, 
                         // A host example's own tool-result renderer, when it feeds one
                         // through the extras channel — the A2UI examples draw their
                         // surface here. Wins over the notebook surfaces in ChatBase.
-                        renderToolResult: chatExtras.renderToolResult, showTurnFooter: chatExtras.showTokenUsage ?? config?.showTokenUsage ?? true, onContextSnapshot: handleContextSnapshot, onLoadingChange: handleLoadingChange, onItemsChange: handleMessagesChange, onDisplayItemsChange: handleDisplayItemsChange, enableStreaming: true }) }), besideChat && !promptHidden ? prompt : null] }) }));
+                        renderToolResult: chatExtras.renderToolResult, showTurnFooter: chatExtras.showTokenUsage ?? config?.showTokenUsage ?? true, onContextSnapshot: handleContextSnapshot, onLoadingChange: handleLoadingChange, onItemsChange: handleMessagesChange, onDisplayItemsChange: handleDisplayItemsChange, enableStreaming: true }, chatThread?.id)) }), besideChat && !promptHidden ? prompt : null] }) }));
     // Off when the host asked for the menu alone: the composer's suggestions
     // control carries the same openers (`suggestions` above).
     const chipsEl = config?.suggestionLabels !== false && chatSuggestions.length > 0 ? (_jsx(Box, { "aria-label": chatText.suggestedPrompts, sx: { display: 'flex', flexWrap: 'wrap', gap: 2, px: 2, pb: '6px' }, children: chatSuggestions.map(item => (_jsx(Box, { as: "button", type: "button", 

package/lib/loop/shell/LoopWorkspace.d.ts

@@ -21,7 +21,7 @@
  */
 import type { JSX } from 'react';
 import type { ReactNode } from 'react';
-import { type PluginRef, type ReactorPlatform } from '@datalayer/reactor';
+import { type PlatformInput, type PluginRef, type ReactorPlatform } from '@datalayer/reactor';
 import { type LoopWorkspaceContext, type SandboxSnapshot } from '../core';
 export type LoopWorkspaceProps = {
     /** Server backing this session. */
@@ -125,6 +125,6 @@ export type LoopWorkspaceProps = {
      */
     sidebarRail?: boolean;
 };
-/** Build the platform for a set of plugins. */
-export declare function buildLoopReactor(extensions: PluginRef[]): ReactorPlatform;
+/** Build the platform for a set of plugins, and of extensions grouping them. */
+export declare function buildLoopReactor(extensions: PlatformInput[]): ReactorPlatform;
 export declare function LoopWorkspace(props: LoopWorkspaceProps): JSX.Element;

package/lib/loop/shell/LoopWorkspace.js

@@ -8,7 +8,7 @@ import { LoopCommand, LoopSlots, LoopViewType, canOpenView, createPromptChannel,
 import { SIDEBAR_WIDTH } from '../plugins/plugins-panel';
 import { ViewSwitcher } from './ViewSwitcher';
 import { SidebarRail } from './SidebarRail';
-/** Build the platform for a set of plugins. */
+/** Build the platform for a set of plugins, and of extensions grouping them. */
 export function buildLoopReactor(extensions) {
     return buildReactorFromPlugins(extensions);
 }

package/lib/runtimes/__tests__/fixtures/accounting-agent-card.json

@@ -16,7 +16,11 @@
       "description": "Answers requests for financial reports, such as open invoices, aged balances, a trial balance or a customer's ledger, from the Odoo books, which it only reads.",
       "tags": ["example", "accounting", "finance", "odoo", "a2a", "team"],
       "inputModes": ["text/plain"],
-      "outputModes": ["text/markdown", "application/x-ipynb+json"],
+      "outputModes": [
+        "text/markdown",
+        "application/x-ipynb+json",
+        "application/json+a2ui"
+      ],
       "examples": [
         "List the customer invoices that are still open, with the total due.",
         "Give the aged receivables as of today, by customer.",
@@ -25,7 +29,11 @@
     }
   ],
   "defaultInputModes": ["text/plain"],
-  "defaultOutputModes": ["text/markdown", "application/x-ipynb+json"],
+  "defaultOutputModes": [
+    "text/markdown",
+    "application/x-ipynb+json",
+    "application/json+a2ui"
+  ],
   "capabilities": {
     "streaming": true,
     "pushNotifications": false,

package/lib/runtimes/actions.js

@@ -49,6 +49,20 @@ export async function createRuntime(options) {
         throw new Error(`Invalid runtime creditsLimit for environment ${options.environmentName}. ` +
             'A number of zero or more is required.');
     }
+    /*
+     * An application's launch carries its Appspec (STUDIO R-19), as
+     * `RuntimesClient.create` does in Python: the Operator hands it to the
+     * companion, which gives the runtime the secrets its connections declare
+     * before its agent is made. Refused here, before any request, as the
+     * Operator would refuse it (422).
+     */
+    if (options.deploymentUid && !options.appUid) {
+        throw new Error(`Deployment ${options.deploymentUid} is named without its application: give appUid.`);
+    }
+    if (options.appUid && !options.appSpec) {
+        throw new Error(`Application ${options.appUid} is launched without its Appspec: give appSpec, ` +
+            'so its runtime is given the secrets its connections declare.');
+    }
     /*
      * `environment: {name, version}` — and the version is ADDITIVE.
      *
@@ -75,6 +89,15 @@ export async function createRuntime(options) {
     if (options.snapshot) {
         body['from'] = options.snapshot;
     }
+    if (options.appUid) {
+        body['app_uid'] = options.appUid;
+    }
+    if (options.deploymentUid) {
+        body['deployment_uid'] = options.deploymentUid;
+    }
+    if (options.appSpec) {
+        body['app_spec'] = options.appSpec;
+    }
     const data = await requestDatalayerAPI({
         url: runtimesUrl(runtimesStore.getState().runtimesUrl),
         method: 'POST',

package/lib/runtimes/apis.d.ts

@@ -51,6 +51,24 @@ export interface IRuntimeOptions {
      * Kernel snapshot to restore
      */
     snapshot?: string;
+    /**
+     * The Appspec of the application the runtime is launched for (STUDIO
+     * R-19), as its file holds it. The Operator hands it to the runtime's
+     * companion, which gives the runtime the secrets its connections declare
+     * before its agent is made. An application's launch carries it:
+     * `appUid` without it is refused.
+     */
+    appSpec?: Record<string, unknown>;
+    /**
+     * The saved application the runtime runs for (LOOP R-09): written on its
+     * reservation, so its running time is counted per application.
+     */
+    appUid?: string;
+    /**
+     * The deployment of that application it runs for. A deployment is always
+     * of an application: one named without `appUid` is refused.
+     */
+    deploymentUid?: string;
 }
 /**
  * Interface for the Environments Manager

package/lib/runtimes/browser/a2aPeer.d.ts

@@ -85,6 +85,21 @@ export type A2APeerToolStep = {
 export declare const TEXT_MEDIA_TYPES: readonly string[];
 /** A Jupyter notebook, as A2A carries it. */
 export declare const NOTEBOOK_MEDIA_TYPE = "application/x-ipynb+json";
+/**
+ * Components of the catalog, as A2A carries them: one A2UI surface per
+ * artifact (`{surfaceId, catalogId, title, messages}`), A2UI's media type.
+ */
+export declare const A2UI_MEDIA_TYPE = "application/json+a2ui";
+/**
+ * A button pressed on an answer's surface, sent back with the reader's turn:
+ * its name and what choosing it does (`payload.does`). The runtime reads it
+ * from the message's metadata (`loop.action`): one that does more than read
+ * is refused to a visitor in a sentence, before any model runs.
+ */
+export type A2APeerAction = {
+    name: string;
+    payload: Record<string, unknown>;
+};
 /**
  * What a peer gave besides words: one part of an artifact, by its media type.
  *
@@ -135,8 +150,8 @@ export declare function artifactsOf(artifact: {
     name?: string;
     parts?: Part[];
 } | undefined): A2APeerArtifact[];
-/** A user's message of one text part, as the SDK's 1.x types write it. */
-export declare function textMessage(text: string): Message;
+/** A user's message of one text part, as the SDK's 1.x types write it; a pressed button's action in its metadata. */
+export declare function textMessage(text: string, action?: A2APeerAction): Message;
 /**
  * What a working status says while the peer works: in a few words, and the
  * tool step when it is one.
@@ -159,6 +174,8 @@ export type AskA2APeerOptions = {
      * the peer answers in words alone.
      */
     accept?: readonly string[];
+    /** The button pressed on one of its answers' surfaces, when this request is one. */
+    action?: A2APeerAction;
 };
 /**
  * Ask a peer once, streaming the task, and return its answer.

package/lib/runtimes/browser/a2aPeer.js

@@ -92,9 +92,15 @@ export const TEXT_MEDIA_TYPES = [
 ];
 /** A Jupyter notebook, as A2A carries it. */
 export const NOTEBOOK_MEDIA_TYPE = 'application/x-ipynb+json';
+/**
+ * Components of the catalog, as A2A carries them: one A2UI surface per
+ * artifact (`{surfaceId, catalogId, title, messages}`), A2UI's media type.
+ */
+export const A2UI_MEDIA_TYPE = 'application/json+a2ui';
 /** What a format is, in words, for a model reading a tool's description. */
 const FORMAT_NAMES = {
     [NOTEBOOK_MEDIA_TYPE]: 'a Jupyter notebook',
+    [A2UI_MEDIA_TYPE]: 'components drawn for the person: the sources as cards, a table, a chart, a choice of buttons',
 };
 /** The text of a message's or an artifact's parts. */
 export function textOf(parts) {
@@ -131,8 +137,8 @@ export function artifactsOf(artifact) {
     }
     return found;
 }
-/** A user's message of one text part, as the SDK's 1.x types write it. */
-export function textMessage(text) {
+/** A user's message of one text part, as the SDK's 1.x types write it; a pressed button's action in its metadata. */
+export function textMessage(text, action) {
     return {
         messageId: globalThis.crypto.randomUUID(),
         contextId: '',
@@ -146,7 +152,7 @@ export function textMessage(text) {
                 mediaType: '',
             },
         ],
-        metadata: undefined,
+        metadata: action ? { loop: { action } } : undefined,
         extensions: [],
         referenceTaskIds: [],
     };
@@ -205,14 +211,14 @@ const ENDED_BADLY = {
  * completed is thrown, with what the peer said.
  */
 export async function askA2APeer(peer, request, options = {}) {
-    const { signal, onEvent, accept } = options;
+    const { signal, onEvent, accept, action } = options;
     onEvent?.({
         phase: 'asked',
         request,
         ...(accept?.length ? { accept: [...accept] } : {}),
     });
     try {
-        return await streamTask(peer, request, signal, onEvent, accept);
+        return await streamTask(peer, request, signal, onEvent, accept, action);
     }
     catch (reason) {
         const error = reason instanceof Error ? reason.message : String(reason);
@@ -220,7 +226,7 @@ export async function askA2APeer(peer, request, options = {}) {
         throw reason;
     }
 }
-async function streamTask(peer, request, signal, onEvent, accept) {
+async function streamTask(peer, request, signal, onEvent, accept, action) {
     const texts = new Map();
     // What it gave besides words, by artifact: the last chunk says it whole.
     const given = new Map();
@@ -229,7 +235,7 @@ async function streamTask(peer, request, signal, onEvent, accept) {
     let ended;
     const stream = peer.client.sendMessageStream({
         tenant: '',
-        message: textMessage(request),
+        message: textMessage(request, action),
         configuration: accept?.length
             ? {
                 acceptedOutputModes: [...accept],