@datalayer/agent-runtimes 1.3.28 → 1.3.30

package/lib/chat/assistant/state.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What the floating assistant acts out (LOOP T-22): the presence of the
+ * application (T-08), and three moments of its own — greeting when it
+ * arrives, speaking while an answer streams in, goodbye when it is sent away.
+ *
+ * @module chat/assistant/state
+ */
+import type { PresenceState } from '../presence/presenceStatus';
+/** The states a character has an animation for. */
+export type AssistantState = 'idle' | 'thinking' | 'working' | 'waiting' | 'greeting' | 'speaking' | 'goodbye';
+/** What a character is doing, beyond what the application is doing. */
+export interface AssistantMoment {
+    /** It has just appeared, and says hello once. */
+    arriving?: boolean;
+    /** It is being sent away. */
+    leaving?: boolean;
+    /** The answer is arriving: words are being written. */
+    speaking?: boolean;
+}
+/**
+ * The state to act, from the application's presence and the moment.
+ *
+ * Leaving and arriving win, being short; then waiting for the person, which
+ * must never be missed; then speaking over thinking, since words arriving
+ * are what the person watches; then the presence as it is.
+ */
+export declare function assistantStateOf(presence: PresenceState, moment?: AssistantMoment): AssistantState;
+/**
+ * Whether words are arriving: the newest item of the conversation is the
+ * assistant's own message, not a tool call. Read with `busy`, it is speaking.
+ */
+export declare function newestIsAnswer(items: readonly unknown[]): boolean;
+/** A word from the agent, for the character's balloon. */
+export interface AssistantSaying {
+    /** The message it comes from: a new id is a new thing said. */
+    id: string;
+    /** Its text, short enough for a balloon. */
+    text: string;
+    /** Whether there was more than the balloon holds. */
+    more: boolean;
+}
+/** How much of a message the balloon says before *Open the conversation*. */
+export declare const SAYING_LIMIT = 220;
+/**
+ * The newest thing the agent said, as the Office Assistant said it: in the
+ * balloon, while the conversation is closed (T-23). Only its own messages
+ * with text — not a tool call, not the person's words; markdown is read as
+ * plain words, and a long message is cut at a word with `more` set.
+ */
+export declare function latestSaying(items: readonly unknown[]): AssistantSaying | undefined;
+/**
+ * How long the assistant is away, once sent (T-27): for the page — the
+ * popup's button calls it back — for the session, or for good; the header's
+ * *Floating assistant* always calls it back.
+ */
+export type AssistantAway = 'none' | 'page' | 'session' | 'always';
+/** Where the choice is kept: the session's storage, or for good. */
+export declare const ASSISTANT_AWAY_KEY = "datalayer-assistant-away";
+/** The away a page starts with, from what was kept. Storage may be refused. */
+export declare function keptAway(): AssistantAway;
+/** Keep the choice where it lasts as long as it says; `none` forgets it. */
+export declare function keepAway(away: AssistantAway): void;

package/lib/chat/assistant/state.js

