@datalayer/agent-runtimes 1.3.69 → 1.3.71

package/lib/chat/notebook/EphemeralNotebook.js

@@ -71,7 +71,15 @@ export function EphemeralNotebook({ notebookId, runtimeName, runtimeOverride, se
     // deliberately NO fallback to "first running" or `runtimes[0]`: the ephemeral
     // notebook must bind to exactly the runtime assigned to this agent, or to
     // none at all (straight path).
-    const { runtimes, refetchRuntimes } = useAgentsRuntimes();
+    //
+    // Asked only when there is a pod to look up: a host that hands its own
+    // manager (a browser sandbox) or an endpoint has nothing to find there,
+    // and a page that never needs the runtimes list does not poll it.
+    const { runtimes, refetchRuntimes } = useAgentsRuntimes(undefined, {
+        enabled: Boolean(String(runtimeName || '').trim()) &&
+            !externalServiceManager &&
+            !String(runtimeOverride?.baseUrl || '').trim(),
+    });
     const resolvedRuntime = useMemo(() => {
         const preferredRuntime = String(runtimeName || '').trim();
         if (!preferredRuntime) {

package/lib/components/teams/TeamNotebook.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A notebook a member of the team gave, open in the page to run.
+ *
+ * What a peer gives besides words arrives as an artifact by media type
+ * (`a2aPeer`'s {@link A2APeerArtifact}); a Jupyter notebook
+ * (`application/x-ipynb+json`) is shown here, as the loop's notebook view
+ * shows one: jupyter-react's notebook on the browser sandbox, a Pyodide
+ * kernel in the page, where the reader runs cells, edits them and adds more.
+ * It runs in the reader's browser and costs nothing elsewhere.
+ *
+ * This module is light: the notebook, JupyterLab and Pyodide are in
+ * `TeamNotebookView`, imported only once a notebook is drawn, so that a page
+ * that shows a team — the landing's home page — loads none of them until a
+ * notebook arrives.
+ *
+ * @module components/teams/TeamNotebook
+ */
+import type { JSX } from 'react';
+import type { A2APeerArtifact } from '../../runtimes/browser/a2aPeer';
+export type TeamNotebookProps = {
+    /** The notebook, as the peer gave it: its `data` is the nbformat document. */
+    notebook: A2APeerArtifact;
+    /** What the section is called: `Accounting's notebook`. */
+    title: string;
+    /** How tall the notebook is, in pixels. */
+    height?: number;
+};
+/** The file a notebook is saved as: the peer's name for it, else its name. */
+export declare function notebookFileName(notebook: A2APeerArtifact): string;
+/** A notebook a member of the team gave, under its title, to run in the page. */
+export declare function TeamNotebook({ notebook, title, height, }: TeamNotebookProps): JSX.Element;
+export default TeamNotebook;

package/lib/components/teams/TeamNotebook.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense, lazy } from 'react';
+import { Heading, Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+/** The view itself: jupyter-react, JupyterLab and Pyodide, loaded when a notebook is drawn. */
+const TeamNotebookView = lazy(() => import('./TeamNotebookView'));
+/** The file a notebook is saved as: the peer's name for it, else its name. */
+export function notebookFileName(notebook) {
+    if (notebook.filename) {
+        return notebook.filename;
+    }
+    const stem = notebook.name
+        .replace(/[^A-Za-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase() || 'notebook';
+    return `${stem}.ipynb`;
+}
+/** A notebook a member of the team gave, under its title, to run in the page. */
+export function TeamNotebook({ notebook, title, height = 560, }) {
+    return (_jsxs(Box, { as: "section", "aria-label": title, "data-team-notebook": "", sx: { display: 'flex', flexDirection: 'column', gap: 2, minWidth: 0 }, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, m: 0 }, children: title }), _jsx(Suspense, { fallback: _jsx(Text, { as: "p", sx: { color: 'fg.muted', fontSize: 1, m: 0 }, children: "Opening the notebook\u2026" }), children: _jsx(TeamNotebookView, { notebook: notebook, fileName: notebookFileName(notebook), height: height }) })] }));
+}
+export default TeamNotebook;

package/lib/components/teams/TeamNotebookView.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The notebook a member of the team gave, on the browser sandbox.
+ *
+ * What the loop's notebook view does (`loop/plugins/notebook/NotebookView`),
+ * for a notebook that arrived over A2A: the browser sandbox
+ * (`createBrowserSandboxService`, a JupyterLite Pyodide kernel in the page)
+ * is started, and `EphemeralNotebook` is bound to its manager and its
+ * kernel. Nothing runs anywhere but in the reader's browser.
+ *
+ * Loaded by `TeamNotebook` when a notebook is drawn, never before.
+ *
+ * @module components/teams/TeamNotebookView
+ */
+import type { JSX } from 'react';
+import type { A2APeerArtifact } from '../../runtimes/browser/a2aPeer';
+export type TeamNotebookViewProps = {
+    notebook: A2APeerArtifact;
+    /** The file it is saved as. */
+    fileName: string;
+    height: number;
+};
+export declare function TeamNotebookView({ notebook, fileName, height, }: TeamNotebookViewProps): JSX.Element;
+export default TeamNotebookView;

package/lib/components/teams/TeamNotebookView.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { DownloadIcon } from '@primer/octicons-react';
+import { Button, Flash, Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { useSignalValue } from '@datalayer/reactor/react';
+import { notebookStore } from '@datalayer/jupyter-react';
+import { EphemeralNotebook } from '../../chat/notebook/EphemeralNotebook';
+import { createBrowserSandboxService } from '../../loop/plugins/agents/browserService';
+/** Each notebook drawn has its own id in jupyter-react's store. */
+let drawn = 0;
+/** Save a notebook as an `.ipynb` file, as Jupyter writes one. */
+function download(content, fileName) {
+    const text = `${JSON.stringify(content, null, 1)}\n`;
+    const url = URL.createObjectURL(new Blob([text], { type: 'application/x-ipynb+json' }));
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = fileName;
+    link.click();
+    URL.revokeObjectURL(url);
+}
+export function TeamNotebookView({ notebook, fileName, height, }) {
+    // One sandbox for the view: a notebook that replaces another runs on the
+    // same kernel, already started.
+    const service = useMemo(() => createBrowserSandboxService(), []);
+    const snapshot = useSignalValue(service.snapshot);
+    const [failed, setFailed] = useState(null);
+    // The notebook's store needs a query client; this view asks it nothing.
+    const queries = useMemo(() => new QueryClient(), []);
+    useEffect(() => {
+        const disconnect = service.connect();
+        return disconnect;
+    }, [service]);
+    useEffect(() => {
+        if (snapshot.state === 'error') {
+            setFailed('Python could not start in this browser, so the notebook cannot run here. Download it to open it in Jupyter.');
+        }
+    }, [snapshot.state]);
+    // A new id for each notebook given: the notebook component keeps the
+    // document it is first handed.
+    const notebookId = useMemo(() => {
+        drawn += 1;
+        return `team-notebook-${drawn}`;
+    }, [notebook]);
+    const content = notebook.data;
+    // Handed once: the component edits it in place.
+    const opening = useMemo(() => JSON.parse(JSON.stringify(content)), [content]);
+    const save = () => {
+        // What the reader has made of it, when it is open; as it came otherwise.
+        const model = notebookStore
+            .getState()
+            .selectNotebook(notebookId)
+            ?.model?.toJSON();
+        download(model ?? content, fileName);
+    };
+    const manager = service.getServiceManager() ??
+        undefined;
+    const running = snapshot.state === 'running' && manager !== undefined;
+    return (_jsx(QueryClientProvider, { client: queries, children: _jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsxs(Box, { sx: {
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: 2,
+                        flexWrap: 'wrap',
+                    }, children: [_jsx(Text, { sx: { color: 'fg.muted', fontSize: 1, flex: '1 1 auto' }, children: running
+                                ? 'It runs in your browser, with Python (Pyodide): run its cells, change them, add your own.'
+                                : 'Starting Python in your browser…' }), _jsx(Button, { size: "small", leadingVisual: DownloadIcon, onClick: save, "data-team-notebook-download": "", children: "Download .ipynb" })] }), failed && _jsx(Flash, { variant: "warning", children: failed }), _jsx(Box, { "data-team-notebook-sheet": "", sx: {
+                        position: 'relative',
+                        height,
+                        minHeight: 0,
+                        border: '1px solid',
+                        borderColor: 'border.default',
+                        borderRadius: 2,
+                        overflow: 'hidden',
+                        // As the loop's notebook view pins them: Lumino sizes these
+                        // itself, and a resize it never hears of leaves them at zero.
+                        '& .jp-NotebookPanel': {
+                            height: '100% !important',
+                            minHeight: 0,
+                        },
+                        '& .dla-Box-Notebook': {
+                            display: 'flex',
+                            flexDirection: 'column',
+                            minHeight: 0,
+                        },
+                    }, children: running && (_jsx(EphemeralNotebook, { notebookId: notebookId, nbformat: opening, inheritTheme: true, serviceManager: manager, 
+                        // Join the sandbox's kernel rather than starting a rival one.
+                        kernelId: snapshot.kernelId }, notebookId)) })] }) }));
+}
+export default TeamNotebookView;

package/lib/components/teams/index.d.ts

@@ -10,3 +10,4 @@ export * from './a2aTeamFlow';
 export * from './teamConnections';
 export * from './useA2ATeam';
 export * from './A2ATeamGraph';
+export * from './TeamNotebook';

package/lib/components/teams/index.js

@@ -14,3 +14,4 @@ export * from './a2aTeamFlow';
 export * from './teamConnections';
 export * from './useA2ATeam';
 export * from './A2ATeamGraph';
+export * from './TeamNotebook';

package/lib/components/teams/useA2ATeam.d.ts

@@ -1,6 +1,6 @@
 import type { AssistantState } from '../../chat/assistant/state';
 import { type BrowserModelOptions } from '../../runtimes/browser/model';
-import { type A2APeer } from '../../runtimes/browser/a2aPeer';
+import { type A2APeer, type A2APeerArtifact } from '../../runtimes/browser/a2aPeer';
 import type { AppSpec } from '../../types/agentspecs';
 import { type A2ATeamCall, type A2ATeamConnection, type A2ATeamFlow } from './a2aTeamFlow';
 /** What one member's character does: its state, its balloon, and whether it was sent away. */
@@ -18,6 +18,12 @@ export type A2ATeamTurn = {
     role: 'user' | 'assistant';
     text: string;
 };
+/** What a page that shows notebooks accepts: a notebook, and words in Markdown. */
+export declare const NOTEBOOK_AND_WORDS: readonly string[];
+/** What an exchange line calls what the peer gave: its words, and each of its artifacts. */
+export declare function answeredLine(artifacts: A2APeerArtifact[]): string;
+/** The latest notebook among what a peer gave, or none. */
+export declare function notebookAmong(artifacts: A2APeerArtifact[]): A2APeerArtifact | null;
 /** A line short enough for a balloon. */
 export declare function balloonLine(text: string, length?: number): string;
 export type UseA2ATeamOptions = {
@@ -35,6 +41,11 @@ export type UseA2ATeamOptions = {
     maxSteps?: number;
     /** The peer's connections (`teamConnectionsOf(peerApp)`): the calls to them are kept. */
     peerConnections?: A2ATeamConnection[];
+    /**
+     * The media types the page accepts from the peer (`acceptedOutputModes`):
+     * words, and the formats it can show, such as a notebook. Unsaid, words alone.
+     */
+    accept?: readonly string[];
 };
 export type A2ATeam = {
     entryPersona: A2ATeamPersona;
@@ -46,6 +57,10 @@ export type A2ATeam = {
     exchange: string[];
     /** The peer's last answer, as it gave it. */
     report: string | null;
+    /** What the peer gave besides words with its last answer, by media type. */
+    artifacts: A2APeerArtifact[];
+    /** The latest notebook the peer gave, kept until another one comes. */
+    notebook: A2APeerArtifact | null;
     /** Which way the link carries a message now. */
     flow: A2ATeamFlow;
     /** The tool calls the peer's connections are answering now. */

package/lib/components/teams/useA2ATeam.js

@@ -13,7 +13,10 @@
  * {@link a2aPeerTool}. What each of them does is kept as a persona — the
  * state its character acts and what its balloon says — and the exchange
  * between them as a log, the peer's last answer as the report, and the way
- * the link carries a message as the flow ({@link flowAfter}). The tools the
+ * the link carries a message as the flow ({@link flowAfter}). What the peer
+ * gives besides words — the formats the page accepts (`accept`), such as a
+ * Jupyter notebook — is kept as its artifacts, and its latest notebook kept
+ * until another one comes ({@link A2ATeam.notebook}). The tools the
  * peer calls on its connections (its MCP servers), told over A2A as it calls
  * them, are kept as the calls running now ({@link callsAfter}).
  *
@@ -24,7 +27,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { stepCountIs, ToolLoopAgent } from 'ai';
 import { createBrowserModel, } from '../../runtimes/browser/model';
-import { a2aPeerTool, } from '../../runtimes/browser/a2aPeer';
+import { a2aPeerTool, NOTEBOOK_MEDIA_TYPE, } from '../../runtimes/browser/a2aPeer';
 import { callsAfter, flowAfter, pruneCalls, } from './a2aTeamFlow';
 const NO_CONNECTIONS = [];
 export const AT_REST = {
@@ -32,6 +35,24 @@ export const AT_REST = {
     insist: false,
     away: false,
 };
+/** What a page that shows notebooks accepts: a notebook, and words in Markdown. */
+export const NOTEBOOK_AND_WORDS = [
+    NOTEBOOK_MEDIA_TYPE,
+    'text/markdown',
+];
+/** What an exchange line calls what the peer gave: its words, and each of its artifacts. */
+export function answeredLine(artifacts) {
+    const besides = artifacts.map(artifact => artifact.mediaType === NOTEBOOK_MEDIA_TYPE
+        ? `a notebook, ${artifact.name}`
+        : artifact.name);
+    return besides.length ? `the report and ${besides.join(', ')}` : 'the report';
+}
+/** The latest notebook among what a peer gave, or none. */
+export function notebookAmong(artifacts) {
+    return ([...artifacts]
+        .reverse()
+        .find(artifact => artifact.mediaType === NOTEBOOK_MEDIA_TYPE) ?? null);
+}
 /** A line short enough for a balloon. */
 export function balloonLine(text, length = 120) {
     const flat = text.replace(/\s+/g, ' ').trim();
@@ -40,6 +61,10 @@ export function balloonLine(text, length = 120) {
 /** Run a team of two over A2A in the page. */
 export function useA2ATeam(options) {
     const { entry, peerApp, peer, inference, maxSteps = 6, peerConnections = NO_CONNECTIONS, } = options;
+    // By what it names, so that a page passing a new array of the same media
+    // types does not make the agent again.
+    const acceptKey = options.accept?.join('\n');
+    const accept = useMemo(() => (acceptKey ? acceptKey.split('\n') : undefined), [acceptKey]);
     const askTool = options.askTool ?? `ask_${peerApp.id.replace(/-/g, '_')}`;
     const [entryPersona, setEntryPersona] = useState(() => ({
         ...AT_REST,
@@ -50,6 +75,8 @@ export function useA2ATeam(options) {
     const [peerPersona, setPeerPersona] = useState(AT_REST);
     const [turns, setTurns] = useState([]);
     const [report, setReport] = useState(null);
+    const [artifacts, setArtifacts] = useState([]);
+    const [notebook, setNotebook] = useState(null);
     const [exchange, setExchange] = useState([]);
     const [flow, setFlow] = useState('still');
     const [calls, setCalls] = useState([]);
@@ -105,9 +132,14 @@ export function useA2ATeam(options) {
         else if (event.phase === 'answered') {
             setExchange(prev => [
                 ...prev,
-                `${peerApp.name} → ${entry.name}: the report`,
+                `${peerApp.name} → ${entry.name}: ${answeredLine(event.artifacts)}`,
             ]);
             setReport(event.answer);
+            setArtifacts(event.artifacts);
+            const given = notebookAmong(event.artifacts);
+            if (given) {
+                setNotebook(given);
+            }
             setPeerPersona(prev => ({
                 ...prev,
                 state: 'speaking',
@@ -139,10 +171,12 @@ export function useA2ATeam(options) {
                 model: entry.model || undefined,
             }),
             instructions: entry.instructions,
-            tools: { [askTool]: a2aPeerTool({ peer, onEvent: onPeerEvent }) },
+            tools: {
+                [askTool]: a2aPeerTool({ peer, onEvent: onPeerEvent, accept }),
+            },
             stopWhen: stepCountIs(maxSteps),
         });
-    }, [peer, inference, onPeerEvent, entry, askTool, maxSteps]);
+    }, [peer, inference, onPeerEvent, entry, askTool, maxSteps, accept]);
     const send = useCallback(async (text) => {
         const asked = text.trim();
         if (!asked || !agent || busy) {
@@ -150,6 +184,7 @@ export function useA2ATeam(options) {
         }
         setBusy(true);
         setReport(null);
+        setArtifacts([]);
         setExchange([]);
         setTurns(prev => [...prev, { role: 'user', text: asked }]);
         setEntryPersona({
@@ -250,6 +285,8 @@ export function useA2ATeam(options) {
         turns,
         exchange,
         report,
+        artifacts,
+        notebook,
         flow,
         calls,
         busy,

package/lib/examples/AgentA2ATeamExample.d.ts

@@ -17,6 +17,12 @@
  * the tool's name on it. Then the report appears. The page's own state is `useA2ATeam`'s, which the landing's home
  * page runs too.
  *
+ * Sales accepts a Jupyter notebook from Accounting besides its words
+ * (`acceptedOutputModes`, `NOTEBOOK_AND_WORDS`). When Accounting gives one,
+ * it opens under the conversation in place of the report, on the browser
+ * sandbox — a Pyodide kernel in this page — to run, change and download
+ * (`TeamNotebook`, loaded only then).
+ *
  * Where Accounting is: `VITE_A2A_ACCOUNTING_URL`, else the examples' local
  * server (`…:8765/api/v1/a2a/agents/accounting`), which answers this machine
  * without a key. A cloud runtime needs a key granted to its route:

package/lib/examples/AgentA2ATeamExample.js

@@ -1,4 +1,4 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { Button, Flash, Heading, Text, Textarea } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
@@ -10,7 +10,7 @@ import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { useBrowserInference } from '../hooks/useBrowserInference';
 import { readJwtClaims, tokenLifetimeMs, useAnonymousSessionStore, } from '../runtimes/browser/anonymousToken';
 import { connectA2APeer } from '../runtimes/browser/a2aPeer';
-import { A2ATeamGraph, teamConnectionsOf, useA2ATeam, } from '../components/teams';
+import { A2ATeamGraph, NOTEBOOK_AND_WORDS, TeamNotebook, teamConnectionsOf, useA2ATeam, } from '../components/teams';
 import { ACCOUNTING_APP_0_0_1, SALES_APP_0_0_1 } from '../specs/apps';
 import { SALES_AND_ACCOUNTING_TEAM_SPEC_0_0_1 } from '../specs/teams/teams';
 const TEAM = SALES_AND_ACCOUNTING_TEAM_SPEC_0_0_1;
@@ -70,6 +70,8 @@ function AgentA2ATeam() {
         inference,
         askTool: 'ask_accounting',
         peerConnections: ACCOUNTING_CONNECTIONS,
+        // Its words, and a notebook to run here when it gives one.
+        accept: NOTEBOOK_AND_WORDS,
     });
     const send = (text) => {
         setDraft('');
@@ -120,13 +122,13 @@ function AgentA2ATeam() {
                                         mb: 2,
                                         borderRadius: 2,
                                         bg: turn.role === 'user' ? 'accent.subtle' : 'canvas.subtle',
-                                    }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', display: 'block' }, children: turn.role === 'user' ? 'You' : SALES.name }), _jsx(Streamdown, { children: turn.text })] }, index))) })] }), _jsxs(Box, { sx: { flex: '1 1 360px', minWidth: 0 }, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: "The exchange" }), _jsx(Box, { as: "ol", sx: { pl: 3, color: 'fg.muted', fontSize: 1 }, "data-team-exchange": "", children: team.exchange.length === 0 ? (_jsx(Text, { as: "li", children: "Nothing asked yet." })) : (team.exchange.map((step, index) => (_jsx(Text, { as: "li", children: step }, index)))) }), _jsx(Heading, { as: "h3", sx: { fontSize: 2, mt: 3, mb: 2 }, children: "The report" }), _jsx(Box, { sx: {
-                                    p: 3,
-                                    border: '1px solid',
-                                    borderColor: 'border.default',
-                                    borderRadius: 2,
-                                    minHeight: 120,
-                                }, "data-team-report": "", children: team.report ? (_jsx(Streamdown, { children: team.report })) : (_jsx(Text, { sx: { color: 'fg.muted' }, children: "The report Accounting returns appears here, as it returned it." })) })] })] })] }));
+                                    }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', display: 'block' }, children: turn.role === 'user' ? 'You' : SALES.name }), _jsx(Streamdown, { children: turn.text })] }, index))) })] }), _jsxs(Box, { sx: { flex: '1 1 360px', minWidth: 0 }, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: "The exchange" }), _jsx(Box, { as: "ol", sx: { pl: 3, color: 'fg.muted', fontSize: 1 }, "data-team-exchange": "", children: team.exchange.length === 0 ? (_jsx(Text, { as: "li", children: "Nothing asked yet." })) : (team.exchange.map((step, index) => (_jsx(Text, { as: "li", children: step }, index)))) }), !team.notebook && (_jsxs(_Fragment, { children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mt: 3, mb: 2 }, children: "The report" }), _jsx(Box, { sx: {
+                                            p: 3,
+                                            border: '1px solid',
+                                            borderColor: 'border.default',
+                                            borderRadius: 2,
+                                            minHeight: 120,
+                                        }, "data-team-report": "", children: team.report ? (_jsx(Streamdown, { children: team.report })) : (_jsx(Text, { sx: { color: 'fg.muted' }, children: "The report Accounting returns appears here, as it returned it, or as a notebook to run when it gives one." })) })] }))] })] }), team.notebook && (_jsx(Box, { sx: { mt: 3 }, children: _jsx(TeamNotebook, { notebook: team.notebook, title: `${ACCOUNTING.name}\u2019s notebook` }) }))] }));
 }
 export function AgentA2ATeamExample() {
     return (_jsx(ThemedProvider, { children: _jsx(AgentA2ATeam, {}) }));

package/lib/loop/apps/appspec.js

@@ -105,6 +105,7 @@ export function emptyAppspec(kind = 'chat') {
             starters: [],
             settings: [],
             components: [],
+            outputs: [],
         },
         tests: {
             readyAt: DEFAULT_READY_AT,
@@ -246,6 +247,7 @@ function parseInterface(data, kind) {
         settings: records(data.settings).map(parseSetting),
         components: texts(data.components),
         voice: parseVoice(data.voice),
+        outputs: texts(data.outputs),
     };
     if (isData(data.surface)) {
         parsed.surface = parseSurface(data.surface);
@@ -524,6 +526,8 @@ function dumpInterface(spec, kind) {
             .text('language', spec.voice.language)
             .value('where', spec.voice.where, DEFAULT_VOICE.where).data);
     }
+    // The formats its answers come in, words first, when it says any.
+    writer.list('outputs', spec.outputs ?? []);
     return writer.data;
 }
 function dumpDecision(decision) {

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

@@ -16,7 +16,7 @@
       "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/plain"],
+      "outputModes": ["text/markdown", "application/x-ipynb+json"],
       "examples": [
         "List the customer invoices that are still open, with the total due.",
         "Give the aged receivables as of today, by customer.",
@@ -24,8 +24,8 @@
       ]
     }
   ],
