@datalayer/agent-runtimes 1.3.29 → 1.3.32

package/lib/chat/prompt/InputPrompt.js

@@ -29,7 +29,7 @@ const EMPTY_ID_SET = new Set();
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export function InputPrompt({ input, setInput, isLoading, kernelStatus, connectionConfirmed, placeholder, typingSuggestions, autoFocus, focusTrigger, padding, placement, floatingAnchor = 'bottom', draggable = false, container, footerExtras, leadingPanel, trailingPanel, onSend, onStop, disableInputPrompt = false, promptVariant, mentionableAgents, promptHistory, headerContent, showAgentsMenu = false, showInlineAgentsMenu = true, agents = [], selectedAgentId, onSelectAgent, showTokenUsage, showContextRing = false, agentUsage, showModelSelector, showToolsMenu, showSkillsMenu, showSuggestionsMenu = true, suggestions, codemodeEnabled, onToggleCodemode, isA2AProtocol, hasConfigData, hasSkillsData, configLoading = false, models = [], selectedModel = '', onModelSelect = () => { }, availableTools = [], mcpServers = [], enabledMcpTools = EMPTY_TOOL_MAP, enabledMcpToolCount = 0, onToggleMcpTool = () => { }, onToggleAllMcpServerTools = () => { }, approvedMcpTools = EMPTY_TOOL_MAP, onToggleMcpToolApproval = () => { }, skills = [], skillsLoading = false, enabledSkills = EMPTY_ID_SET, onToggleSkill = () => { }, onToggleAllSkills = () => { }, approvedSkills = EMPTY_ID_SET, onToggleSkillApproval = () => { }, apiBase, authToken, mcpStatusData, }) {
+export function InputPrompt({ input, setInput, isLoading, kernelStatus, connectionConfirmed, placeholder, typingSuggestions, autoFocus, focusTrigger, padding, placement, floatingAnchor = 'bottom', draggable = false, container, footerExtras, leadingPanel, trailingPanel, onSend, onStop, disableInputPrompt = false, promptVariant, mentionableAgents, promptHistory, headerContent, showAgentsMenu = false, showInlineAgentsMenu = true, agents = [], selectedAgentId, onSelectAgent, showTokenUsage, showContextRing = false, agentUsage, showModelSelector, showToolsMenu, showSkillsMenu, showSuggestionsMenu = true, suggestions, codemodeEnabled, onToggleCodemode, isA2AProtocol, hasConfigData, hasSkillsData, configLoading = false, models = [], decisions, selectedModel = '', onModelSelect = () => { }, availableTools = [], mcpServers = [], enabledMcpTools = EMPTY_TOOL_MAP, enabledMcpToolCount = 0, onToggleMcpTool = () => { }, onToggleAllMcpServerTools = () => { }, approvedMcpTools = EMPTY_TOOL_MAP, onToggleMcpToolApproval = () => { }, skills = [], skillsLoading = false, enabledSkills = EMPTY_ID_SET, onToggleSkill = () => { }, onToggleAllSkills = () => { }, approvedSkills = EMPTY_ID_SET, onToggleSkillApproval = () => { }, apiBase, authToken, mcpStatusData, }) {
     const isKernelBusy = kernelStatus === 'busy';
     /*
      * Each menu is offered when it is switched on *and* has something behind it.
@@ -143,7 +143,7 @@ export function InputPrompt({ input, setInput, isLoading, kernelStatus, connecti
                             minHeight: 36,
                             bordered: true,
                             subtle: true,
-                            content: (_jsx(_Fragment, { children: anyOffered || extrasOffered || suggestionsOffered ? (_jsxs(_Fragment, { children: [agentsOffered && (_jsx(AgentsMenu, { agents: agents, selectedAgentId: selectedAgentId, onSelectAgent: onSelectAgent })), toolsOffered && (_jsx(ToolsMenu, { codemodeEnabled: codemodeEnabled, onToggleCodemode: onToggleCodemode, mcpServers: mcpServers, enabledMcpTools: enabledMcpTools, enabledMcpToolCount: enabledMcpToolCount, onToggleMcpTool: onToggleMcpTool, onToggleAllMcpServerTools: onToggleAllMcpServerTools, approvedMcpTools: approvedMcpTools, onToggleMcpToolApproval: onToggleMcpToolApproval, availableTools: availableTools })), skillsOffered && (_jsx(SkillsMenu, { skills: skills, skillsLoading: skillsLoading, enabledSkills: enabledSkills, onToggleSkill: onToggleSkill, onToggleAllSkills: onToggleAllSkills, approvedSkills: approvedSkills, onToggleSkillApproval: onToggleSkillApproval })), modelsOffered && (_jsx(ModelSelector, { models: models, selectedModel: selectedModel, onModelSelect: onModelSelect, isA2AProtocol: isA2AProtocol })), suggestionsOffered && (_jsx(SuggestionsMenu, { suggestions: suggestionItems, onPick: text => {
+                            content: (_jsx(_Fragment, { children: anyOffered || extrasOffered || suggestionsOffered ? (_jsxs(_Fragment, { children: [agentsOffered && (_jsx(AgentsMenu, { agents: agents, selectedAgentId: selectedAgentId, onSelectAgent: onSelectAgent })), toolsOffered && (_jsx(ToolsMenu, { codemodeEnabled: codemodeEnabled, onToggleCodemode: onToggleCodemode, mcpServers: mcpServers, enabledMcpTools: enabledMcpTools, enabledMcpToolCount: enabledMcpToolCount, onToggleMcpTool: onToggleMcpTool, onToggleAllMcpServerTools: onToggleAllMcpServerTools, approvedMcpTools: approvedMcpTools, onToggleMcpToolApproval: onToggleMcpToolApproval, availableTools: availableTools })), skillsOffered && (_jsx(SkillsMenu, { skills: skills, skillsLoading: skillsLoading, enabledSkills: enabledSkills, onToggleSkill: onToggleSkill, onToggleAllSkills: onToggleAllSkills, approvedSkills: approvedSkills, onToggleSkillApproval: onToggleSkillApproval })), modelsOffered && (_jsx(ModelSelector, { models: models, decisions: decisions, selectedModel: selectedModel, onModelSelect: onModelSelect, isA2AProtocol: isA2AProtocol })), suggestionsOffered && (_jsx(SuggestionsMenu, { suggestions: suggestionItems, onPick: text => {
                                                 setInput(text);
                                                 setPickedFocus(n => n + 1);
                                             } })), extrasOffered && (_jsx(Box, { sx: {

package/lib/chat/prompt/InputPromptBase.js

@@ -192,7 +192,7 @@ export function InputPromptBase({ variant = 'lexical', placeholder = 'Ask anythi
             , { 
                 // Named so the turn-end refocus can ask whether the caret is already
                 // somewhere inside this prompt before it reaches for it.
-                ref: containerRef, onFocusCapture: () => {
+                ref: containerRef, "data-chat-composer": "", onFocusCapture: () => {
                     if (selfFocused.current) {
                         selfFocused.current = false;
                         return;

package/lib/chat/prompt/menus/ModelSelector.d.ts

@@ -1,6 +1,18 @@
 import type { ModelConfig } from '../../../types';
-export declare function ModelSelector({ models, selectedModel, onModelSelect, isA2AProtocol, }: {
+import type { Decisions } from '../../base/modelChoice';
+/**
+ * The typed-decision models, read-only under the models.
+ *
+ * A decision asks them through `/decisions`; an agent cannot run on one, so
+ * no row here selects anything. Each says so, in the runtime's sentence, and
+ * why it cannot be used when it cannot — the same rule as the models above.
+ */
+export declare function DecisionsGroup({ decisions }: {
+    decisions: Decisions;
+}): import("react").JSX.Element;
+export declare function ModelSelector({ models, decisions, selectedModel, onModelSelect, isA2AProtocol, }: {
     models: ModelConfig[];
+    decisions?: Decisions;
     selectedModel: string;
     onModelSelect: (modelId: string) => void;
     isA2AProtocol: boolean;

package/lib/chat/prompt/menus/ModelSelector.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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.
@@ -11,7 +11,19 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text, Button, ActionMenu, ActionList, Tooltip } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { AiModelIcon } from '@primer/octicons-react';
-export function ModelSelector({ models, selectedModel, onModelSelect, isA2AProtocol, }) {
+/**
+ * The typed-decision models, read-only under the models.
+ *
+ * A decision asks them through `/decisions`; an agent cannot run on one, so
+ * no row here selects anything. Each says so, in the runtime's sentence, and
+ * why it cannot be used when it cannot — the same rule as the models above.
+ */
+export function DecisionsGroup({ decisions }) {
+    return (_jsxs(ActionList.Group, { selectionVariant: false, children: [_jsx(ActionList.GroupHeading, { children: "Decisions" }), decisions.models.map(model => (_jsxs(ActionList.Item, { disabled: true, sx: { color: 'fg.muted' }, children: [model.name, _jsx(ActionList.Description, { variant: "block", children: model.isAvailable === false
+                            ? `${model.unavailableReason ?? 'Not usable here'} · ${decisions.note}`
+                            : decisions.note })] }, model.id)))] }));
+}
+export function ModelSelector({ models, decisions, selectedModel, onModelSelect, isA2AProtocol, }) {
     const active = models.find(model => model.id === selectedModel);
     /*
      * A count, not a name — the same trigger as tools, skills, agents and
@@ -28,7 +40,7 @@ export function ModelSelector({ models, selectedModel, onModelSelect, isA2AProto
             alignItems: 'flex-end',
         }, children: [_jsxs(ActionMenu, { children: [_jsx(ActionMenu.Anchor, { children: _jsx(Tooltip, { text: `Model — ${summary}`, direction: "n", children: _jsx(Button, { type: "button", variant: "invisible", size: "small", "aria-label": `Model — ${summary}`, leadingVisual: AiModelIcon, disabled: isA2AProtocol, sx: isA2AProtocol
                                     ? { opacity: 0.5, cursor: 'not-allowed' }
-                                    : undefined, children: _jsx(Text, { sx: { fontSize: 0 }, children: models.length }) }) }) }), _jsx(ActionMenu.Overlay, { side: "outside-top", align: "end", children: _jsx(ActionList, { selectionVariant: "single", children: models.map(modelItem => (_jsxs(ActionList.Item, { selected: selectedModel === modelItem.id, onSelect: () => onModelSelect(modelItem.id), disabled: modelItem.isAvailable === false || isA2AProtocol, sx: modelItem.isAvailable === false
-                                    ? { color: 'fg.muted' }
-                                    : undefined, children: [modelItem.name, modelItem.isAvailable === false && (_jsx(ActionList.Description, { variant: "block", children: modelItem.unavailableReason ?? 'Missing API key' }))] }, modelItem.id))) }) })] }), isA2AProtocol && (_jsx(Text, { sx: { fontSize: 0, color: 'attention.fg', mt: 1 }, children: "A2A: Model set by agent config" }))] }));
+                                    : undefined, children: _jsx(Text, { sx: { fontSize: 0 }, children: models.length }) }) }) }), _jsx(ActionMenu.Overlay, { side: "outside-top", align: "end", children: _jsxs(ActionList, { selectionVariant: "single", children: [models.map(modelItem => (_jsxs(ActionList.Item, { selected: selectedModel === modelItem.id, onSelect: () => onModelSelect(modelItem.id), disabled: modelItem.isAvailable === false || isA2AProtocol, sx: modelItem.isAvailable === false
+                                        ? { color: 'fg.muted' }
+                                        : undefined, children: [modelItem.name, modelItem.isAvailable === false && (_jsx(ActionList.Description, { variant: "block", children: modelItem.unavailableReason ?? 'Missing API key' }))] }, modelItem.id))), decisions && decisions.models.length > 0 && (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsx(DecisionsGroup, { decisions: decisions })] }))] }) })] }), isA2AProtocol && (_jsx(Text, { sx: { fontSize: 0, color: 'attention.fg', mt: 1 }, children: "A2A: Model set by agent config" }))] }));
 }

package/lib/chat/useViewportDrag.d.ts

@@ -3,7 +3,15 @@ export type DragPosition = {
     left: number;
     top: number;
 } | null;
-export declare function useViewportDrag(boxRef: React.RefObject<HTMLElement | null>): {
+export interface ViewportDragOptions {
+    /**
+     * Keep the whole box inside the viewport, not only a margin of it: the
+     * floating assistant's character, whose balloon and conversation open
+     * from where it stands (LOOP T-23).
+     */
+    whole?: boolean;
+}
+export declare function useViewportDrag(boxRef: React.RefObject<HTMLElement | null>, { whole }?: ViewportDragOptions): {
     position: DragPosition;
     onHandlePointerDown: (event: React.PointerEvent<HTMLElement>) => void;
     reset: () => void;

package/lib/chat/useViewportDrag.js

@@ -17,7 +17,7 @@
 import { useCallback, useRef, useState } from 'react';
 /** How much of the box must stay inside the viewport. */
 const MARGIN = 24;
-export function useViewportDrag(boxRef) {
+export function useViewportDrag(boxRef, { whole = false } = {}) {
     const [position, setPosition] = useState(null);
     /* Where the pointer took hold, so the box moves by the pointer's delta
        rather than snapping its corner to the cursor. */
@@ -39,8 +39,8 @@ export function useViewportDrag(boxRef) {
             if (!grip.current) {
                 return;
             }
-            const left = Math.min(Math.max(moved.clientX - grip.current.dx, MARGIN - rect.width), window.innerWidth - MARGIN);
-            const top = Math.min(Math.max(moved.clientY - grip.current.dy, 0), window.innerHeight - MARGIN);
+            const left = Math.min(Math.max(moved.clientX - grip.current.dx, whole ? 0 : MARGIN - rect.width), window.innerWidth - (whole ? rect.width : MARGIN));
+            const top = Math.min(Math.max(moved.clientY - grip.current.dy, 0), window.innerHeight - (whole ? rect.height : MARGIN));
             setPosition({ left, top });
         };
         const up = () => {
@@ -53,7 +53,7 @@ export function useViewportDrag(boxRef) {
         handle.addEventListener('pointerup', up);
         handle.addEventListener('pointercancel', up);
         event.preventDefault();
-    }, [boxRef]);
+    }, [boxRef, whole]);
     /** Back to wherever the box starts: called when the mode changes. */
     const reset = useCallback(() => setPosition(null), []);
     return { position, onHandlePointerDown, reset };

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

@@ -1,3 +1,5 @@
 export * from './A2uiMarkdownProvider';
 export * from './A2uiSurfaceComposed';
 export * from './styles';
+export * from './visibleWhen';
+export * from './visibility';

package/lib/components/a2ui/index.js

@@ -5,3 +5,5 @@
 export * from './A2uiMarkdownProvider';
 export * from './A2uiSurfaceComposed';
 export * from './styles';
+export * from './visibleWhen';
+export * from './visibility';

package/lib/components/a2ui/visibility.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What `visible_when` is, without the renderer: the key and the rule, for
+ * whatever writes or checks a surface (the Studio's Canvas) as well as for
+ * what draws it (`visibleWhen`).
+ *
+ * @module components/a2ui/visibility
+ */
+/** The key any block may carry to be shown only under a condition. */
+export declare const VISIBLE_WHEN = "visible_when";
+/**
+ * Whether a block whose condition resolved to `value` is shown: `true`, or a
+ * value that is not empty. `false`, `''`, `0`, `null`, an empty list, or
+ * nothing published at the path yet hide it.
+ */
+export declare function isShown(value: unknown): boolean;

package/lib/components/a2ui/visibility.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What `visible_when` is, without the renderer: the key and the rule, for
+ * whatever writes or checks a surface (the Studio's Canvas) as well as for
+ * what draws it (`visibleWhen`).
+ *
+ * @module components/a2ui/visibility
+ */
+/** The key any block may carry to be shown only under a condition. */
+export const VISIBLE_WHEN = 'visible_when';
+/**
+ * Whether a block whose condition resolved to `value` is shown: `true`, or a
+ * value that is not empty. `false`, `''`, `0`, `null`, an empty list, or
+ * nothing published at the path yet hide it.
+ */
+export function isShown(value) {
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    return Boolean(value);
+}

package/lib/components/a2ui/visibleWhen.d.ts

@@ -0,0 +1,17 @@
+import { type ReactComponentImplementation } from '@a2ui/react/v0_9';
+import { Catalog } from '@a2ui/web_core/v0_9';
+/**
+ * Whether a node's resolved properties let it be drawn: no condition, or one
+ * that holds. A2UI resolves a dynamic property to a binding whether the block
+ * gave it or not; a path's is writable, and its value may be nothing yet,
+ * which hides the block. A literal or a function call that resolved to
+ * nothing is a block without a condition.
+ */
+export declare function nodeIsShown(props: Record<string, unknown>): boolean;
+/** A component, its schema declaring `visible_when`, drawn behind the guard. */
+export declare function withVisibleWhen(component: ReactComponentImplementation): ReactComponentImplementation;
+/**
+ * The catalog Datalayer's renderer draws from: A2UI's basic catalog, under
+ * its own id — the payloads name it — with `visible_when` on every component.
+ */
+export declare const datalayerCatalog: Catalog<ReactComponentImplementation, import("@a2ui/web_core/v0_9").FunctionImplementation>;

package/lib/components/a2ui/visibleWhen.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { basicCatalog, useSignalValue, } from '@a2ui/react/v0_9';
+import { Catalog, DynamicBooleanSchema, ResolvedBinding, isWritable, } from '@a2ui/web_core/v0_9';
+import { VISIBLE_WHEN, isShown } from './visibility';
+/**
+ * Whether a node's resolved properties let it be drawn: no condition, or one
+ * that holds. A2UI resolves a dynamic property to a binding whether the block
+ * gave it or not; a path's is writable, and its value may be nothing yet,
+ * which hides the block. A literal or a function call that resolved to
+ * nothing is a block without a condition.
+ */
+export function nodeIsShown(props) {
+    const condition = props[VISIBLE_WHEN];
+    if (!(condition instanceof ResolvedBinding)) {
+        throw new Error(`${VISIBLE_WHEN} resolved to ${String(condition)}, not a binding: the catalog's schema does not declare it.`);
+    }
+    if (isWritable(condition)) {
+        return isShown(condition.value);
+    }
+    return condition.value === undefined || isShown(condition.value);
+}
+const VISIBLE_WHEN_SCHEMA = DynamicBooleanSchema.describe('REF:#/$defs/DynamicBoolean|Datalayer: the block is shown only while this is true or not empty — a path the application publishes.').optional();
+/** A component, its schema declaring `visible_when`, drawn behind the guard. */
+export function withVisibleWhen(component) {
+    const View = component.view;
+    if (!View) {
+        throw new Error(`${component.name} has no node view: visible_when is read from the node, and A2uiSurface draws through it.`);
+    }
+    // A zod object: what every basic component's schema is.
+    const schema = component.schema;
+    if (!schema.shape || typeof schema.extend !== 'function') {
+        throw new Error(`${component.name}'s schema is not an object: visible_when cannot be declared on it.`);
+    }
+    if (VISIBLE_WHEN in schema.shape) {
+        throw new Error(`${component.name} already declares ${VISIBLE_WHEN}.`);
+    }
+    const Guarded = ({ node, buildChild }) => {
+        const props = useSignalValue(node.props);
+        return nodeIsShown(props) ? (_jsx(View, { node: node, buildChild: buildChild })) : null;
+    };
+    Guarded.displayName = `${component.name}.visibleWhen`;
+    return {
+        ...component,
+        schema: schema.extend({ [VISIBLE_WHEN]: VISIBLE_WHEN_SCHEMA }),
+        // A2uiSurface draws through the view; `render` is only its fallback for
+        // a component without one, which this one is not.
+        view: Guarded,
+    };
+}
+/**
+ * The catalog Datalayer's renderer draws from: A2UI's basic catalog, under
+ * its own id — the payloads name it — with `visible_when` on every component.
+ */
+export const datalayerCatalog = new Catalog(basicCatalog.id, basicCatalog.protocolVersion, [...basicCatalog.components.values()].map(withVisibleWhen), [...basicCatalog.functions.values()], basicCatalog.themeSchema, basicCatalog.instructions);

package/lib/examples/ChatAssistantExample.d.ts

@@ -2,6 +2,10 @@
  * The floating assistant (LOOP T-21 to T-27): the chat as a character on the
  * page, after the Office Assistant — Datalayer's own characters, chosen
  * here, acting out what the agent does and speaking in a balloon.
+ *
+ * The characters offered are what the enabled plugins contribute to
+ * `loop.assistant.character` (T-24): Datalayer's four, and an owl from a
+ * small example plugin (`utils/owlCharacterPlugin`).
  */
 import React from 'react';
 declare const ChatAssistantExample: React.FC;

package/lib/examples/ChatAssistantExample.js

@@ -7,14 +7,31 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * The floating assistant (LOOP T-21 to T-27): the chat as a character on the
  * page, after the Office Assistant — Datalayer's own characters, chosen
  * here, acting out what the agent does and speaking in a balloon.
+ *
+ * The characters offered are what the enabled plugins contribute to
+ * `loop.assistant.character` (T-24): Datalayer's four, and an owl from a
+ * small example plugin (`utils/owlCharacterPlugin`).
  */
 import { useState } from 'react';
+import { buildReactorFromPlugins } from '@datalayer/reactor';
 import { Button, Heading, Text } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
-import { ASSISTANT_CHARACTERS } from '../chat/assistant/characters';
+import { AssistantCharactersPlugin, assistantCharacterNamed, assistantCharactersOf, } from '../loop/plugins/assistant-characters';
+import { OwlCharacterPlugin } from './utils/owlCharacterPlugin';
 import { readAcsCharacter, readClippyCharacter, } from '../chat/assistant/formats';
+/** The plugins this page enables: Datalayer's characters and the owl's. */
+const reactor = buildReactorFromPlugins([
+    AssistantCharactersPlugin,
+    OwlCharacterPlugin,
+]);
+reactor.start();
+/** The catalogue: what the enabled plugins contribute. */
+const CATALOGUE = assistantCharactersOf(reactor).map(entry => ({
+    id: entry.id,
+    name: entry.character.name,
+}));
 /**
  * A character file a person picked, read in the page (T-26): one `.acs`, or
  * a clippy.js character's `agent.js` and `map.png` (and its sounds file).
@@ -37,12 +54,16 @@ async function readPicked(files) {
     });
 }
 const ChatAssistantExample = () => {
-    const [character, setCharacter] = useState(ASSISTANT_CHARACTERS[0].id);
+    const [character, setCharacter] = useState('paperclip');
+    // A character chosen by id is the one its plugin contributes.
+    const drawn = typeof character === 'string'
+        ? assistantCharacterNamed(reactor, character)
+        : character;
     const [loadError, setLoadError] = useState();
-    return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: { minHeight: '100vh', bg: 'canvas.default', p: 4 }, children: [_jsxs(Box, { sx: { maxWidth: 720, mx: 'auto' }, children: [_jsx(Heading, { as: "h1", sx: { mb: 2 }, children: "Floating assistant" }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', mb: 3 }, children: "The chat as a character on the page. It greets you, acts out what the agent is doing, and says the agent\u2019s words in a balloon while the conversation is closed. Click it to talk, drag it to move it, hover it to send it away." }), _jsx(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: ASSISTANT_CHARACTERS.map(option => (_jsx(Button, { variant: option.id === character ? 'primary' : 'default', onClick: () => {
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: { minHeight: '100vh', bg: 'canvas.default', p: 4 }, children: [_jsxs(Box, { sx: { maxWidth: 720, mx: 'auto' }, children: [_jsx(Heading, { as: "h1", sx: { mb: 2 }, children: "Floating assistant" }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', mb: 3 }, children: "The chat as a character on the page. It greets you, acts out what the agent is doing, and says the agent\u2019s words in a balloon while the conversation is closed. Click it to talk, drag it to move it, hover it to send it away." }), _jsx(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: CATALOGUE.map(option => (_jsx(Button, { variant: option.id === character ? 'primary' : 'default', onClick: () => {
                                     setCharacter(option.id);
                                     setLoadError(undefined);
-                                }, "aria-pressed": option.id === character, children: option.name }, option.id))) }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "A character you bring" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: ["The characters of Microsoft Office \u2014 Clippy, Merlin, Links and the others \u2014 are Microsoft\u2019s. Load only a character file you have the right to use: a Microsoft Agent ", _jsx("code", { children: ".acs" }), " file, or a clippy.js character\u2019s ", _jsx("code", { children: "agent.js" }), " and map image. It is read in this page and sent nowhere."] }), _jsx("input", { type: "file", multiple: true, accept: ".acs,.js,.png,.gif,.webp,.jpg,.jpeg", "aria-label": "Character files", onChange: async (event) => {
+                                }, "aria-pressed": option.id === character, "data-assistant-character": option.id, children: option.name }, option.id))) }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "A character you bring" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: ["The characters of Microsoft Office \u2014 Clippy, Merlin, Links and the others \u2014 are Microsoft\u2019s. Load only a character file you have the right to use: a Microsoft Agent ", _jsx("code", { children: ".acs" }), " file, or a clippy.js character\u2019s ", _jsx("code", { children: "agent.js" }), " and map image. It is read in this page and sent nowhere."] }), _jsx("input", { type: "file", multiple: true, accept: ".acs,.js,.png,.gif,.webp,.jpg,.jpeg", "aria-label": "Character files", onChange: async (event) => {
                                         const files = Array.from(event.target.files ?? []);
                                         if (!files.length) {
                                             return;
@@ -54,6 +75,6 @@ const ChatAssistantExample = () => {
                                         catch (error) {
                                             setLoadError(error instanceof Error ? error.message : String(error));
                                         }
-                                    } }), loadError && (_jsx(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mt: 2 }, children: loadError })), typeof character !== 'string' && (_jsxs(Text, { as: "p", sx: { mt: 2 }, children: ["Playing ", character.name, "."] }))] })] }), _jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: character, protocol: "vercel-ai", endpoint: "http://127.0.0.1:8765/api/v1/vercel-ai/assistant", title: "Assistant", description: "Hello! Ask me anything about this page.", position: "bottom-right", useStore: false }, typeof character === 'string' ? character : character.sprite)] }) }));
+                                    } }), loadError && (_jsx(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mt: 2 }, children: loadError })), typeof character !== 'string' && (_jsxs(Text, { as: "p", sx: { mt: 2 }, children: ["Playing ", character.name, "."] }))] })] }), _jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: drawn, protocol: "vercel-ai", endpoint: "http://127.0.0.1:8765/api/v1/vercel-ai/assistant", title: "Assistant", description: "Hello! Ask me anything about this page.", position: "bottom-right", useStore: false }, typeof character === 'string' ? character : character.sprite)] }) }));
 };
 export default ChatAssistantExample;

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

@@ -0,0 +1,7 @@
+import type { AssistantCharacter } from '../../chat/assistant/characters';
+/** The owl, as the example plugin contributes it. */
+export declare const OWL_CHARACTER: AssistantCharacter;
+export declare const OWL_CHARACTER_PLUGIN_NAME = "@datalayer/example-plugin-owl-character";
+/** The example plugin: one character, contributed to the point. */
+export declare const OwlCharacterPlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;
+export default OwlCharacterPlugin;

package/lib/examples/utils/owlCharacterPlugin.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { contribution, definePlugin } from '@datalayer/reactor';
+import { LoopAssistantCharacter } from '../../loop/core';
+const OWL = {
+    light: {
+        feathers: '#8A5A3C',
+        belly: '#E9D3B8',
+        tufts: '#6B4329',
+        beak: '#E0A54A',
+        eye: '#FFFFFF',
+        ring: '#1D1D1F',
+        pupil: '#1D1D1F',
+    },
+    dark: {
+        feathers: '#C08B66',
+        belly: '#F1E1CC',
+        tufts: '#D9A57F',
+        beak: '#F8D469',
+        eye: '#F5F5F7',
+        ring: '#1D1D1F',
+        pupil: '#131314',
+    },
+};
+function Owl({ size, mode = 'light', }) {
+    const c = OWL[mode];
+    return (_jsx("svg", { width: size, height: size, viewBox: "0 0 96 96", role: "img", "aria-label": "Owl", "data-assistant-mode": mode, children: _jsxs("g", { className: "assistant-body", children: [_jsx("path", { d: "M26 30 L22 10 L40 22 Z", fill: c.tufts }), _jsx("path", { d: "M70 30 L74 10 L56 22 Z", fill: c.tufts }), _jsx("ellipse", { cx: 48, cy: 54, rx: 28, ry: 34, fill: c.feathers }), _jsx("ellipse", { cx: 48, cy: 66, rx: 17, ry: 20, fill: c.belly }), [34, 62].map(x => (_jsx("circle", { cx: x, cy: 40, r: 11, fill: c.eye, stroke: c.ring, strokeWidth: 1.5 }, x))), _jsxs("g", { className: "assistant-pupils", children: [_jsx("circle", { cx: 35, cy: 41, r: 5, fill: c.pupil }), _jsx("circle", { cx: 63, cy: 41, r: 5, fill: c.pupil })] }), _jsxs("g", { className: "assistant-lids", children: [_jsx("ellipse", { cx: 34, cy: 40, rx: 11.5, ry: 11.5, fill: c.feathers }), _jsx("ellipse", { cx: 62, cy: 40, rx: 11.5, ry: 11.5, fill: c.feathers })] }), _jsx("path", { className: "assistant-mouth", d: "M44 50 L52 50 L48 58 Z", fill: c.beak })] }) }));
+}
+/** The owl, as the example plugin contributes it. */
+export const OWL_CHARACTER = {
+    id: 'owl',
+    name: 'Owl',
+    Drawing: Owl,
+};
+export const OWL_CHARACTER_PLUGIN_NAME = '@datalayer/example-plugin-owl-character';
+/** The example plugin: one character, contributed to the point. */
+export const OwlCharacterPlugin = definePlugin({
+    name: OWL_CHARACTER_PLUGIN_NAME,
+    displayName: 'Owl character (example)',
+    description: 'An owl for the floating assistant, contributed by a plugin.',
+    contributes: [
+        contribution(LoopAssistantCharacter, { id: OWL_CHARACTER.id, character: OWL_CHARACTER }, { id: OWL_CHARACTER.id }),
+    ],
+});
+export default OwlCharacterPlugin;

package/lib/loop/apps/AppFeedback.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The feedback strip above an application's prompt (LOOP V-18): once an
+ * answer is in, a thumb up or down and a comment, kept in the application's
+ * record under the conversation it was about.
+ *
+ * Read through what the workspace offers, not around it: the chat keeps the
+ * current turn — the question, the answer, the conversation's thread — in
+ * `LoopChatTurn`, and the composer hangs what is contributed to
+ * `LoopPromptPanel` beside the prompt. `AppRenderer` adds the plugin for an
+ * application whose record keeps feedback, in the Studio's Preview and on
+ * the hosted page alike.
+ *
+ * @module loop/apps/AppFeedback
+ */
+import type { JSX } from 'react';
+import type { AppSpec } from '../../types/agentspecs';
+import { type LoopWorkspaceContext } from '../core';
+export declare const APP_FEEDBACK_PLUGIN_NAME = "@datalayer/loop-plugin-app-feedback";
+export declare function AppFeedback({ app, workspace, }: {
+    app: Pick<AppSpec, 'name'>;
+    workspace: LoopWorkspaceContext;
+}): JSX.Element | null;
+/**
+ * The plugin, for one application: the strip above its prompt. Made once per
+ * application — a new plugin rebuilds the workspace.
+ */
+export declare function defineAppFeedbackPlugin(app: AppSpec): import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;

package/lib/loop/apps/AppFeedback.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Button, IconButton, Text, Textarea } from '@primer/react';
+import { ThumbsdownIcon, ThumbsupIcon } from '@primer/octicons-react';
+import { contribution, definePlugin, signal } from '@datalayer/reactor';
+import { useContributions, useSignalValue } from '@datalayer/reactor/react';
+import { useIAMStore } from '../../state';
+import { LoopChatTurn, LoopPromptPanel, } from '../core';
+import { FEEDBACK_WORDS, sendFeedback } from './feedback';
+export const APP_FEEDBACK_PLUGIN_NAME = '@datalayer/loop-plugin-app-feedback';
+/* A signal to read when no chat contributed a turn: the hook needs one. */
+const NO_TURN = signal({ id: 0, status: 'idle' });
+export function AppFeedback({ app, workspace, }) {
+    const turns = useContributions(LoopChatTurn);
+    const turn = useSignalValue(turns[0]?.value.turn ?? NO_TURN);
+    const token = useIAMStore(state => state.token);
+    const [liked, setLiked] = useState(null);
+    const [comment, setComment] = useState('');
+    const [said, setSaid] = useState(null);
+    // Only under an answer that is in, in a conversation the runtime named.
+    if (turn.status !== 'done' || !turn.assistant || !turn.thread) {
+        return null;
+    }
+    const thread = turn.thread;
+    const choice = liked?.turn === turn.id ? liked.liked : null;
+    const done = said?.turn === turn.id ? said : null;
+    const agentBaseUrl = workspace.sandbox.agentBaseUrl || workspace.serverUrl || '';
+    const send = async () => {
+        if (choice === null) {
+            return;
+        }
+        setSaid({ turn: turn.id, state: 'sending', says: '' });
+        try {
+            await sendFeedback({ session: thread, liked: choice, comment }, { agentBaseUrl, token });
+            setSaid({
+                turn: turn.id,
+                state: 'kept',
+                says: FEEDBACK_WORDS.kept(app.name),
+            });
+            setComment('');
+        }
+        catch (error) {
+            setSaid({
+                turn: turn.id,
+                state: 'refused',
+                says: error instanceof Error ? error.message : String(error),
+            });
+        }
+    };
+    if (done?.state === 'kept') {
+        return (_jsx("div", { style: { padding: '4px 8px' }, children: _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: done.says }) }));
+    }
+    return (_jsxs("div", { role: "group", "aria-label": FEEDBACK_WORDS.ask, style: {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 4,
+            padding: '4px 8px',
+        }, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 4 }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: FEEDBACK_WORDS.ask }), _jsx(IconButton, { size: "small", variant: choice === true ? 'primary' : 'invisible', icon: ThumbsupIcon, "aria-label": FEEDBACK_WORDS.liked, "aria-pressed": choice === true, onClick: () => setLiked({ turn: turn.id, liked: true }) }), _jsx(IconButton, { size: "small", variant: choice === false ? 'danger' : 'invisible', icon: ThumbsdownIcon, "aria-label": FEEDBACK_WORDS.disliked, "aria-pressed": choice === false, onClick: () => setLiked({ turn: turn.id, liked: false }) })] }), choice !== null ? (_jsxs(_Fragment, { children: [_jsx(Textarea, { "aria-label": FEEDBACK_WORDS.comment, placeholder: FEEDBACK_WORDS.comment, value: comment, rows: 2, resize: "vertical", block: true, onChange: event => setComment(event.target.value) }), _jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 8 }, children: [_jsx(Button, { size: "small", variant: "primary", disabled: done?.state === 'sending', onClick: () => void send(), children: FEEDBACK_WORDS.send }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: FEEDBACK_WORDS.where(app.name) })] })] })) : null, done?.state === 'refused' ? (_jsx(Text, { sx: { fontSize: 0, color: 'danger.fg' }, children: done.says })) : null] }));
+}
+/**
+ * The plugin, for one application: the strip above its prompt. Made once per
+ * application — a new plugin rebuilds the workspace.
+ */
+export function defineAppFeedbackPlugin(app) {
+    function Panel({ workspace, }) {
+        return _jsx(AppFeedback, { app: app, workspace: workspace });
+    }
+    return definePlugin({
+        name: `${APP_FEEDBACK_PLUGIN_NAME}-${app.id}`,
+        displayName: `${app.name}: feedback`,
+        description: `A thumb and a comment on each answer of ${app.name}, kept in its record.`,
+        octicon: 'thumbsup',
+        emoji: '\u{1F44D}',
+        contributes: [
+            contribution(LoopPromptPanel, { id: 'app-feedback', placement: 'above', order: 20, Component: Panel }, { id: 'app-feedback' }),
+        ],
+    });
+}

