@datalayer/agent-runtimes 1.3.58 → 1.3.60

package/lib/examples/AgentDecideExample.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Decide: typed decisions asked of Jev (`cloudflare:wrk/typesafe/jev`), the
+ * typed-decision model, from the chat and from the floating assistant.
+ *
+ * The *Decide* application of the catalogue (agentspecs `apps/decide.yaml`)
+ * in the LOOP workspace, on the Local target: its agent — `example-simple`
+ * with the `decide` tool — runs on the local agent-runtimes server, and
+ * answers a question about a text by asking a typed decision. The floating
+ * assistant beside it offers *Ask a decision* in its balloon: the situation,
+ * the question and its type, asked through the same server's
+ * `/api/v1/configure/inference/decisions`, the route that asks as `decide`
+ * does, with the same token.
+ *
+ * The server needs ai-inference: start it with
+ * `AGENT_RUNTIMES_INFERENCE_PROVIDER_OVERRIDE=datalayer`,
+ * `DATALAYER_AI_INFERENCE_URL=https://r1.datalayer.run` and
+ * `DATALAYER_AI_INFERENCE_API_KEY` set from `DATALAYER_API_KEY`. Another
+ * server than `http://localhost:8765` is named with `?agentRuntimesUrl=`.
+ *
+ * @module examples/AgentDecideExample
+ */
+import { useMemo } from 'react';
+import { configurePlugin } from '@datalayer/reactor';
+import { Heading, Text } from '@primer/react';
+import { Box, setupPrimerPortals } from '@datalayer/primer-addons';
+import { ThemedProvider } from './utils/themedProvider';
+import { resolveExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { AppRenderer, appDatalayerCreatePayload, } from '../loop/apps/AppRenderer';
+import { AssistantCharactersPlugin } from '../loop/plugins/assistant-characters';
+import { LoopAssistantPlugin } from '../loop/plugins/assistant';
+import { APP_CATALOGUE } from '../specs/apps';
+setupPrimerPortals();
+/** The local server: `?agentRuntimesUrl=` when given, else the examples' own. */
+function serverUrlOf() {
+    const named = typeof window === 'undefined'
+        ? null
+        : new URLSearchParams(window.location.search).get('agentRuntimesUrl');
+    return resolveExampleAgentRuntimesUrl('local', named ?? undefined);
+}
+const AgentDecideExample = () => {
+    const app = APP_CATALOGUE['decide'];
+    const serverUrl = useMemo(serverUrlOf, []);
+    // Made once: a new plugin on a render restarts the workspace.
+    const plugins = useMemo(() => [
+        AssistantCharactersPlugin,
+        configurePlugin(LoopAssistantPlugin, {
+            app: app.interface.assistant ?? undefined,
+            decisions: { serverUrl },
+        }),
+    ], [app, serverUrl]);
+    // The Local agent is the application's: created under its id with its
+    // spec, so that the server runs its instructions, its tool and its rule.
+    const localAgent = useMemo(() => ({ createPayload: appDatalayerCreatePayload(app) }), [app]);
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
+                height: '100vh',
+                minHeight: 0,
+                display: 'flex',
+                bg: 'canvas.default',
+            }, children: [_jsx(Box, { sx: { flex: 1, minWidth: 0, minHeight: 0 }, children: _jsx(AppRenderer, { app: app, serverUrl: serverUrl, target: "local", localAgent: localAgent, plugins: plugins }) }), _jsxs(Box, { as: "aside", sx: {
+                        width: 320,
+                        flexShrink: 0,
+                        p: 3,
+                        borderLeft: '1px solid',
+                        borderColor: 'border.default',
+                        overflowY: 'auto',
+                    }, children: [_jsxs(Heading, { as: "h2", sx: { fontSize: 2, mb: 2 }, children: [app.emoji, " Decide"] }), _jsx(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, children: "Typed decisions asked of Jev, the typed-decision model: yes or no with its probability, one of named options, or a score, each with its confidence." }), _jsxs(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, children: [_jsx("strong", { children: "In the chat" }), ": ask \u201CIs this ticket urgent? \u2018Help! My payouts have been failing for 3 days.\u2019\u201D Its agent calls the ", _jsx("code", { children: "decide" }), " tool, a read it does without asking."] }), _jsxs(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, children: [_jsx("strong", { children: "From the assistant" }), ": hover the character below and choose ", _jsx("em", { children: "Ask a decision" }), " \u2014 the situation, the question, and its type. The answer comes back in its balloon."] }), _jsxs(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted' }, children: ["Runs on the local agent-runtimes server at ", serverUrl, ", which asks Jev through ai-inference."] })] })] }) }));
+};
+export default AgentDecideExample;

package/lib/examples/AgentNotificationsExample.js

@@ -51,7 +51,7 @@ const AgentNotificationsInner = ({ onLogout, }) => {
             protocol: 'ag-ui',
             agentSpecId: AGENTSPEC_ID,
             enableSkills: true,
-            tools: [],
+            backendTools: [],
         },
     });
     const [notifications, setNotifications] = useState([]);