@@ -0,0 +1,116 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The state to act, from the application's presence and the moment.
+ *
+ * Leaving and arriving win, being short; then waiting for the person, which
+ * must never be missed; then speaking over thinking, since words arriving
+ * are what the person watches; then the presence as it is.
+ */
+export function assistantStateOf(presence, moment = {}) {
+    if (moment.leaving) {
+        return 'goodbye';
+    }
+    if (moment.arriving) {
+        return 'greeting';
+    }
+    if (presence === 'waiting') {
+        return 'waiting';
+    }
+    if (moment.speaking && presence !== 'idle') {
+        return 'speaking';
+    }
+    return presence;
+}
+/**
+ * Whether words are arriving: the newest item of the conversation is the
+ * assistant's own message, not a tool call. Read with `busy`, it is speaking.
+ */
+export function newestIsAnswer(items) {
+    const newest = items[items.length - 1];
+    return (!!newest &&
+        newest.role === 'assistant' &&
+        typeof newest.toolName !== 'string');
+}
+/** How much of a message the balloon says before *Open the conversation*. */
+export const SAYING_LIMIT = 220;
+/**
+ * The newest thing the agent said, as the Office Assistant said it: in the
+ * balloon, while the conversation is closed (T-23). Only its own messages
+ * with text — not a tool call, not the person's words; markdown is read as
+ * plain words, and a long message is cut at a word with `more` set.
+ */
+export function latestSaying(items) {
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        const item = items[index];
+        if (item.role !== 'assistant' || typeof item.toolName === 'string') {
+            continue;
+        }
+        const raw = typeof item.content === 'string'
+            ? item.content
+            : Array.isArray(item.content)
+                ? item.content
+                    .map(part => part &&
+                    typeof part === 'object' &&
+                    part.type === 'text'
+                    ? String(part.text ?? '')
+                    : '')
+                    .join(' ')
+                : '';
+        const plain = raw
+            .replace(/```[\s\S]*?```/g, ' ')
+            .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+            .replace(/[*_`#>]+/g, '')
+            .replace(/\s+/g, ' ')
+            .trim();
+        if (!plain) {
+            continue;
+        }
+        if (plain.length <= SAYING_LIMIT) {
+            return { id: String(item.id ?? index), text: plain, more: false };
+        }
+        const cut = plain.slice(0, SAYING_LIMIT);
+        const atWord = cut.slice(0, Math.max(cut.lastIndexOf(' '), SAYING_LIMIT * 0.6));
+        return {
+            id: String(item.id ?? index),
+            text: `${atWord.trimEnd()}…`,
+            more: true,
+        };
+    }
+    return undefined;
+}
+/** Where the choice is kept: the session's storage, or for good. */
+export const ASSISTANT_AWAY_KEY = 'datalayer-assistant-away';
+/** The away a page starts with, from what was kept. Storage may be refused. */
+export function keptAway() {
+    try {
+        if (window.localStorage.getItem(ASSISTANT_AWAY_KEY) === 'always') {
+            return 'always';
+        }
+        if (window.sessionStorage.getItem(ASSISTANT_AWAY_KEY) === 'session') {
+            return 'session';
+        }
+    }
+    catch {
+        // A page without storage keeps the assistant for the page only.
+    }
+    return 'none';
+}
+/** Keep the choice where it lasts as long as it says; `none` forgets it. */
+export function keepAway(away) {
+    try {
+        window.localStorage.removeItem(ASSISTANT_AWAY_KEY);
+        window.sessionStorage.removeItem(ASSISTANT_AWAY_KEY);
+        if (away === 'always') {
+            window.localStorage.setItem(ASSISTANT_AWAY_KEY, 'always');
+        }
+        else if (away === 'session') {
+            window.sessionStorage.setItem(ASSISTANT_AWAY_KEY, 'session');
+        }
+    }
+    catch {
+        // Without storage the choice holds for the page.
+    }
+}

package/lib/chat/base/ChatBase.js

@@ -48,7 +48,7 @@ import { InputPrompt } from '../prompt/InputPrompt';
 import { isFloatingChatViewMode } from '../viewModes';
 import { ToolApprovalBanner, ToolApprovalDialog, } from '../tools';
 import { EphemeralNotebook } from '../notebook/EphemeralNotebook';
-import { initialModelId, isOffered, usableModels } from './modelChoice';
+import { initialModelId, isOffered, offeredModels as offeredModelsFor, } from './modelChoice';
 // EphemeralDocument statically imports `@datalayer/jupyter-lexical` (which
 // initialises Lumino-backed nodes on load). Lazy-load it so notebook-only chats
 // never pull lexical into the bundle or trigger its module side effects.
@@ -1380,37 +1380,46 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         : undefined;
     const offeredModels = useMemo(() => {
         // Only what can actually be called — see `modelChoice` for the rule.
-        const fromConfig = availableModels || configQuery.data?.models;
-        if (fromConfig?.length) {
-            return usableModels(fromConfig);
-        }
-        /*
-         * The catalogue, filtered to what is worth offering.
-         *
-         * A server tells the chat which models it can reach and that answer wins.
-         * Without one — an in-page agent, or a server that has not answered yet —
-         * this used to offer the single model the protocol was built with, which
-         * is a menu with nothing to choose.
-         *
-         * `available` is the filter, not the whole catalogue: twenty-six models,
-         * most of them superseded, is a list nobody reads. The specs say which
-         * four are current.
-         */
-        const catalogued = Object.values(AI_MODEL_CATALOGUE)
-            // A typed-judgment model answers typed questions, not a chat.
-            .filter(model => model.available && isChatModel(model))
-            .map(model => ({
-            id: model.id,
-            name: model.name,
-            provider: model.provider,
-        }));
-        if (catalogued.length > 0) {
-            return usableModels(catalogued);
-        }
-        return browserModel
-            ? [{ id: browserModel, name: browserModel, provider: 'inference' }]
-            : [];
-    }, [availableModels, configQuery.data?.models, browserModel]);
+        // The runtime's answer, when it gave one, is the whole list.
+        // A runtime that was asked and did not answer offers nothing: the
+        // agentspecs catalogue below is not its answer.
+        const fromConfig = availableModels ||
+            configQuery.data?.models ||
+            (configQuery.isError ? [] : undefined);
+        return offeredModelsFor(fromConfig, () => {
+            /*
+             * The catalogue, filtered to what is worth offering.
+             *
+             * A server tells the chat which models it can reach and that answer wins.
+             * Without one — an in-page agent, or a server that has not answered yet —
+             * this used to offer the single model the protocol was built with, which
+             * is a menu with nothing to choose.
+             *
+             * `available` is the filter, not the whole catalogue: twenty-six models,
+             * most of them superseded, is a list nobody reads. The specs say which
+             * four are current.
+             */
+            const catalogued = Object.values(AI_MODEL_CATALOGUE)
+                // A typed-judgment model answers typed questions, not a chat.
+                .filter(model => model.available && isChatModel(model))
+                .map(model => ({
+                id: model.id,
+                name: model.name,
+                provider: model.provider,
+            }));
+            if (catalogued.length > 0) {
+                return catalogued;
+            }
+            return browserModel
+                ? [{ id: browserModel, name: browserModel, provider: 'inference' }]
+                : [];
+        });
+    }, [
+        availableModels,
+        configQuery.data?.models,
+        configQuery.isError,
+        browserModel,
+    ]);
     /*
      * Who `@` may address.
      *

package/lib/chat/base/modelChoice.d.ts

@@ -26,6 +26,17 @@ export declare const isUsable: (model: ModelConfig) => boolean;
  * while the rows and their reasons say which key is missing.
  */
 export declare function usableModels(models: ModelConfig[]): ModelConfig[];
+/**
+ * The models a chat offers, given what its runtime answered.
+ *
+ * The runtime's answer is the list: an agent's own models (its `model` and
+ * `model_additionals`), each flagged with whether its inference serves it.
+ * When the runtime answered, nothing else is added — not even when its list
+ * is empty, which says the agent has nothing to switch to. `fallback` is
+ * asked only when there is no runtime to answer (an in-page agent) or it
+ * has not answered yet.
+ */
+export declare function offeredModels(fromRuntime: ModelConfig[] | undefined, fallback: () => ModelConfig[]): ModelConfig[];
 /** Whether `id` is on offer and usable — the selection may stand. */
 export declare const isOffered: (offered: ModelConfig[], id?: string) => boolean;
 /**
@@ -59,4 +70,6 @@ export type ServerCatalogueModel = {
  */
 export declare function readServerCatalogue(payload: {
     models?: ServerCatalogueModel[];
+    source?: string;
+    note?: string;
 } | null | undefined): ModelConfig[];

package/lib/chat/base/modelChoice.js

@@ -14,6 +14,19 @@ export function usableModels(models) {
     const usable = models.filter(isUsable);
     return usable.length > 0 ? usable : models;
 }
+/**
+ * The models a chat offers, given what its runtime answered.
+ *
+ * The runtime's answer is the list: an agent's own models (its `model` and
+ * `model_additionals`), each flagged with whether its inference serves it.
+ * When the runtime answered, nothing else is added — not even when its list
+ * is empty, which says the agent has nothing to switch to. `fallback` is
+ * asked only when there is no runtime to answer (an in-page agent) or it
+ * has not answered yet.
+ */
+export function offeredModels(fromRuntime, fallback) {
+    return usableModels(fromRuntime ?? fallback());
+}
 /** Whether `id` is on offer and usable — the selection may stand. */
 export const isOffered = (offered, id) => Boolean(id) && offered.some(m => m.id === id && isUsable(m));
 /**

package/lib/chat/header/ChatViewModeToggle.js

@@ -1,13 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Tooltip } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
-import { CommentDiscussionIcon, DeviceMobileIcon, GrabberIcon, SidebarExpandIcon, } from '@primer/octicons-react';
-import { CHAT_VIEW_MODES, SIDEBAR_NEEDS_MOUNT_POINT } from '../viewModes';
+import { CommentDiscussionIcon, DeviceMobileIcon, GrabberIcon, PaperclipIcon, SidebarExpandIcon, } from '@primer/octicons-react';
+import { ASSISTANT_NEEDS_A_FLOATING_CHAT, CHAT_VIEW_MODES, SIDEBAR_NEEDS_MOUNT_POINT, } from '../viewModes';
 /** The drawing of each mode. */
 export const VIEW_MODE_ICONS = {
     floating: CommentDiscussionIcon,
     'floating-small': DeviceMobileIcon,
     'floating-draggable': GrabberIcon,
+    assistant: PaperclipIcon,
     sidebar: SidebarExpandIcon,
 };
 export function ChatViewModeToggle({ value, onChange, disabledModes = [], tooltipDirection = 'n', }) {
@@ -26,7 +27,9 @@ export function ChatViewModeToggle({ value, onChange, disabledModes = [], toolti
             const disabled = disabledModes.includes(mode);
             return (_jsx(Tooltip, { text: disabled && mode === 'sidebar'
                     ? `${label} — ${SIDEBAR_NEEDS_MOUNT_POINT}`
-                    : label, direction: tooltipDirection, children: _jsx(Box, { as: "button", type: "button", "aria-label": label, "aria-pressed": selected, "aria-disabled": disabled || undefined, onClick: () => {
+                    : disabled && mode === 'assistant'
+                        ? `${label} — ${ASSISTANT_NEEDS_A_FLOATING_CHAT}`
+                        : label, direction: tooltipDirection, children: _jsx(Box, { as: "button", type: "button", "aria-label": label, "aria-pressed": selected, "aria-disabled": disabled || undefined, onClick: () => {
                         if (!disabled) {
                             onChange(mode);
                         }

package/lib/{loop/plugins/chat → chat/presence}/Presence.js

@@ -10,7 +10,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * still under `prefers-reduced-motion`, and the line changes at the theme's
  * status pace (T-10).
  *
- * @module loop/plugins/chat/Presence
+ * @module chat/presence/Presence
  */
 import { Box, Text } from '@primer/react';
 import { PRESENCE_LINES } from './presenceStatus';

package/lib/{loop/plugins/chat → chat/presence}/presenceStatus.d.ts

@@ -2,7 +2,7 @@
  * What an application is doing, in plain words (LOOP T-08): the one line of
  * status beside its face.
  *
- * @module loop/plugins/chat/presenceStatus
+ * @module chat/presence/presenceStatus
  */
 /** The states a person is told about. Paused waits for a pause to exist. */
 export type PresenceState = 'idle' | 'thinking' | 'working' | 'waiting';
@@ -24,3 +24,9 @@ export interface PresenceTool {
  * leave one open, and the application is not working then.
  */
 export declare function presenceState(busy: boolean, tool?: PresenceTool): PresenceState;
+/**
+ * The newest tool call of the conversation: whether it has not returned, and
+ * whether it waits on a person's approval. A tool call is an item with a
+ * tool name and a call id; it has returned once it is complete or failed.
+ */
+export declare function presenceToolOf(items: readonly unknown[]): PresenceTool;

package/lib/{loop/plugins/chat → chat/presence}/presenceStatus.js

@@ -26,3 +26,21 @@ export function presenceState(busy, tool) {
     }
     return tool?.open ? 'working' : 'thinking';
 }
+/**
+ * The newest tool call of the conversation: whether it has not returned, and
+ * whether it waits on a person's approval. A tool call is an item with a
+ * tool name and a call id; it has returned once it is complete or failed.
+ */
+export function presenceToolOf(items) {
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        const item = items[index];
+        if (typeof item.toolName === 'string' && item.toolCallId) {
+            const open = item.status !== 'complete' && item.status !== 'error';
+            const pendingApproval = open &&
+                item.result
+                    ?.pending_approval === true;
+            return { open, pendingApproval };
+        }
+    }
+    return { open: false, pendingApproval: false };
+}

package/lib/chat/viewModes.d.ts

@@ -23,6 +23,12 @@ export type ChatViewModeOption = {
 };
 /** The modes, in the order the toggle shows them: floating first, docked last. */
 export declare const CHAT_VIEW_MODES: readonly ChatViewModeOption[];
+/**
+ * Why the assistant is greyed out, for its tooltip: it is drawn by the
+ * floating chat (`ChatFloating`); a layout that places the chat itself, as
+ * the page layout does, has no character to show (LOOP T-21).
+ */
+export declare const ASSISTANT_NEEDS_A_FLOATING_CHAT = "The assistant is drawn by the floating chat, not by this layout";
 /** Why the sidebar option is greyed out, for its tooltip. */
 export declare const SIDEBAR_NEEDS_MOUNT_POINT = "No mount point for a sidebar on this page";
 /** Whether a mode floats over the page rather than docking into it. */

package/lib/chat/viewModes.js

@@ -7,15 +7,24 @@ export const CHAT_VIEW_MODES = [
     { mode: 'floating', label: 'Full-height popup' },
     { mode: 'floating-small', label: 'Floating popup' },
     { mode: 'floating-draggable', label: 'Floating draggable' },
+    // A character on the page that speaks in a balloon (LOOP T-21).
+    { mode: 'assistant', label: 'Floating assistant' },
     { mode: 'sidebar', label: 'Sidebar panel' },
 ];
+/**
+ * Why the assistant is greyed out, for its tooltip: it is drawn by the
+ * floating chat (`ChatFloating`); a layout that places the chat itself, as
+ * the page layout does, has no character to show (LOOP T-21).
+ */
+export const ASSISTANT_NEEDS_A_FLOATING_CHAT = 'The assistant is drawn by the floating chat, not by this layout';
 /** Why the sidebar option is greyed out, for its tooltip. */
 export const SIDEBAR_NEEDS_MOUNT_POINT = 'No mount point for a sidebar on this page';
 /** Whether a mode floats over the page rather than docking into it. */
 export function isFloatingChatViewMode(mode) {
     return (mode === 'floating' ||
         mode === 'floating-small' ||
-        mode === 'floating-draggable');
+        mode === 'floating-draggable' ||
+        mode === 'assistant');
 }
 /**
  * Where a host said the sidebar goes.

package/lib/examples/ChatAssistantExample.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+import React from 'react';
+declare const ChatAssistantExample: React.FC;
+export default ChatAssistantExample;

package/lib/examples/ChatAssistantExample.js

@@ -0,0 +1,59 @@
+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.
+ */
+/**
+ * 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.
+ */
+import { useState } from 'react';
+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 { readAcsCharacter, readClippyCharacter, } from '../chat/assistant/formats';
+/**
+ * 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).
+ */
+async function readPicked(files) {
+    const acs = files.find(file => file.name.toLowerCase().endsWith('.acs'));
+    if (acs) {
+        return readAcsCharacter(await acs.arrayBuffer());
+    }
+    const agentJs = files.find(file => file.name.toLowerCase() === 'agent.js');
+    const mapPng = files.find(file => /\.(png|gif|webp|jpe?g)$/i.test(file.name));
+    const soundsJs = files.find(file => /^sounds-.*\.js$/i.test(file.name));
+    if (!agentJs || !mapPng) {
+        throw new Error('Pick one .acs file, or a clippy.js character: its agent.js and its map image (and a sounds file if you have one).');
+    }
+    return readClippyCharacter({
+        agentJs: await agentJs.text(),
+        mapPng,
+        soundsJs: soundsJs ? await soundsJs.text() : undefined,
+    });
+}
+const ChatAssistantExample = () => {
+    const [character, setCharacter] = useState(ASSISTANT_CHARACTERS[0].id);
+    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: () => {
+                                    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) => {
+                                        const files = Array.from(event.target.files ?? []);
+                                        if (!files.length) {
+                                            return;
+                                        }
+                                        try {
+                                            setCharacter(await readPicked(files));
+                                            setLoadError(undefined);
+                                        }
+                                        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)] }) }));
+};
+export default ChatAssistantExample;

package/lib/examples/example-selector.js

@@ -87,6 +87,7 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('DocumentPageAgent', () => import('./DocumentPageAgent'), 'A document as a page: floating prompt on top, an agent writing in it.'),
     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('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.'),

package/lib/examples/main.js

@@ -77,6 +77,9 @@ const ANONYMOUS_EXAMPLES = new Set([
     'DocumentPageAgent',
     // The decks plugin in a Loop; the agent and the decks both live in the page.
     'DecksAgent',
+    // The floating assistant: the character, its balloon and its motions need
+    // no runtime; a conversation does, and says so when there is none.
+    'ChatAssistantExample',
 ]);
 const getExampleGroup = (id) => {
     if (id === 'AgentspecsExample' ||

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

@@ -1,7 +1,8 @@
 import type { ReactorPlugin } from '@datalayer/reactor';
 import type { AppSpec } from '../../types/agentspecs';
 import { type LoopEmbedProps } from '../embed/LoopEmbed';
-import type { PresenceState } from '../plugins/chat/presenceStatus';
+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;