@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/examples/A2UiJupyterOutputExample.js

@@ -0,0 +1,792 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React, { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { Box } from '@datalayer/primer-addons';
+import { Button, Label, SegmentedControl, Spinner, Text, } from '@primer/react';
+import { PlayIcon } from '@primer/octicons-react';
+import { Output, OutputIPyWidgets } from '@datalayer/jupyter-react';
+import { LoopEmbed } from '../loop';
+import { AgentA2uiJupyterOutputPlugin } from '../loop/plugins/agent-a2ui-jupyter-output';
+import { createChatExtrasPlugin } from '../loop/plugins/chat-extras';
+import { A2UI_RENDER_SCOPE_SX, A2uiSurfaceComposed } from '../components/a2ui';
+import { ThemedJupyterProvider, ThemedProvider } from './utils/themedProvider';
+import { A2uiMarkdownProvider } from './utils/a2uiMarkdownProvider';
+import { useA2uiProcessor } from './utils/a2ui';
+import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
+import { uniqueAgentId } from './utils/agentId';
+import { useRuntimeTarget } from './utils/runtimeTargetStore';
+const EXAMPLE_ID = 'A2UiJupyterOutputExample';
+const AGENT_NAME = 'a2ui-jupyter-output';
+const AGENTSPEC_ID = 'example-a2ui-jupyter-output';
+/*
+ * The six kinds, as a value as well as a type.
+ *
+ * The list was written twice — once here and once in the tool's JSON schema
+ * `enum` — which is two places to forget one. Deriving both from this array
+ * keeps the schema the model is given and the check the handler performs
+ * describing the same six things.
+ */
+const DEMO_KINDS = [
+    'stream',
+    'figure',
+    'table',
+    'error',
+    'ipywidgets',
+    'interactive',
+];
+/** Whether a value the model sent is one of the kinds we know how to run. */
+function isDemoKind(value) {
+    return (typeof value === 'string' &&
+        DEMO_KINDS.includes(value));
+}
+const SNIPPETS = [
+    {
+        id: 'stream',
+        label: 'Stream',
+        about: 'stdout and a returned value. The plainest case, and the one that reads worst as raw output.',
+        code: `import platform
+import time
+
+print("Python", platform.python_version())
+planets = [("Mars", 2), ("Jupiter", 95), ("Saturn", 274)]
+for index, (planet, moons) in enumerate(planets):
+    print(f"{planet:<8} {moons:>4} moons")
+    if index < len(planets) - 1:
+        for _ in range(6):
+            print(".", end="", flush=True)
+            time.sleep(0.25)
+        print()
+
+sum(moons for _, moons in planets)
+`,
+    },
+    {
+        id: 'figure',
+        label: 'Figure',
+        about: 'An image/png mime bundle. As raw output this is a base64 blob; as a surface it is the plot.',
+        code: `import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+from io import BytesIO
+from IPython.display import Image, display
+
+x = np.linspace(0, 4 * np.pi, 400)
+figure, axes = plt.subplots(figsize=(5, 2.6))
+axes.plot(x, np.sin(x), label="sin")
+axes.plot(x, np.sin(x) * np.exp(-x / 8), label="damped")
+axes.legend()
+axes.set_title("Two waves")
+png = BytesIO()
+figure.savefig(png, format="png", bbox_inches="tight")
+display(Image(data=png.getvalue()))
+plt.close(figure)
+`,
+    },
+    {
+        id: 'table',
+        label: 'Table',
+        about: 'A DataFrame, which arrives as several representations of one value — text/plain beside text/html.',
+        code: `import pandas as pd
+
+pd.DataFrame(
+    {
+        "environment": ["python-cpu", "python-gpu", "ai-agents"],
+        "runtimes": [12, 3, 27],
+        "credits": [4.5, 61.0, 18.25],
+    }
+)
+`,
+    },
+    {
+        id: 'error',
+        label: 'Error',
+        about: 'A traceback. The converter puts it first, above everything the code managed to print before it failed.',
+        code: `print("this much worked")
+
+readings = {"north": 12.5, "south": 9.0}
+readings["east"] / 2
+`,
+    },
+    {
+        id: 'ipywidgets',
+        label: 'IPyWidgets',
+        about: 'An IntSlider with its widget view and manager state embedded in the output, rendered by jupyter-react as an actual interactive control.',
+        code: `from IPython.display import display
+from ipywidgets import IntSlider
+from ipywidgets.embed import embed_data
+
+slider = IntSlider(
+    value=7,
+    min=0,
+    max=10,
+    step=1,
+    description="Count:",
+    continuous_update=True,
+)
+embedded = embed_data(views=[slider])
+display(
+    {
+        "text/plain": repr(slider),
+        "application/vnd.jupyter.widget-view+json": embedded["view_specs"][0],
+        "application/vnd.jupyter.widget-state+json": embedded["manager_state"],
+    },
+    raw=True,
+)
+`,
+    },
+    {
+        id: 'interactive',
+        label: 'Interactive',
+        about: 'A surface you can press. The click comes back as `a2ui_action`, the code runs again knowing it, and the surface it returns replaces this one.',
+        actions: [
+            { name: 'errors', label: 'Errors' },
+            { name: 'warnings', label: 'Warnings' },
+            { name: 'info', label: 'Info' },
+        ],
+        code: `# \`a2ui_action\` is bound by the server when you press a button below.
+choice = (globals().get("a2ui_action") or {}).get("name", "")
+
+counts = {"errors": 3, "warnings": 11, "info": 240}
+if choice in counts:
+    print(f"{choice}: {counts[choice]}")
+else:
+    print("Pick a level to see its count.")
+    print("levels:", ", ".join(counts))
+`,
+    },
+    {
+        id: 'chat',
+        label: 'Chat',
+        about: 'Ask the agent to run any demonstration. The suggestions call the same Jupyter execution path as the tabs above.',
+        code: '',
+        chat: true,
+    },
+];
+/*
+ * What to ask for, in the words somebody would actually use.
+ *
+ * These used to read 'Call run_jupyter_output_demo with kind "figure"' — a
+ * person reciting a function signature to a machine that already knows it,
+ * and a demonstration of the plumbing rather than of the product. Which tool
+ * answers a request is the agent's problem, and the agentspec's system prompt
+ * now tells it how to read each of these; a suggestion is for the reader.
+ *
+ * They name the code sandbox, because that is the thing being demonstrated
+ * and the reader can see it running.
+ */
+/** The surface this example draws into; re-running replaces rather than stacks. */
+const SURFACE_ID = 'jupyter-output';
+/**
+ * What the sandbox kernel returned, rendered through the same jupyter-react
+ * Output component applications use for notebook output.
+ */
+function JupyterOutputs({ execution, }) {
+    if (!execution) {
+        return (_jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Nothing has run yet." }));
+    }
+    const outputs = [...(execution.outputs ?? [])];
+    const hasStdout = outputs.some(output => output.output_type === 'stream' && output.name === 'stdout');
+    if (!hasStdout && execution.stdout?.trim()) {
+        outputs.push({
+            output_type: 'stream',
+            name: 'stdout',
+            text: execution.stdout,
+        });
+    }
+    if (execution.stderr?.trim()) {
+        outputs.push({
+            output_type: 'stream',
+            name: 'stderr',
+            text: execution.stderr,
+        });
+    }
+    if (execution.error &&
+        !outputs.some(output => output.output_type === 'error')) {
+        outputs.push({
+            output_type: 'error',
+            ename: 'ExecutionError',
+            evalue: execution.error,
+            traceback: [execution.error],
+        });
+    }
+    if (outputs.length === 0) {
+        return (_jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "The code ran and produced no output." }));
+    }
+    const widgetViewMime = 'application/vnd.jupyter.widget-view+json';
+    const widgetStateMime = 'application/vnd.jupyter.widget-state+json';
+    return (
+    /*
+      `ThemedJupyterProvider`, which is both halves of what this panel needs.
+
+      It had neither. The example's `ThemedProvider` supplies Primer and the
+      Datalayer theme and nothing Jupyter, so the JupyterLab stylesheets were
+      never loaded and no `--jp-*` variable existed on the page. `Output`
+      still rendered — its structure is React, and `OutputRenderer` colours an
+      error with an inline style needing no stylesheet — but everything that
+      makes it *look* like a notebook did not: `.jp-RenderedText`, an error's
+      background and padding, the mono stack, and the ipywidgets control CSS,
+      which is why a slider could arrive looking like text.
+
+      A bare `JupyterReactTheme` fixes that and brings its own problem: it
+      applies JupyterLab's palette, so the outputs stop matching the page
+      around them. This wrapper is the pairing that already exists for it —
+      the Datalayer theme outside, carrying the reader's chosen variant and
+      colormode, and a `JupyterReactTheme` inside it that loads the
+      stylesheets while taking its colormode and canvas from that theme, with
+      `useBaseStyles` off so the branded font survives.
+    */
+    _jsx(ThemedJupyterProvider, { children: _jsx(Box, { sx: {
+                bg: 'canvas.default',
+                color: 'fg.default',
+                /*
+                The JupyterLab palette, pointed at the Datalayer one.
+      
+                `JupyterLabCss` injects the `--jp-*` variables onto `document.body`,
+                for the whole page — so a wrapper's `backgroundColor` cannot reach
+                them, and the outputs kept JupyterLab's own white while the page
+                around them was the reader's theme. That is why an ipywidget arrived
+                sitting on a white band.
+      
+                Redefining them here rather than fighting for specificity: custom
+                properties inherit, and the nearest definition wins for the subtree
+                below it. Everything Jupyter draws inside this panel — output areas,
+                rendered text, widget controls, which all resolve their colours
+                through these — therefore follows the theme the reader picked.
+              */
+                '--jp-layout-color0': 'var(--bgColor-default)',
+                '--jp-layout-color1': 'var(--bgColor-default)',
+                '--jp-layout-color2': 'var(--bgColor-muted)',
+                '--jp-layout-color3': 'var(--bgColor-muted)',
+                '--jp-content-font-color0': 'var(--fgColor-default)',
+                '--jp-content-font-color1': 'var(--fgColor-default)',
+                '--jp-content-font-color2': 'var(--fgColor-muted)',
+                '--jp-ui-font-color0': 'var(--fgColor-default)',
+                '--jp-ui-font-color1': 'var(--fgColor-default)',
+                '--jp-ui-font-color2': 'var(--fgColor-muted)',
+                '--jp-border-color1': 'var(--borderColor-default)',
+                '--jp-border-color2': 'var(--borderColor-muted)',
+                '--jp-border-color3': 'var(--borderColor-muted)',
+                // ipywidgets keeps its own names, and a control left on the defaults
+                // is the one thing in the panel still wearing JupyterLab's palette.
+                '--jp-widgets-color': 'var(--fgColor-default)',
+                '--jp-widgets-label-color': 'var(--fgColor-default)',
+                '--jp-widgets-readout-color': 'var(--fgColor-default)',
+                '--jp-widgets-input-color': 'var(--fgColor-default)',
+                '--jp-widgets-input-background-color': 'var(--bgColor-default)',
+                '--jp-widgets-input-border-color': 'var(--borderColor-default)',
+                '--jp-widgets-border-color': 'var(--borderColor-default)',
+                '& .jp-OutputArea, & .jp-OutputArea-output': {
+                    bg: 'canvas.default',
+                    color: 'fg.default',
+                },
+                '& table, & th, & td': {
+                    backgroundColor: 'canvas.default',
+                    color: 'fg.default',
+                    borderColor: 'border.default',
+                },
+            }, children: outputs.map((output, index) => {
+                const data = 'data' in output && output.data
+                    ? output.data
+                    : undefined;
+                const view = data?.[widgetViewMime];
+                const state = data?.[widgetStateMime];
+                if (view && state) {
+                    return (_jsx(OutputIPyWidgets, { view: view, state: state }, `${SURFACE_ID}-widget-${index}`));
+                }
+                const isError = output.output_type === 'error' ||
+                    (output.output_type === 'stream' && output.name === 'stderr');
+                return (_jsx(Output, { id: `${SURFACE_ID}-output-${index}`, outputs: [output], autoRun: false, lumino: !isError, showControl: false, showEditor: false, showKernelProgressBar: false }, `${SURFACE_ID}-output-${index}`));
+            }) }) }));
+}
+function Panel({ title, caption, children, style, sx, }) {
+    return (_jsxs(Box, { sx: {
+            flex: '1 1 0',
+            height: '100%',
+            minWidth: 0,
+            minHeight: 0,
+            display: 'flex',
+            flexDirection: 'column',
+            border: '1px solid',
+            borderColor: 'border.default',
+            borderRadius: 2,
+            bg: 'canvas.default',
+            color: 'fg.default',
+            overflow: 'hidden',
+        }, children: [_jsxs(Box, { sx: {
+                    px: 3,
+                    py: 2,
+                    borderBottom: '1px solid',
+                    borderColor: 'border.default',
+                    bg: 'canvas.default',
+                    color: 'fg.default',
+                }, children: [_jsx(Text, { sx: { fontWeight: 'semibold' }, children: title }), _jsx(Text, { sx: { display: 'block', fontSize: 0, color: 'fg.muted' }, children: caption })] }), _jsx(Box, { style: style, sx: {
+                    flex: '1 1 0',
+                    minHeight: 0,
+                    overflow: 'auto',
+                    p: 3,
+                    bg: 'canvas.default',
+                    color: 'fg.default',
+                    ...sx,
+                }, children: children })] }));
+}
+const A2UiJupyterOutputExample = () => {
+    const { label: targetLabel } = useRuntimeTarget();
+    const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
+    const { agentId, isReady: agentReady, baseUrl: serverUrl, hasAgent, chatGate, error: agentError, } = useExampleAgentRuntime({
+        exampleId: EXAMPLE_ID,
+        agentName,
+        specId: AGENTSPEC_ID,
+        agentConfig: {
+            protocol: 'vercel-ai',
+            agentSpecId: AGENTSPEC_ID,
+        },
+    });
+    const unavailableReason = chatGate.disableReason;
+    const [snippetId, setSnippetId] = useState(SNIPPETS[0].id);
+    const snippet = useMemo(() => SNIPPETS.find(entry => entry.id === snippetId) ?? SNIPPETS[0], [snippetId]);
+    const [code, setCode] = useState(SNIPPETS[0].code);
+    const [running, setRunning] = useState(false);
+    const [failure, setFailure] = useState(null);
+    const [execution, setExecution] = useState(null);
+    // The code that drew what is on screen, so an action re-runs *it* rather
+    // than whatever happens to be in the editor by the time the click lands.
+    const sourceRef = useRef(SNIPPETS[0].code);
+    const actionsRef = useRef([]);
+    /* Which demonstration drew the surface, for the same reason `sourceRef` and
+       `actionsRef` exist: a click has to re-run the thing it was a click on.
+       Without it, pressing a button updated both panels and left the chat's copy
+       of that demonstration's output at whatever it was before the press. */
+    const kindRef = useRef(undefined);
+    const runRef = useRef(null);
+    const handleAction = useCallback((action) => {
+        void runRef.current?.(sourceRef.current, action, actionsRef.current, kindRef.current);
+    }, []);
+    const { surfaces, processMessages, resetSurfaces, themeStyle } = useA2uiProcessor(handleAction);
+    const run = useCallback(async (source, action, actions = [], 
+    // Which demonstration this is, when it is one. The chat draws its output
+    // under the matching tool message, and needs the snapshots as they
+    // arrive rather than the result at the end.
+    kind) => {
+        if (!agentId) {
+            setFailure('The Jupyter agent is not ready yet.');
+            return null;
+        }
+        setRunning(true);
+        setFailure(null);
+        sourceRef.current = source;
+        actionsRef.current = actions;
+        kindRef.current = kind;
+        try {
+            const response = await fetch(`${serverUrl.replace(/\/$/, '')}/api/v1/sandbox/execute/a2ui`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    code: source,
+                    action: action ?? null,
+                    surface_id: SURFACE_ID,
+                    agent_id: agentId,
+                    actions,
+                    // A2UI is a streaming protocol and its specification names the
+                    // single POST as the one transport that cannot carry that. The
+                    // stream demonstration prints a line at a time and was invisible
+                    // until it had finished.
+                    stream: true,
+                }),
+            });
+            if (!response.ok) {
+                setFailure(`The server could not run that (${response.status} ${response.statusText}).`);
+                return null;
+            }
+            // Replace rather than stack: a re-run is the same surface with new
+            // data, not a second one below the first. Done before the first
+            // message arrives, so the old surface is not on screen underneath the
+            // new one while it builds.
+            resetSurfaces();
+            /*
+             * Branch on what the server actually sent, not on what was asked for.
+             *
+             * A server that does not know the `stream` flag ignores it and answers
+             * with the whole surface as JSON — and a reader loop turned loose on
+             * that finds no `data:` lines, processes no messages, and renders an
+             * empty surface. Which is worse than not streaming: the feature would
+             * appear to have broken the example rather than simply not being
+             * there. The same branch covers an environment that gives no readable
+             * body at all.
+             */
+            const streamed = (response.headers.get('content-type') ?? '').includes('text/event-stream');
+            const reader = streamed ? response.body?.getReader() : undefined;
+            if (!reader) {
+                const payload = await response.json();
+                const whole = (payload.execution ?? null);
+                setExecution(whole);
+                if (kind && whole) {
+                    setExecutionsByKind(previous => ({ ...previous, [kind]: whole }));
+                }
+                processMessages((payload.messages ?? []));
+                return whole;
+            }
+            const decoder = new TextDecoder();
+            let buffer = '';
+            let nextExecution = null;
+            /*
+             * Surfaces already created, so a redelivered `createSurface` is not
+             * processed twice.
+             *
+             * The reference A2UI client keeps the same set for the same reason:
+             * the processor treats a second create for one id as an error, and a
+             * stream that re-announces its surface would otherwise fail partway
+             * through for a reason that looks nothing like its cause.
+             */
+            const created = new Set();
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                buffer += decoder.decode(value, { stream: true });
+                // Events are separated by a blank line; the last piece may be a
+                // partial event, so it stays in the buffer for the next read.
+                const chunks = buffer.split(/\r?\n\r?\n/);
+                buffer = chunks.pop() ?? '';
+                for (const chunk of chunks) {
+                    for (const line of chunk.split(/\r?\n/)) {
+                        if (!line.startsWith('data: ')) {
+                            continue;
+                        }
+                        let event;
+                        try {
+                            event = JSON.parse(line.slice(6));
+                        }
+                        catch {
+                            // A malformed event is not worth abandoning the run for.
+                            continue;
+                        }
+                        /*
+                          An execution snapshot, whether or not the run has finished.
+          
+                          The Jupyter Output panel renders from this rather than from
+                          the A2UI surface, so applying it only on the final event left
+                          one half of the comparison streaming and the other half
+                          frozen until the end — which is the least useful place for the
+                          difference to be.
+                        */
+                        if (event.execution) {
+                            nextExecution = event.execution;
+                            setExecution(nextExecution);
+                            if (kind) {
+                                const snapshot = nextExecution;
+                                setExecutionsByKind(previous => ({
+                                    ...previous,
+                                    [kind]: snapshot,
+                                }));
+                            }
+                            continue;
+                        }
+                        if (event.done) {
+                            continue;
+                        }
+                        const create = event.createSurface;
+                        if (create?.surfaceId) {
+                            if (created.has(create.surfaceId)) {
+                                continue;
+                            }
+                            created.add(create.surfaceId);
+                        }
+                        processMessages([event]);
+                    }
+                }
+            }
+            return nextExecution;
+        }
+        catch (error) {
+            setFailure(error instanceof Error ? error.message : String(error));
+            return null;
+        }
+        finally {
+            setRunning(false);
+        }
+    }, [agentId, processMessages, resetSurfaces, serverUrl]);
+    // Published for the processor's action callback, which is built once and
+    // cannot close over a `run` that changes with the server URL.
+    React.useEffect(() => {
+        runRef.current = run;
+    }, [run]);
+    const chooseSnippet = useCallback((next) => {
+        setSnippetId(next.id);
+        setCode(next.code);
+        setExecution(null);
+        setFailure(null);
+        resetSurfaces();
+    }, [resetSurfaces]);
+    /*
+     * Arguments typed as they actually arrive: unvalidated.
+     *
+     * This was declared `FrontendToolDefinition<{ kind: DemoKind }, …>`, and
+     * TypeScript was right to refuse it. Parameters are contravariant, so a
+     * handler that demands `{ kind: DemoKind }` cannot stand in for one the
+     * runner will call with an arbitrary `Record<string, unknown>` — and an
+     * arbitrary record is exactly what it gets, because these arguments are
+     * whatever the model emitted against the JSON schema below. Nothing between
+     * the model and here checks them.
+     *
+     * So the narrowing happens where the values are, at runtime. `isDemoKind`
+     * is the same check the lookup was doing implicitly, made explicit and made
+     * to say something useful when it fails.
+     *
+     * The result is left at the default `unknown` for a related reason: the
+     * optional `render` on this interface *consumes* the result, so the type is
+     * invariant in it, and a narrower result type cannot stand in for the wider
+     * one the tool list holds — whether or not this tool supplies a `render`.
+     * TypeScript checks the shape either way.
+     */
+    /*
+     * Each kind's execution *as it arrives*, in state.
+     *
+     * This was a ref written once, after `run` resolved — two reasons the chat
+     * could not stream while the panels beside it did. A ref mutation does not
+     * re-render, so React had no reason to redraw the message; and there was
+     * nothing to draw until the run had finished anyway.
+     *
+     * The panels stream because they read `execution`, which `run` sets from
+     * every snapshot the server sends. This is the same thing, kept per kind so
+     * a second demonstration does not overwrite the first one's message.
+     */
+    const [executionsByKind, setExecutionsByKind] = useState({});
+    /*
+     * Which surfaces the reader has opened, kept out of the DOM.
+     *
+     * A native `details` remembers being open only for as long as the element
+     * exists — and pressing a button in the surface calls `resetSurfaces`, which
+     * empties the list for a moment, unmounts the whole disclosure and mounts a
+     * new one for the replacement surface. So the fold shut itself on exactly
+     * the interaction it was open for, and had to be reopened to see the answer
+     * to the click.
+     *
+     * Keyed by tool call, so two demonstrations in one conversation stay
+     * independent of each other.
+     */
+    const [openSurfaces, setOpenSurfaces] = useState({});
+    /*
+     * The output, drawn under the tool message in the conversation.
+     *
+     * Running a demonstration updated the two panels and left the chat saying
+     * only that a tool had been called — so a reader following the conversation
+     * was told something happened and shown none of it, and had to look away to
+     * find out what.
+     *
+     * This is `renderToolResult` on `Chat` rather than the `render` field on the
+     * tool definition. That field exists on `FrontendToolDefinition` and nothing
+     * in the chat ever calls it; the first version of this was written there and
+     * was simply dead code, which is only visible by grepping for the call site
+     * rather than by reading the type.
+     *
+     * The execution comes from a ref rather than from the tool's result, because
+     * a handler's return value is sent back to the model: putting a base64
+     * figure or a widget's manager state in there would spend the context window
+     * on bytes no model needs to read.
+     */
+    const renderToolResult = useCallback(({ name, args, status, defaultUI, toolCallId }) => {
+        /*
+          The chat's own tool row, and the output underneath it.
+  
+          Returning only the output replaced the row — so "Run Jupyter Output
+          Demo", its status and its arguments all disappeared, and any other
+          tool called in this chat would have rendered nothing at all, since
+          returning null here draws nothing rather than falling back.
+        */
+        const kind = args.kind;
+        if (name !== 'run_jupyter_output_demo' || !isDemoKind(kind)) {
+            return defaultUI;
+        }
+        // Whatever has arrived so far, mid-run included: the row above says it
+        // is executing, and the output below should be filling in while it
+        // does, which is the whole point of streaming it.
+        const executed = executionsByKind[kind];
+        if (!executed) {
+            return defaultUI;
+        }
+        const demoActions = SNIPPETS.find(entry => entry.id === kind)?.actions ?? [];
+        return (_jsxs(_Fragment, { children: [defaultUI, demoActions.length > 0 ? (_jsxs(Box, { sx: { mt: 2 }, children: [_jsx(Text, { sx: { display: 'block', mb: 1, fontSize: 0, color: 'fg.muted' }, children: "Choose an action" }), _jsx(Box, { sx: { display: 'flex', flexWrap: 'wrap', gap: 2 }, children: demoActions.map((action, index) => (_jsx(Button, { size: "small", variant: index === 0 ? 'primary' : 'default', onClick: () => 
+                                // A real client action, not a cast: the same shape the
+                                // surface's own buttons emit, so the round-trip cannot
+                                // tell the two apart. `sourceComponentId` says which
+                                // button it was, which is the only field that differs.
+                                handleAction({
+                                    name: action.name,
+                                    context: {},
+                                    surfaceId: SURFACE_ID,
+                                    sourceComponentId: `chat-action-${action.name}`,
+                                    timestamp: new Date().toISOString(),
+                                }), children: action.label }, action.name))) })] })) : null, surfaces.length > 0 ? (
+                /*
+                  Folded away, and shut to begin with.
+    
+                  The surface repeats the code, the status and the outputs, and in
+                  a conversation that is a screenful of things the reader has just
+                  read pushing the next message off the bottom. Open it when the
+                  surface is the point — the interactive demonstration's buttons
+                  live in here — and leave it out of the way when it is not.
+    
+                  A native `details`, so the disclosure keeps its keyboard
+                  behaviour and its semantics for nothing, and so the surface
+                  inside it stays mounted: the buttons remain live whether or not
+                  anybody has opened it.
+                */
+                _jsxs(Box, { as: "details", 
+                    // Shut to begin with, for every kind. What the interactive
+                    // demonstration needed from being open — its buttons — is now
+                    // above the fold, and what is left inside is the execution
+                    // detail the reader has already been shown once.
+                    open: openSurfaces[toolCallId] ?? false, onToggle: (event) => {
+                        const isOpen = event.currentTarget.open;
+                        setOpenSurfaces(previous => ({
+                            ...previous,
+                            [toolCallId]: isOpen,
+                        }));
+                    }, sx: { mt: 2 }, children: [_jsx(Box, { as: "summary", sx: {
+                                cursor: 'pointer',
+                                fontSize: 0,
+                                color: 'fg.muted',
+                                // The marker is the affordance; without a list-style the
+                                // triangle disappears in some browsers.
+                                listStyle: 'revert',
+                                '&:hover': { color: 'fg.default' },
+                            }, children: "A2UI surface" }), _jsx(Box, { sx: { mt: 2, ...A2UI_RENDER_SCOPE_SX }, style: themeStyle, children: surfaces.map(surface => (_jsx(A2uiSurfaceComposed, { surface: surface }, surface.id))) })] })) : null, _jsxs(Box, { sx: { mt: 2 }, children: [_jsx(Text, { sx: { display: 'block', mb: 1, fontSize: 0, color: 'fg.muted' }, children: "Jupyter output" }), _jsx(JupyterOutputs, { execution: executed })] })] }));
+    }, [executionsByKind, handleAction, openSurfaces, surfaces, themeStyle]);
+    const runDemoTool = useMemo(() => ({
+        name: 'run_jupyter_output_demo',
+        description: 'Run one output demonstration in the connected Jupyter sandbox and display both its A2UI surface and jupyter-react Output.',
+        parameters: {
+            type: 'object',
+            properties: {
+                kind: {
+                    type: 'string',
+                    enum: [...DEMO_KINDS],
+                    description: 'The Jupyter output demonstration to run.',
+                },
+            },
+            required: ['kind'],
+            additionalProperties: false,
+        },
+        handler: async (args) => {
+            const kind = args.kind;
+            if (!isDemoKind(kind)) {
+                throw new Error(`Unknown Jupyter output demonstration: ${String(kind)}. ` +
+                    `Expected one of ${DEMO_KINDS.join(', ')}.`);
+            }
+            const demo = SNIPPETS.find((entry) => entry.id === kind && !entry.chat);
+            if (!demo) {
+                throw new Error(`Unknown Jupyter output demonstration: ${kind}`);
+            }
+            const result = await run(demo.code, undefined, demo.actions ?? [], kind);
+            if (!result) {
+                throw new Error('The Jupyter output demonstration could not run.');
+            }
+            return {
+                kind,
+                displayed: true,
+                executionSucceeded: result.success,
+            };
+        },
+    }), [run]);
+    // The chat column is the shared loop on the A2UI-jupyter-output capacity
+    // plugin; the bespoke run_jupyter_output_demo frontend tool and the surface
+    // renderer reach it through the chat-extras channel.
+    const { plugin: extrasPlugin, setExtras } = useMemo(() => createChatExtrasPlugin(), []);
+    const chatPlugins = useMemo(() => [AgentA2uiJupyterOutputPlugin, extrasPlugin], [extrasPlugin]);
+    useEffect(() => {
+        setExtras({ frontendTools: [runDemoTool], renderToolResult });
+    }, [runDemoTool, renderToolResult, setExtras]);
+    const outputPanels = (_jsxs(Box, { sx: {
+            flex: '1 1 0',
+            minHeight: 0,
+            height: '100%',
+            display: 'grid',
+            gridTemplateColumns: [
+                'minmax(0, 1fr)',
+                'minmax(0, 1fr)',
+                'repeat(2, minmax(0, 1fr))',
+            ],
+            gridTemplateRows: [
+                'repeat(2, minmax(280px, auto))',
+                'repeat(2, minmax(280px, auto))',
+                'minmax(0, 1fr)',
+            ],
+            gap: 3,
+            alignItems: 'stretch',
+            overflow: ['auto', 'auto', 'hidden'],
+        }, children: [_jsx(Panel, { title: "A2UI Surface", caption: "The outputs read by the server-side converter.", style: themeStyle, sx: A2UI_RENDER_SCOPE_SX, children: surfaces.length === 0 ? (_jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: snippet.chat
+                        ? 'Choose a chat suggestion to see the surface.'
+                        : 'Press Run to see the surface.' })) : (surfaces.map(surface => (_jsx(A2uiSurfaceComposed, { surface: surface }, surface.id)))) }), _jsx(Panel, { title: "Jupyter Output", caption: "The sandbox result rendered by jupyter-react Output.", children: _jsx(JupyterOutputs, { execution: execution }) })] }));
+    return (_jsx(ThemedProvider, { children: _jsx(A2uiMarkdownProvider, { children: _jsxs(Box, { sx: {
+                    height: '100%',
+                    display: 'flex',
+                    flexDirection: 'column',
+                    minHeight: 0,
+                    overflow: 'hidden',
+                    bg: 'canvas.default',
+                    color: 'fg.default',
+                }, children: [_jsxs(Box, { sx: {
+                            px: 3,
+                            py: 3,
+                            borderBottom: '1px solid',
+                            borderColor: 'border.default',
+                            bg: 'canvas.default',
+                            color: 'fg.default',
+                        }, children: [_jsx(Text, { as: "h1", sx: { fontSize: 3, fontWeight: 'bold' }, children: "\uD83D\uDCD3 Jupyter Output as a A2UI Surface" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: "One execution, twice: what the kernel said, and what the A2UI converter made of it. The conversion runs on the server, so a terminal and a JupyterLab panel get the same surface from the same code." })] }), !hasAgent || unavailableReason || agentError ? (_jsx(Box, { sx: { p: 3, bg: 'canvas.default', color: 'fg.default' }, children: _jsx(Text, { sx: { color: 'fg.muted' }, children: unavailableReason || agentError || (_jsxs(_Fragment, { children: ["This example converts on the server, and the", ' ', _jsx("strong", { children: targetLabel }), " target has no agent-runtimes server beside its sandbox. Switch to ", _jsx("strong", { children: "Local" }), ' ', "or ", _jsx("strong", { children: "Datalayer" }), " in the header to run it."] })) }) })) : (_jsxs(Box, { sx: {
+                            flex: '1 1 0',
+                            minHeight: 0,
+                            display: 'flex',
+                            flexDirection: 'column',
+                            gap: 3,
+                            p: 3,
+                            bg: 'canvas.default',
+                            color: 'fg.default',
+                        }, children: [_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsx(SegmentedControl, { "aria-label": "Output kind", fullWidth: true, children: SNIPPETS.map(entry => (_jsx(SegmentedControl.Button, { selected: entry.id === snippetId, onClick: () => chooseSnippet(entry), children: entry.label }, entry.id))) }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: snippet.about })] }), snippet.chat ? (_jsxs(Box, { sx: {
+                                    flex: '1 1 0',
+                                    minHeight: 0,
+                                    display: 'grid',
+                                    gridTemplateColumns: [
+                                        'minmax(0, 1fr)',
+                                        'minmax(0, 1fr)',
+                                        'minmax(320px, 0.7fr) minmax(0, 1.3fr)',
+                                    ],
+                                    gridTemplateRows: [
+                                        'minmax(420px, auto) minmax(560px, auto)',
+                                        'minmax(420px, auto) minmax(560px, auto)',
+                                        'minmax(0, 1fr)',
+                                    ],
+                                    gap: 3,
+                                    overflow: ['auto', 'auto', 'hidden'],
+                                }, children: [_jsx(Box, { sx: {
+                                            minHeight: 0,
+                                            border: '1px solid',
+                                            borderColor: 'border.default',
+                                            borderRadius: 2,
+                                            overflow: 'hidden',
+                                            bg: 'canvas.default',
+                                        }, children: agentReady && agentId ? (_jsx(LoopEmbed, { serverUrl: serverUrl, target: "local", agentId: agentId, defaultEditor: "none", showHeader: true, plugins: chatPlugins })) : (_jsxs(Box, { sx: {
+                                                height: '100%',
+                                                display: 'flex',
+                                                alignItems: 'center',
+                                                justifyContent: 'center',
+                                                gap: 2,
+                                            }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: "Starting Jupyter output agent\u2026" })] })) }), outputPanels] })) : (_jsxs(_Fragment, { children: [_jsx(Box, { as: "textarea", value: code, onChange: (event) => setCode(event.target.value), spellCheck: false, "aria-label": "Code to run", sx: {
+                                            width: '100%',
+                                            minHeight: '150px',
+                                            p: 2,
+                                            fontFamily: 'mono',
+                                            fontSize: 1,
+                                            borderRadius: 2,
+                                            border: '1px solid',
+                                            borderColor: 'border.default',
+                                            bg: 'canvas.default',
+                                            color: 'fg.default',
+                                            resize: 'vertical',
+                                        } }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Button, { variant: "primary", leadingVisual: PlayIcon, disabled: running || !agentReady || !agentId, onClick: () => void run(code, undefined, snippet.actions ?? []), children: running
+                                                    ? 'Running…'
+                                                    : !agentReady
+                                                        ? 'Starting Jupyter…'
+                                                        : 'Run' }), (running || !agentReady) && _jsx(Spinner, { size: "small" }), execution?.variant && (_jsx(Label, { variant: "secondary", children: execution.variant })), failure && (_jsx(Text, { sx: { color: 'danger.fg', fontSize: 1 }, children: failure }))] }), outputPanels] }))] }))] }) }) }));
+};
+export default A2UiJupyterOutputExample;