-  "defaultInputModes": ["application/json"],
-  "defaultOutputModes": ["application/json"],
+  "defaultInputModes": ["text/plain"],
+  "defaultOutputModes": ["text/markdown", "application/x-ipynb+json"],
   "capabilities": {
     "streaming": true,
     "pushNotifications": false,

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

@@ -14,6 +14,13 @@
  *   peer's answer in words. Each step is told to {@link A2APeerEvent} as it
  *   happens, so a page can show the exchange: asked, working, answered.
  *
+ * **Output formats.** A peer's card says the media types it answers in (its
+ * skill's `outputModes`). The asker says which it accepts with each request
+ * (`acceptedOutputModes`, {@link AskA2APeerOptions.accept}); what the peer
+ * gives besides words — a Jupyter notebook, `application/x-ipynb+json` —
+ * arrives as artifacts, one part of a media type each, and is handed over on
+ * `answered` as {@link A2APeerArtifact}s, whatever their format.
+ *
  * The key goes as a bearer token on every request, the card's too. The
  * runtime hands it to the peer's run, which then reaches the peer's
  * connections with it and with nothing broader.
@@ -59,10 +66,34 @@ export type A2APeerToolStep = {
     /** Why it failed, when it did. */
     error?: string;
 };
+/** The media types an answer in words comes in: the answer itself, never an artifact of its own. */
+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";
+/**
+ * What a peer gave besides words: one part of an artifact, by its media type.
+ *
+ * `data` is the part's structured data (a notebook is its nbformat document),
+ * a JSON file's bytes read as JSON, other bytes as they came, or a URL.
+ */
+export type A2APeerArtifact = {
+    mediaType: string;
+    /** The artifact's name: what it is, in a few words. */
+    name: string;
+    /** The file it would be saved as, when the peer named one. */
+    filename?: string;
+    data: unknown;
+};
+/** A peer's answer: its words, and what it gave besides them. */
+export type A2APeerAnswer = {
+    answer: string;
+    artifacts: A2APeerArtifact[];
+};
 /** What happens to one request, as it happens. */
 export type A2APeerEvent = {
     phase: 'asked';
     request: string;
+    accept?: string[];
 } | {
     phase: 'working';
     taskId: string;
@@ -73,12 +104,22 @@ export type A2APeerEvent = {
     phase: 'answered';
     taskId: string;
     answer: string;
+    /** What it gave besides words, in the order it gave them. */
+    artifacts: A2APeerArtifact[];
 } | {
     phase: 'failed';
     error: string;
 };
 /** The text of a message's or an artifact's parts. */
 export declare function textOf(parts: Part[] | undefined): string;
+/**
+ * What an artifact gives besides words: each part that is not text, by its
+ * media type. A part without one is not told apart, and is left out.
+ */
+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;
 /**
@@ -94,24 +135,40 @@ export declare function stepOf(message: Message | undefined): {
     note?: string;
     tool?: A2APeerToolStep;
 };
+export type AskA2APeerOptions = {
+    signal?: AbortSignal;
+    onEvent?: (event: A2APeerEvent) => void;
+    /**
+     * The media types the asker accepts (`acceptedOutputModes`): words, and
+     * any format it can show, such as a notebook. Unsaid, nothing is named and
+     * the peer answers in words alone.
+     */
+    accept?: readonly string[];
+};
 /**
  * Ask a peer once, streaming the task, and return its answer.
  *
- * The answer is the text of the task's artifact, assembled from its chunks,
- * or the final status message's when there is no artifact. A task that ends
- * other than completed is thrown, with what the peer said.
+ * The answer is the text of the task's artifacts, assembled from their
+ * chunks, or the final status message's when there is none; what it gave
+ * besides words comes with it, by media type. A task that ends other than
+ * completed is thrown, with what the peer said.
  */
-export declare function askA2APeer(peer: A2APeer, request: string, options?: {
-    signal?: AbortSignal;
-    onEvent?: (event: A2APeerEvent) => void;
-}): Promise<string>;
+export declare function askA2APeer(peer: A2APeer, request: string, options?: AskA2APeerOptions): Promise<A2APeerAnswer>;
 export type A2APeerToolOptions = {
     peer: A2APeer;
     /** Told each step of each request, as it happens. */
     onEvent?: (event: A2APeerEvent) => void;
+    /**
+     * The media types the asker accepts, words and the formats its page can
+     * show: what each request accepts unless the model narrows it with
+     * `formats`. Unsaid, words alone.
+     */
+    accept?: readonly string[];
 };
-/** The tool's description: the peer's skill, and what it may be asked. */
-export declare function peerToolDescription(peer: A2APeer): string;
+/** The formats a peer gives besides words that the asker accepts too. */
+export declare function offeredFormats(peer: A2APeer, accept: readonly string[] | undefined): string[];
+/** The tool's description: the peer's skill, what it may be asked, and what it gives besides words. */
+export declare function peerToolDescription(peer: A2APeer, accept?: readonly string[]): string;
 /**
  * The tool an agent asks its peer with: a request in, the peer's answer out.
  *

package/lib/runtimes/browser/a2aPeer.js

@@ -18,6 +18,13 @@
  *   peer's answer in words. Each step is told to {@link A2APeerEvent} as it
  *   happens, so a page can show the exchange: asked, working, answered.
  *
+ * **Output formats.** A peer's card says the media types it answers in (its
+ * skill's `outputModes`). The asker says which it accepts with each request
+ * (`acceptedOutputModes`, {@link AskA2APeerOptions.accept}); what the peer
+ * gives besides words — a Jupyter notebook, `application/x-ipynb+json` —
+ * arrives as artifacts, one part of a media type each, and is handed over on
+ * `answered` as {@link A2APeerArtifact}s, whatever their format.
+ *
  * The key goes as a bearer token on every request, the card's too. The
  * runtime hands it to the peer's run, which then reaches the peer's
  * connections with it and with nothing broader.
@@ -64,12 +71,52 @@ export async function connectA2APeer(options) {
     }
     return { client, card, skill };
 }
+/** The media types an answer in words comes in: the answer itself, never an artifact of its own. */
+export const TEXT_MEDIA_TYPES = [
+    'text/plain',
+    'text/markdown',
+];
+/** A Jupyter notebook, as A2A carries it. */
+export const NOTEBOOK_MEDIA_TYPE = 'application/x-ipynb+json';
+/** What a format is, in words, for a model reading a tool's description. */
+const FORMAT_NAMES = {
+    [NOTEBOOK_MEDIA_TYPE]: 'a Jupyter notebook',
+};
 /** The text of a message's or an artifact's parts. */
 export function textOf(parts) {
     return (parts ?? [])
         .map(part => (part.content?.$case === 'text' ? part.content.value : ''))
         .join('');
 }
+/** Whether a media type is JSON: `application/json`, or `+json` like a notebook. */
+function isJson(mediaType) {
+    return mediaType === 'application/json' || mediaType.endsWith('+json');
+}
+/**
+ * What an artifact gives besides words: each part that is not text, by its
+ * media type. A part without one is not told apart, and is left out.
+ */
+export function artifactsOf(artifact) {
+    const found = [];
+    for (const part of artifact?.parts ?? []) {
+        const content = part.content;
+        const mediaType = part.mediaType;
+        if (!content || content.$case === 'text' || !mediaType) {
+            continue;
+        }
+        let data = content.value;
+        if (content.$case === 'raw' && isJson(mediaType)) {
+            data = JSON.parse(new TextDecoder().decode(content.value));
+        }
+        found.push({
+            mediaType,
+            name: artifact?.name || part.filename || mediaType,
+            ...(part.filename ? { filename: part.filename } : {}),
+            data,
+        });
+    }
+    return found;
+}
 /** A user's message of one text part, as the SDK's 1.x types write it. */
 export function textMessage(text) {
     return {
@@ -111,7 +158,9 @@ export function stepOf(message) {
             if (told?.name) {
                 const ended = !data.tool_call;
                 return {
-                    note: ended ? `Read ${told.name}` : `Calling ${told.name}`,
+                    // A tool that composes an output says what it does in words
+                    // (`Writing a notebook…`); any other is named.
+                    note: told.note || (ended ? `Read ${told.name}` : `Calling ${told.name}`),
                     tool: {
                         ...(told.id ? { id: told.id } : {}),
                         name: told.name,
@@ -136,15 +185,20 @@ const ENDED_BADLY = {
 /**
  * Ask a peer once, streaming the task, and return its answer.
  *
- * The answer is the text of the task's artifact, assembled from its chunks,
- * or the final status message's when there is no artifact. A task that ends
- * other than completed is thrown, with what the peer said.
+ * The answer is the text of the task's artifacts, assembled from their
+ * chunks, or the final status message's when there is none; what it gave
+ * besides words comes with it, by media type. A task that ends other than
+ * completed is thrown, with what the peer said.
  */
 export async function askA2APeer(peer, request, options = {}) {
-    const { signal, onEvent } = options;
-    onEvent?.({ phase: 'asked', request });
+    const { signal, onEvent, accept } = options;
+    onEvent?.({
+        phase: 'asked',
+        request,
+        ...(accept?.length ? { accept: [...accept] } : {}),
+    });
     try {
-        return await streamTask(peer, request, signal, onEvent);
+        return await streamTask(peer, request, signal, onEvent, accept);
     }
     catch (reason) {
         const error = reason instanceof Error ? reason.message : String(reason);
@@ -152,15 +206,23 @@ export async function askA2APeer(peer, request, options = {}) {
         throw reason;
     }
 }
-async function streamTask(peer, request, signal, onEvent) {
-    const artifacts = new Map();
+async function streamTask(peer, request, signal, onEvent, accept) {
+    const texts = new Map();
+    // What it gave besides words, by artifact: the last chunk says it whole.
+    const given = new Map();
     let taskId = '';
     let final = '';
     let ended;
     const stream = peer.client.sendMessageStream({
         tenant: '',
         message: textMessage(request),
-        configuration: undefined,
+        configuration: accept?.length
+            ? {
+                acceptedOutputModes: [...accept],
+                taskPushNotificationConfig: undefined,
+                returnImmediately: false,
+            }
+            : undefined,
         metadata: undefined,
     }, { signal });
     for await (const event of stream) {
@@ -187,11 +249,17 @@ async function streamTask(peer, request, signal, onEvent) {
             const artifact = payload.value.artifact;
             if (artifact) {
                 const text = textOf(artifact.parts);
-                const before = artifacts.get(artifact.artifactId) ?? '';
-                // Chunks are appended; the last chunk carries the whole answer again.
-                artifacts.set(artifact.artifactId, payload.value.append && !payload.value.lastChunk
-                    ? before + text
-                    : text);
+                const besides = artifactsOf(artifact);
+                if (besides.length) {
+                    given.set(artifact.artifactId, besides);
+                }
+                if (text || !besides.length) {
+                    const before = texts.get(artifact.artifactId) ?? '';
+                    // Chunks are appended; the last chunk carries the whole answer again.
+                    texts.set(artifact.artifactId, payload.value.append && !payload.value.lastChunk
+                        ? before + text
+                        : text);
+                }
             }
         }
         else if (payload.$case === 'message') {
@@ -203,28 +271,53 @@ async function streamTask(peer, request, signal, onEvent) {
         const how = (ended !== undefined && ENDED_BADLY[ended]) || 'ended without an answer';
         throw new Error(`${peer.card.name} ${how}${final ? `: ${final}` : '.'}`);
     }
-    const answer = [...artifacts.values()].join('\n') || final;
-    onEvent?.({ phase: 'answered', taskId, answer });
-    return answer;
+    const answer = [...texts.values()].filter(text => text).join('\n') || final;
+    const artifacts = [...given.values()].flat();
+    onEvent?.({ phase: 'answered', taskId, answer, artifacts });
+    return { answer, artifacts };
+}
+/** The formats a peer gives besides words that the asker accepts too. */
+export function offeredFormats(peer, accept) {
+    const outputs = peer.skill.outputModes.length
+        ? peer.skill.outputModes
+        : peer.card.defaultOutputModes;
+    return outputs.filter(mode => !TEXT_MEDIA_TYPES.includes(mode) && (accept ?? []).includes(mode));
 }
-/** The input of a peer's tool: one request, in words, as its skill takes it. */
-const REQUEST_SCHEMA = {
-    type: 'object',
-    properties: {
-        request: {
-            type: 'string',
-            description: 'What to ask, in one request that can be acted on without the rest of this conversation.',
+/** The input of a peer's tool: one request, in words, and the formats wanted besides. */
+function requestSchema(formats) {
+    return {
+        type: 'object',
+        properties: {
+            request: {
+                type: 'string',
+                description: 'What to ask, in one request that can be acted on without the rest of this conversation.',
+            },
+            ...(formats.length
+                ? {
+                    formats: {
+                        type: 'array',
+                        items: { type: 'string', enum: formats },
+                        description: `What to ask for besides its answer in words, by media type: ${formats
+                            .map(format => `${format} (${FORMAT_NAMES[format] ?? format})`)
+                            .join(', ')}. Empty for words alone; left out, it may give any of them.`,
+                    },
+                }
+                : {}),
         },
-    },
-    required: ['request'],
-};
-/** The tool's description: the peer's skill, and what it may be asked. */
-export function peerToolDescription(peer) {
+        required: ['request'],
+    };
+}
+/** The tool's description: the peer's skill, what it may be asked, and what it gives besides words. */
+export function peerToolDescription(peer, accept) {
     const { card, skill } = peer;
     const examples = skill.examples.length
         ? ` For example: ${skill.examples.map(example => `"${example}"`).join('; ')}.`
         : '';
-    return `Ask ${card.name}, over A2A: ${skill.description}${examples} It answers in words; report its answer as it gave it.`;
+    const formats = offeredFormats(peer, accept);
+    const besides = formats.length
+        ? ` It can also give ${formats.map(format => FORMAT_NAMES[format] ?? format).join(' or ')}, shown to the person as it arrives: ask for it with \`formats\` when the person wants one, and do not repeat its content.`
+        : '';
+    return `Ask ${card.name}, over A2A: ${skill.description}${examples} It answers in words; report its answer as it gave it.${besides}`;
 }
 /**
  * The tool an agent asks its peer with: a request in, the peer's answer out.
@@ -233,21 +326,42 @@ export function peerToolDescription(peer) {
  * person what the peer said instead of the whole run failing.
  */
 export function a2aPeerTool(options) {
-    const { peer, onEvent } = options;
+    const { peer, onEvent, accept } = options;
+    const formats = offeredFormats(peer, accept);
     return tool({
-        description: peerToolDescription(peer),
-        inputSchema: jsonSchema(REQUEST_SCHEMA),
+        description: peerToolDescription(peer, accept),
+        inputSchema: jsonSchema(requestSchema(formats)),
         execute: async (input, execution) => {
-            const { request } = (input ?? {});
+            const { request, formats: wanted } = (input ?? {});
             if (!request?.trim()) {
                 return { error: `A request to ${peer.card.name} says what it asks.` };
             }
+            // Words always; besides them, what the model asked for, or else
+            // whatever the asker accepts.
+            const accepted = Array.isArray(wanted)
+                ? [
+                    ...(accept ?? []).filter(mode => TEXT_MEDIA_TYPES.includes(mode)),
+                    ...wanted.filter(mode => formats.includes(mode)),
+                ]
+                : accept;
             try {
-                const answer = await askA2APeer(peer, request, {
+                const { answer, artifacts } = await askA2APeer(peer, request, {
                     signal: execution?.abortSignal,
                     onEvent,
+                    accept: accepted,
                 });
-                return { answer };
+                // What it gave besides words is shown to the person; the model is
+                // told it came, not its content.
+                return artifacts.length
+                    ? {
+                        answer,
+                        attached: artifacts.map(artifact => ({
+                            mediaType: artifact.mediaType,
+                            name: artifact.name,
+                            shown: 'to the person, as it arrived',
+                        })),
+                    }
+                    : { answer };
             }
             catch (reason) {
                 return {

package/lib/specs/apps.js

@@ -75,6 +75,7 @@ export const ACCOUNTING_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: ['text/markdown', 'application/x-ipynb+json'],
     },
     tests: {
         readyAt: 0.8,
@@ -212,6 +213,7 @@ export const CUSTOMER_INTERVIEW_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.8,
@@ -327,6 +329,7 @@ export const DATA_QUALITY_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.8,
@@ -482,6 +485,7 @@ export const DECIDE_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.8,
@@ -633,6 +637,7 @@ export const INBOX_TRIAGE_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.9,
@@ -770,6 +775,7 @@ export const MODEL_CHOICE_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.8,
@@ -1102,6 +1108,7 @@ export const PIPELINE_REPORT_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.9,
@@ -1396,6 +1403,7 @@ export const QUOTE_CALCULATOR_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 1.0,
@@ -1631,6 +1639,7 @@ export const REPORT_FROM_A_FILE_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.8,
@@ -1752,6 +1761,7 @@ export const SALES_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.8,
@@ -1866,6 +1876,7 @@ export const SHIP_OR_FIX_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.8,
@@ -2041,6 +2052,7 @@ export const SUPPLIER_COMPARISON_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.8,
@@ -2334,6 +2346,7 @@ export const SUPPORT_DESK_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.8,
@@ -2468,6 +2481,7 @@ export const WEB_RESEARCH_APP_0_0_1 = {
             language: '',
             where: 'auto',
         },
+        outputs: [],
     },
     tests: {
         readyAt: 0.8,
@@ -2603,6 +2617,7 @@ export const APP_SOURCES = {
                 },
             ],
             assistant: 'wizard',
+            outputs: ['text/markdown', 'application/x-ipynb+json'],
         },
         tests: {
             cases: [

package/lib/specs/appspecSchema.js

@@ -330,6 +330,16 @@ export const APPSPEC_SCHEMA = {
                     $ref: '#/$defs/AppVoice',
                     description: 'Its voice: whether it listens and speaks, with which voice, in which language (off unless said)',
                 },
+                outputs: {
+                    description: "The formats its answers come in, by media type, words first: `text/markdown`, then `application/x-ipynb+json` for a Jupyter notebook. Over A2A, its agent card's output modes; a caller asks for some of them (`acceptedOutputModes`). Plain text alone when unsaid",
+                    items: {
+                        pattern: '^[a-z0-9][a-z0-9.+-]*/[a-z0-9][a-z0-9.+-]*$',
+                        type: 'string',
+                    },
+                    title: 'Outputs',
+                    type: 'array',
+                    uniqueItems: true,
+                },
             },
             title: 'AppInterface',
             type: 'object',

package/lib/types/agentspecs.d.ts

@@ -481,6 +481,12 @@ export interface AppInterfaceSpec {
     assistant?: AppAssistantCharacter;
     /** Its voice: off unless said (VO-41); absent from a spec made before voice. */
     voice?: AppVoiceSpec;
+    /**
+     * The formats its answers come in, by media type, words first:
+     * `text/markdown`, then `application/x-ipynb+json` for a Jupyter notebook.
+     * Over A2A, its agent card's output modes. Empty: plain text alone.
+     */
+    outputs: string[];
 }
 export interface AppTestCaseSpec {
     ask: string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.69",
+    "version": "1.3.71",
     "type": "module",
     "workspaces": [
         ".",