package/lib/examples/AgentSkillsExample.js

@@ -74,7 +74,7 @@ const AgentSkillsInner = ({ onLogout }) => {
             protocol: 'ag-ui',
             agentSpecId: AGENTSPEC_ID,
             enableSkills: true,
-            tools: [],
+            backendTools: [],
         },
     });
     const chatAuthToken = token === null ? undefined : token;

package/lib/examples/AgentspecsExample.js

@@ -602,7 +602,7 @@ githubClientId, kaggleToken, }) => {
         setGoal(spec.goal || '');
         setSystemPrompt(spec.systemPrompt || spec.goal || DEFAULT_SYSTEM_PROMPT);
         setSystemPromptCodemodeAddons(spec.systemPromptCodemodeAddons || '');
-        setTools(spec.tools || []);
+        setTools(spec.backendTools || []);
         setSandboxVariant(spec.sandboxVariant || '');
         if (spec.model) {
             setModel(spec.model);
@@ -650,7 +650,7 @@ githubClientId, kaggleToken, }) => {
             protocol: normalizedProtocol,
             systemPrompt: systemPrompt || undefined,
             systemPromptCodemodeAddons: systemPromptCodemodeAddons || undefined,
-            tools,
+            backendTools: tools,
             sandboxVariant: sandboxVariant || undefined,
             skills: selectedSkills,
             mcpServers: selectedMcpServers.map(server => ({
@@ -786,7 +786,7 @@ githubClientId, kaggleToken, }) => {
                 model: model,
                 system_prompt: systemPrompt || DEFAULT_SYSTEM_PROMPT,
                 system_prompt_codemode_addons: systemPromptCodemodeAddons || undefined,
-                tools: tools,
+                backend_tools: tools,
                 sandbox_variant: sandboxVariant || undefined,
                 enable_skills: enableSkills,
                 enable_codemode: enableCodemode,

package/lib/examples/ChatAssistantGalleryExample.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Every representation of the floating assistant, as a gallery (LOOP T-21
+ * to T-27): each character — Datalayer's four, the owl an example plugin
+ * contributes to `loop.assistant.character`, and a test sprite read through
+ * the clippy.js reader — in each state it acts, stepped aside, with its
+ * balloon, in light and dark, moving or still.
+ *
+ * Static data, no agent: it opens without a server or an account.
+ */
+import React from 'react';
+declare const ChatAssistantGalleryExample: React.FC;
+export default ChatAssistantGalleryExample;

package/lib/examples/ChatAssistantGalleryExample.js

@@ -0,0 +1,181 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Every representation of the floating assistant, as a gallery (LOOP T-21
+ * to T-27): each character — Datalayer's four, the owl an example plugin
+ * contributes to `loop.assistant.character`, and a test sprite read through
+ * the clippy.js reader — in each state it acts, stepped aside, with its
+ * balloon, in light and dark, moving or still.
+ *
+ * Static data, no agent: it opens without a server or an account.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { Button, Checkbox, FormControl, Heading, SegmentedControl, Text, } from '@primer/react';
+import { Box, DatalayerThemeProvider, themeConfigs, } from '@datalayer/primer-addons';
+import { ThemedProvider } from './utils/themedProvider';
+import { useExampleThemeStore } from './utils/themeStore';
+import { AssistantStage } from '../chat/assistant/AssistantStage';
+import { useViewportDrag } from '../chat/useViewportDrag';
+import { AssistantGalleryGrid, GalleryObstacle, Still, useGalleryCharacters, } from './utils/AssistantGalleryGrid';
+import { GALLERY_POSES, GALLERY_POSE_LABELS, balloonForPose, sampleApproval, sampleSaying, stateOfPose, } from './utils/assistantGallery';
+const STAGE_SIZE = 96;
+const PANEL_HEIGHT = 420;
+const LEAVE_MS = 700;
+const ARRIVE_MS = 1900;
+const AWAY_WORDS = {
+    none: '',
+    page: 'for now',
+    session: 'for this session',
+    always: 'for good',
+};
+/** One colour mode's panel, with the character on its own stage. */
+function ModePanel({ mode, character, pose, presence, balloon, insist, onToggle, onDismiss, onCallBack, away, replay, }) {
+    const panelRef = useRef(null);
+    const stageRef = useRef(null);
+    const drag = useViewportDrag(stageRef, { whole: true });
+    // Where it stands in the panel: the drag's viewport place, made the
+    // panel's own once, so a scroll does not move it.
+    const [spot, setSpot] = useState({ left: 48, top: PANEL_HEIGHT - 150 });
+    useEffect(() => {
+        const panel = panelRef.current;
+        if (drag.position && panel) {
+            const box = panel.getBoundingClientRect();
+            setSpot({
+                left: drag.position.left - box.left,
+                top: drag.position.top - box.top,
+            });
+        }
+    }, [drag.position]);
+    const state = presence === 'leaving'
+        ? 'goodbye'
+        : presence === 'arriving'
+            ? 'greeting'
+            : stateOfPose(pose);
+    return (_jsxs(Box, { ref: panelRef, "data-gallery-mode": mode, sx: {
+            position: 'relative',
+            flex: '1 1 320px',
+            minWidth: 0,
+            height: PANEL_HEIGHT,
+            bg: 'canvas.default',
+            color: 'fg.default',
+            border: '1px solid',
+            borderColor: 'border.default',
+            borderRadius: 2,
+            overflow: 'visible',
+        }, children: [_jsx(Text, { sx: {
+                    position: 'absolute',
+                    top: 2,
+                    left: 3,
+                    fontSize: 0,
+                    fontWeight: 600,
+                    color: 'fg.muted',
+                    textTransform: 'uppercase',
+                    letterSpacing: '0.04em',
+                }, children: mode }), presence === 'away' ? (_jsxs(Box, { sx: {
+                    position: 'absolute',
+                    left: spot.left,
+                    top: spot.top + STAGE_SIZE / 2 - 16,
+                }, children: [_jsxs(Button, { size: "small", onClick: onCallBack, "data-gallery-call-back": "", children: ["Call ", character.name, " back"] }), _jsxs(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 1 }, children: ["Sent away ", AWAY_WORDS[away], "."] })] })) : (_jsx(AssistantStage, { character: character.character, state: state, size: STAGE_SIZE, place: { position: 'absolute', left: spot.left, top: spot.top }, stageRef: stageRef, onDragStart: drag.onHandlePointerDown, open: false, onToggle: onToggle, balloon: presence === 'here' ? balloon : undefined, insist: insist, onDismiss: onDismiss }, `${character.id}-${replay}`)), pose === 'aside' && presence === 'here' && (_jsx(GalleryObstacle, { sx: {
+                    left: spot.left - 12,
+                    top: spot.top - 12,
+                    width: STAGE_SIZE + 24,
+                    height: STAGE_SIZE + 24,
+                } }))] }));
+}
+/** The panels in the modes asked, each in the examples' theme. */
+function InModes({ modes, stacked = false, children, }) {
+    const { theme } = useExampleThemeStore();
+    const config = themeConfigs[theme] ?? themeConfigs.loop;
+    const shown = modes === 'both' ? ['light', 'dark'] : [modes];
+    return (_jsx(Box, { sx: {
+            display: 'flex',
+            flexDirection: stacked ? 'column' : 'row',
+            gap: 3,
+            flexWrap: 'wrap',
+        }, children: shown.map(mode => (_jsx(Box, { sx: { flex: '1 1 320px', minWidth: 0 }, children: _jsx(DatalayerThemeProvider, { colorMode: mode, theme: config.primerTheme, themeStyles: config.themeStyles, children: children(mode) }) }, mode))) }));
+}
+const ChatAssistantGalleryExample = () => {
+    const { characters, problem } = useGalleryCharacters();
+    const [characterId, setCharacterId] = useState('paperclip');
+    const [pose, setPose] = useState('idle');
+    const [view, setView] = useState('stage');
+    const [modes, setModes] = useState('both');
+    const [still, setStill] = useState(false);
+    const [saying, setSaying] = useState();
+    const [said, setSaid] = useState(0);
+    const [decision, setDecision] = useState();
+    const [presence, setPresence] = useState('here');
+    const [away, setAway] = useState('none');
+    const [replay, setReplay] = useState(0);
+    const character = characters.find(entry => entry.id === characterId) ?? characters[0];
+    // Leaving takes the goodbye's length; arriving, the greeting's.
+    useEffect(() => {
+        if (presence !== 'leaving' && presence !== 'arriving') {
+            return;
+        }
+        const timer = window.setTimeout(() => setPresence(presence === 'leaving' ? 'away' : 'here'), presence === 'leaving' ? LEAVE_MS : ARRIVE_MS);
+        return () => window.clearTimeout(timer);
+    }, [presence]);
+    const sendAway = (choice) => {
+        setAway(choice);
+        setPresence('leaving');
+    };
+    const callBack = () => {
+        setAway('none');
+        setPresence('arriving');
+    };
+    const say = () => {
+        setSaying(said);
+        setSaid(said + 1);
+    };
+    const approval = sampleApproval(() => setDecision('Approved: send_reply.'), () => setDecision('Denied: send_reply.'));
+    const balloon = balloonForPose(pose, {
+        saying: saying === undefined ? undefined : sampleSaying(saying),
+        approval,
+    });
+    const insist = saying !== undefined || pose === 'waiting' || pose === 'paused';
+    return (_jsx(ThemedProvider, { children: _jsx(Box, { sx: {
+                minHeight: '100vh',
+                bg: 'canvas.default',
+                color: 'fg.default',
+                p: 4,
+            }, children: _jsxs(Box, { sx: { maxWidth: 1200, mx: 'auto' }, children: [_jsx(Heading, { as: "h1", sx: { mb: 2 }, children: "Floating assistant gallery" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 3, maxWidth: 760 }, children: ["Every character in every state the floating assistant acts, with its balloon, in light and dark. Datalayer\u2019s four and the owl are what the enabled plugins contribute to", ' ', _jsx("code", { children: "loop.assistant.character" }), "; Pixel is a test sprite of our own, read through the clippy.js reader. No agent is behind it: the words are a sample conversation."] }), _jsxs(Box, { as: "section", "aria-label": "Gallery controls", sx: {
+                            display: 'grid',
+                            gap: 3,
+                            mb: 4,
+                            p: 3,
+                            border: '1px solid',
+                            borderColor: 'border.default',
+                            borderRadius: 2,
+                            bg: 'canvas.subtle',
+                        }, children: [_jsxs(Box, { sx: {
+                                    display: 'flex',
+                                    gap: 3,
+                                    flexWrap: 'wrap',
+                                    alignItems: 'center',
+                                }, children: [_jsxs(SegmentedControl, { "aria-label": "View", children: [_jsx(SegmentedControl.Button, { selected: view === 'stage', onClick: () => setView('stage'), children: "One at a time" }), _jsx(SegmentedControl.Button, { selected: view === 'grid', onClick: () => setView('grid'), "data-gallery-view": "grid", children: "Grid" })] }), _jsx(SegmentedControl, { "aria-label": "Colour mode", children: ['light', 'dark', 'both'].map(option => (_jsx(SegmentedControl.Button, { selected: modes === option, onClick: () => setModes(option), children: option === 'both'
+                                                ? 'Side by side'
+                                                : option === 'light'
+                                                    ? 'Light'
+                                                    : 'Dark' }, option))) }), _jsxs(FormControl, { children: [_jsx(Checkbox, { checked: still, onChange: event => setStill(event.target.checked) }), _jsx(FormControl.Label, { children: "Reduced motion" })] }), _jsx(Button, { onClick: () => setReplay(replay + 1), children: "Replay the motions" })] }), view === 'stage' && (_jsxs(_Fragment, { children: [_jsx(Box, { role: "group", "aria-label": "Character", sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: characters.map(option => (_jsx(Button, { size: "small", variant: option.id === character.id ? 'primary' : 'default', "aria-pressed": option.id === character.id, "data-gallery-character": option.id, onClick: () => setCharacterId(option.id), children: option.name }, option.id))) }), _jsx(Box, { role: "group", "aria-label": "State", sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: GALLERY_POSES.map(option => (_jsx(Button, { size: "small", variant: option === pose ? 'primary' : 'default', "aria-pressed": option === pose, "data-gallery-pose": option, onClick: () => {
+                                                setPose(option);
+                                                setDecision(undefined);
+                                                setReplay(replay + 1);
+                                            }, children: GALLERY_POSE_LABELS[option] }, option))) }), _jsxs(Box, { sx: {
+                                            display: 'flex',
+                                            gap: 2,
+                                            flexWrap: 'wrap',
+                                            alignItems: 'center',
+                                        }, children: [_jsx(Button, { onClick: say, "data-gallery-say": "", children: "Say something" }), saying !== undefined && (_jsx(Button, { variant: "invisible", onClick: () => setSaying(undefined), children: "Hush" })), presence === 'away' ? (_jsx(Button, { onClick: callBack, children: "Call it back" })) : (_jsx(Button, { onClick: () => sendAway('page'), disabled: presence !== 'here', "data-gallery-send-away": "", children: "Send it away" })), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Drag the character to move it; hover it for its own send-away menu." }), decision && (_jsx(Text, { role: "status", sx: { fontSize: 1 }, children: decision }))] })] }))] }), problem && (_jsxs(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mb: 3 }, children: ["The test sprite could not be read: ", problem] })), _jsx(Still, { still: still, children: view === 'stage' ? (_jsx(InModes, { modes: modes, children: mode => (_jsx(ModePanel, { mode: mode, character: character, pose: pose, presence: presence, balloon: balloon, insist: insist, onToggle: () => saying === undefined ? say() : setSaying(undefined), onDismiss: sendAway, onCallBack: callBack, away: away, replay: replay })) })) : (_jsx(InModes, { modes: modes, stacked: true, children: mode => (_jsx(Box, { "data-gallery-mode": mode, sx: {
+                                    bg: 'canvas.default',
+                                    border: '1px solid',
+                                    borderColor: 'border.default',
+                                    borderRadius: 2,
+                                    p: 2,
+                                    overflowX: 'auto',
+                                }, children: _jsx(AssistantGalleryGrid, { characters: characters }, replay) })) })) })] }) }) }));
+};
+export default ChatAssistantGalleryExample;

package/lib/examples/example-selector.js

@@ -88,6 +88,7 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('DecksAgent', () => import('./DecksAgent'), 'A deck beside the chat: the decks plugin in a Loop, and an agent that writes presentations as data.'),
     makeEntry('CellExample', () => import('./CellExample'), 'Simple cell example.'),
     makeEntry('ChatAssistantExample', () => import('./ChatAssistantExample'), 'The floating assistant: the chat as a character on the page.'),
+    makeEntry('ChatAssistantGalleryExample', () => import('./ChatAssistantGalleryExample'), 'Every representation of the floating assistant: each character in each state, its balloon, light and dark, still or moving, one at a time or as a grid.'),
     makeEntry('ChatCustomExample', () => import('./ChatCustomExample'), 'Custom chat experience composition example.'),
     makeEntry('ChatExample', () => import('./ChatExample'), 'Baseline chat integration example.'),
     makeEntry('ChatStandaloneExample', () => import('./ChatStandaloneExample'), 'Standalone chat component usage example.'),
@@ -97,6 +98,7 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('AgentCompactionExample', () => import('./AgentCompactionExample'), 'Set a context token budget and watch history compaction summarize older messages, with live from/to token and timing details.', ['example', 'agent', 'compaction', 'context', 'tokens']),
     makeEntry('AgentCodemodeExample', () => import('./AgentCodemodeExample'), 'Code mode execution and tool orchestration example.'),
     makeEntry('AgentCodeSandboxesExample', () => import('./AgentCodeSandboxesExample'), 'Launch sandbox-variant agent specs and compare code execution across backends.', ['example', 'agent', 'sandbox', 'codemode']),
+    makeEntry('AgentDecideExample', () => import('./AgentDecideExample'), 'Decide: typed decisions asked of Jev — yes or no, a choice, a score — from the chat, where the agent calls decide, and from the floating assistant’s Ask a decision.', ['example', 'agent', 'loop', 'app', 'decisions', 'jev', 'assistant']),
     makeEntry('AgentEvalsExample', () => import('./AgentEvalsExample'), 'Evaluation workflows for agent outputs.'),
     makeEntry('AgentGuardrailsExample', () => import('./AgentGuardrailsExample'), 'Guardrails and safety checks for agent runs.'),
     makeEntry('AgentHooksExample', () => import('./AgentHooksExample'), 'Pre-hooks and post-hooks lifecycle execution example.'),

package/lib/examples/index.d.ts

@@ -15,6 +15,7 @@ export { default as AgUiHumanInTheLoopExample } from './AgUiHumanInTheLoopExampl
 export { default as AgUiSharedStateExample } from './AgUiSharedStateExample';
 export { default as AgUiToolsBasedGenUiExample } from './AgUiToolsBasedGenUiExample';
 export { default as CellExample } from './CellExample';
+export { default as ChatAssistantGalleryExample } from './ChatAssistantGalleryExample';
 export { default as ChatStandaloneExample } from './ChatStandaloneExample';
 export { default as CopilotKitLexicalExample } from './CopilotKitLexicalExample';
 export { default as CopilotKitNotebookExample } from './CopilotKitNotebookExample';
@@ -24,6 +25,7 @@ export { default as AgentCheckpointsExample } from './AgentCheckpointsExample';
 export { default as AgentCompactionExample } from './AgentCompactionExample';
 export { default as AgentCodemodeExample } from './AgentCodemodeExample';
 export { default as AgentCodeSandboxesExample } from './AgentCodeSandboxesExample';
+export { default as AgentDecideExample } from './AgentDecideExample';
 export { default as AgentEvalsExample } from './AgentEvalsExample';
 export { default as AgentGuardrailsExample } from './AgentGuardrailsExample';
 export { default as AgentHooksExample } from './AgentHooksExample';

package/lib/examples/index.js

@@ -21,6 +21,7 @@ export { default as AgUiHumanInTheLoopExample } from './AgUiHumanInTheLoopExampl
 export { default as AgUiSharedStateExample } from './AgUiSharedStateExample';
 export { default as AgUiToolsBasedGenUiExample } from './AgUiToolsBasedGenUiExample';
 export { default as CellExample } from './CellExample';
+export { default as ChatAssistantGalleryExample } from './ChatAssistantGalleryExample';
 export { default as ChatStandaloneExample } from './ChatStandaloneExample';
 export { default as CopilotKitLexicalExample } from './CopilotKitLexicalExample';
 export { default as CopilotKitNotebookExample } from './CopilotKitNotebookExample';
@@ -30,6 +31,7 @@ export { default as AgentCheckpointsExample } from './AgentCheckpointsExample';
 export { default as AgentCompactionExample } from './AgentCompactionExample';
 export { default as AgentCodemodeExample } from './AgentCodemodeExample';
 export { default as AgentCodeSandboxesExample } from './AgentCodeSandboxesExample';
+export { default as AgentDecideExample } from './AgentDecideExample';
 export { default as AgentEvalsExample } from './AgentEvalsExample';
 export { default as AgentGuardrailsExample } from './AgentGuardrailsExample';
 export { default as AgentHooksExample } from './AgentHooksExample';

package/lib/examples/main.js

@@ -70,6 +70,9 @@ const ANONYMOUS_EXAMPLES = new Set([
     // An application beside its computer, on the local agent-runtimes server:
     // nothing allocated on Datalayer, and the machine itself needs no token.
     'LoopAppComputerExample',
+    // Decide, on the local agent-runtimes server as above: Jev is asked
+    // through the server's ai-inference, with the server's own key.
+    'AgentDecideExample',
     // Runs on the browser sandbox: nothing to allocate, nothing to sign into.
     'LoopShellExample',
     // Temporarily anonymous so the Jupyter output surface can be driven and
@@ -83,6 +86,8 @@ const ANONYMOUS_EXAMPLES = new Set([
     // The floating assistant: the character, its balloon and its motions need
     // no runtime; a conversation does, and says so when there is none.
     'ChatAssistantExample',
+    // Every character in every state, from static data: no agent at all.
+    'ChatAssistantGalleryExample',
 ]);
 const getExampleGroup = (id) => {
     if (id === 'AgentspecsExample' ||

package/lib/examples/utils/AssistantGalleryGrid.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The floating assistant's characters, every one in every pose, small, for
+ * a quick visual check (LOOP T-16, T-22, T-24 to T-27): Datalayer's four and
+ * the owl as the enabled plugins contribute them to
+ * `loop.assistant.character`, and a test sprite read through the clippy.js
+ * reader. Each cell is the real `AssistantStage`, set in the grid's flow
+ * rather than fixed to the window; stepped aside is the real `useKeepClear`
+ * stepping it aside from a composer laid over the cell.
+ *
+ * @module examples/utils/AssistantGalleryGrid
+ */
+import type { JSX, ReactNode } from 'react';
+import type { AssistantCharacter } from '../../chat/assistant/characters';
+import type { AssistantCharacterData } from '../../chat/assistant/formats/types';
+/** A character of the gallery: by id, with its name, as contributed. */
+export interface GalleryCharacter {
+    id: string;
+    name: string;
+    character: AssistantCharacter | AssistantCharacterData;
+    /** Where it comes from, as the gallery says it. */
+    from: string;
+}
+/** What the enabled plugins contribute, in contribution order. */
+export declare const CONTRIBUTED_CHARACTERS: readonly GalleryCharacter[];
+/** The id the test sprite is shown under. */
+export declare const SPRITE_CHARACTER_ID = "sprite";
+/**
+ * The gallery's characters: the contributed ones at once, and the test
+ * sprite once its files are read; `ready` once they all are.
+ */
+export declare function useGalleryCharacters(): {
+    characters: readonly GalleryCharacter[];
+    ready: boolean;
+    problem?: string;
+};
+/** Its children without motion, as a reader asking for reduced motion sees them. */
+export declare function Still({ still, children, }: {
+    still: boolean;
+    children: ReactNode;
+}): JSX.Element;
+/**
+ * What the assistant steps aside from (T-27): a composer laid over it. The
+ * stage's own `useKeepClear` finds it and steps aside.
+ */
+export declare function GalleryObstacle({ sx, }: {
+    sx?: Record<string, unknown>;
+}): JSX.Element;
+/** Every character in every pose: a row per character, a column per pose. */
+export declare function AssistantGalleryGrid({ characters, size, }: {
+    characters: readonly GalleryCharacter[];
+    size?: number;
+}): JSX.Element;
+export default AssistantGalleryGrid;

package/lib/examples/utils/AssistantGalleryGrid.js

@@ -0,0 +1,123 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { buildReactorFromPlugins } from '@datalayer/reactor';
+import { AssistantStage } from '../../chat/assistant/AssistantStage';
+import { AssistantCharactersPlugin, assistantCharactersOf, } from '../../loop/plugins/assistant-characters';
+import { OWL_CHARACTER, OwlCharacterPlugin } from './owlCharacterPlugin';
+import { readTestSpriteCharacter } from './testSpriteCharacter';
+import { GALLERY_POSES, GALLERY_POSE_LABELS, stateOfPose, } from './assistantGallery';
+/** The plugins the gallery enables: Datalayer's characters and the owl's. */
+const reactor = buildReactorFromPlugins([
+    AssistantCharactersPlugin,
+    OwlCharacterPlugin,
+]);
+reactor.start();
+/** What the enabled plugins contribute, in contribution order. */
+export const CONTRIBUTED_CHARACTERS = assistantCharactersOf(reactor).map(entry => ({
+    id: entry.id,
+    name: entry.character.name,
+    character: entry.character,
+    from: entry.id === OWL_CHARACTER.id ? 'Example plugin' : 'Datalayer',
+}));
+/** The id the test sprite is shown under. */
+export const SPRITE_CHARACTER_ID = 'sprite';
+/**
+ * The gallery's characters: the contributed ones at once, and the test
+ * sprite once its files are read; `ready` once they all are.
+ */
+export function useGalleryCharacters() {
+    const [sprite, setSprite] = useState();
+    const [problem, setProblem] = useState();
+    useEffect(() => {
+        let cancelled = false;
+        readTestSpriteCharacter().then(read => {
+            if (!cancelled) {
+                setSprite(read);
+            }
+        }, error => {
+            if (!cancelled) {
+                setProblem(error instanceof Error ? error.message : String(error));
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    // The object URL lives as long as the gallery does.
+    useEffect(() => () => {
+        if (sprite) {
+            URL.revokeObjectURL(sprite.sprite);
+        }
+    }, [sprite]);
+    return {
+        characters: sprite
+            ? [
+                ...CONTRIBUTED_CHARACTERS,
+                {
+                    id: SPRITE_CHARACTER_ID,
+                    name: `${sprite.name} (sprite)`,
+                    character: sprite,
+                    from: 'clippy.js reader',
+                },
+            ]
+            : CONTRIBUTED_CHARACTERS,
+        ready: !!sprite || !!problem,
+        problem,
+    };
+}
+/** Its children without motion, as a reader asking for reduced motion sees them. */
+export function Still({ still, children, }) {
+    return (_jsx(Box, { "data-gallery-still": still ? '' : undefined, sx: still ? { '& *': { animation: 'none !important' } } : undefined, children: children }));
+}
+/**
+ * What the assistant steps aside from (T-27): a composer laid over it. The
+ * stage's own `useKeepClear` finds it and steps aside.
+ */
+export function GalleryObstacle({ sx, }) {
+    return (_jsx(Box, { "data-chat-composer": "", "aria-label": "A composer over the assistant", sx: {
+            position: 'absolute',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            border: '1px dashed',
+            borderColor: 'border.default',
+            borderRadius: 2,
+            bg: 'canvas.subtle',
+            color: 'fg.muted',
+            fontSize: 0,
+            textAlign: 'center',
+            p: 1,
+            ...sx,
+        }, children: "composer" }));
+}
+function GalleryCell({ character, pose, size, }) {
+    const stageRef = useRef(null);
+    return (_jsxs(Box, { "data-gallery-cell": `${character.id}-${pose}`, sx: {
+            position: 'relative',
+            width: size + 16,
+            height: size + 16,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+        }, children: [_jsx(AssistantStage, { character: character.character, state: stateOfPose(pose), size: size, place: { position: 'relative', zIndex: 0 }, stageRef: stageRef, onDragStart: () => undefined, open: false, onToggle: () => undefined, onDismiss: () => undefined }), pose === 'aside' && _jsx(GalleryObstacle, { sx: { inset: 0 } })] }));
+}
+/** Every character in every pose: a row per character, a column per pose. */
+export function AssistantGalleryGrid({ characters, size = 48, }) {
+    return (_jsxs(Box, { as: "table", "data-assistant-gallery-grid": "", sx: {
+            borderCollapse: 'collapse',
+            color: 'fg.default',
+            '& th': {
+                fontSize: 0,
+                fontWeight: 600,
+                color: 'fg.muted',
+                px: 1,
+                py: 1,
+                textAlign: 'center',
+                whiteSpace: 'nowrap',
+            },
+            '& td': { p: 0, textAlign: 'center' },
+        }, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", {}), GALLERY_POSES.map(pose => (_jsx("th", { scope: "col", children: GALLERY_POSE_LABELS[pose] }, pose)))] }) }), _jsx("tbody", { children: characters.map(character => (_jsxs("tr", { children: [_jsxs(Box, { as: "th", scope: "row", sx: { textAlign: 'left !important', pr: '12px !important' }, children: [_jsx(Text, { sx: { display: 'block', color: 'fg.default' }, children: character.name }), _jsx(Text, { sx: { fontWeight: 400 }, children: character.from })] }), GALLERY_POSES.map(pose => (_jsx("td", { children: _jsx(GalleryCell, { character: character, pose: pose, size: size }) }, pose)))] }, character.id))) })] }));
+}
+export default AssistantGalleryGrid;

package/lib/examples/utils/assistantGallery.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What the floating assistant's gallery shows (LOOP T-21 to T-27): every
+ * state a character acts (T-22), and stepped aside (T-27), with the balloon
+ * each one says — the agent's latest saying (T-23), an approval to answer,
+ * or that it is paused. Static data only: no agent, no server.
+ *
+ * @module examples/utils/assistantGallery
+ */
+import type { AssistantStageProps } from '../../chat/assistant/AssistantStage';
+import { type AssistantState, type BalloonApproval } from '../../chat/assistant/state';
+/** What the gallery poses a character in: a state, or stepped aside. */
+export type GalleryPose = AssistantState | 'aside';
+/** Every state, in the order an assistant lives them, then stepped aside. */
+export declare const GALLERY_POSES: readonly ["idle", "greeting", "thinking", "working", "waiting", "speaking", "paused", "aside", "goodbye"];
+/** How the gallery names each pose. */
+export declare const GALLERY_POSE_LABELS: Record<GalleryPose, string>;
+/** The state the stage acts for a pose: aside, it is idle under what covers it. */
+export declare function stateOfPose(pose: GalleryPose): AssistantState;
+/**
+ * What the agent said, as a conversation would hold it: each entry is read
+ * by `latestSaying`, as the floating assistant reads the chat — Markdown made
+ * plain, a long answer cut with *Open the conversation*.
+ */
+export declare const SAMPLE_CONVERSATIONS: readonly (readonly unknown[])[];
+/** The saying of sample `index` (wrapping), as the balloon shows it. */
+export declare function sampleSaying(index: number): {
+    text: string;
+    more: boolean;
+};
+/** The approval the gallery waits on (T-23): answered in the balloon. */
+export declare function sampleApproval(onApprove: () => void, onDeny: () => void): BalloonApproval;
+/**
+ * The balloon for a pose: waiting holds the approval, paused says so, and
+ * any other pose says the sample's words when asked to (`saying`).
+ */
+export declare function balloonForPose(pose: GalleryPose, { saying, approval, }: {
+    saying?: {
+        text: string;
+        more: boolean;
+    };
+    approval: BalloonApproval;
+}): AssistantStageProps['balloon'];