package/lib/loop/apps/AppRenderer.d.ts

@@ -1,6 +1,7 @@
 import type { ReactorPlugin } from '@datalayer/reactor';
 import type { AppSpec } from '../../types/agentspecs';
 import { type LoopEmbedProps } from '../embed/LoopEmbed';
+import type { LoopPresetOptions } from '../presets';
 import type { PresenceState } from '../../chat/presence/presenceStatus';
 /** The id of an agent or a Cog, without its version. */
 export declare const agentIdOf: (app: Pick<AppSpec, "agent" | "team">) => string;
@@ -37,7 +38,38 @@ export type AppRendererProps = Omit<LoopEmbedProps, 'agentId'> & {
      * stable function, such as a state setter.
      */
     onPresence?: (state: PresenceState) => void;
+    /**
+     * Draw the application in a window (the `window-frame` plugin), its title
+     * the application's face and name. A host's own `frameTitle` wins.
+     */
+    frame?: boolean;
 };
+/** What `interface.layout` sets on the workspace. */
+export type AppLayoutOptions = Pick<LoopPresetOptions, 'editors' | 'showViewSelector' | 'defaultEditor' | 'pageLayout' | 'pageLayoutArrangement' | 'pageLayoutPrompt' | 'pageLayoutPromptAnchor' | 'pageLayoutTurnPanelFooter'>;
+/**
+ * The workspace an application's layout asks for (LOOP T-07).
+ *
+ * - `chat`: the conversation alone — no editor, no page, no strip.
+ * - `page`: the page layout — its page (or, without one, the editors) on the
+ *   sheet; the composer a card over it, starting at the bottom, whose display
+ *   modes put it in the conversation panel beside, over or in the corner of
+ *   the page; the current turn under the composer, its copy and dismiss only.
+ * - `split`: the page layout's split — the conversation on the left with its
+ *   composer, the page on the right, a hairline between them to drag.
+ *
+ * With a page, the page is the one editor, opened, without a strip to swap
+ * it; without one (a decision, whose page is the Studio's), the editors stay.
+ */
+export declare function appLayoutOptions(app: Pick<AppSpec, 'kind' | 'interface' | 'agent'>): AppLayoutOptions;
+/**
+ * What an application's agent is created with on a Datalayer runtime: under
+ * the application's id, over AG-UI, with the application's own document —
+ * so that the runtime registers it and decides every tool call by its rules
+ * (LOOP R-03, R-05), as `loop apps run --cloud` does. One payload for every
+ * place it runs: the workspace (`AppRenderer`) and the embed's floating
+ * modes (`AppEmbed`).
+ */
+export declare function appDatalayerCreatePayload(app: AppSpec, instance?: AppInstance): Record<string, unknown>;
 /**
  * An application in a LOOP workspace: its agent, its starters, its layout.
  *
@@ -47,5 +79,5 @@ export type AppRendererProps = Omit<LoopEmbedProps, 'agentId'> & {
 /** No host plugins: one array, so that it never reads as a change. */
 /** The agentspec a runtime is allocated with before an application's agent is created on it. */
 export declare const DATALAYER_BOOTSTRAP_AGENTSPEC = "example-simple";
-export declare function AppRenderer({ app, plugins, instance, onPresence, ...embed }: AppRendererProps): React.JSX.Element;
+export declare function AppRenderer({ app, plugins, instance, onPresence, frame, ...embed }: AppRendererProps): React.JSX.Element;
 export default AppRenderer;