@datalayer/agent-runtimes 1.3.27 → 1.3.29

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/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/chat/presence/Presence.d.ts

@@ -0,0 +1,9 @@
+import { type PresenceState } from './presenceStatus';
+export declare function PresenceFace({ face, size, state, }: {
+    face: string;
+    size: number;
+    state: PresenceState;
+}): import("react").JSX.Element;
+export declare function PresenceLine({ state }: {
+    state: PresenceState;
+}): import("react").JSX.Element;

package/lib/chat/presence/Presence.js

@@ -0,0 +1,57 @@
+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.
+ */
+/**
+ * An application's presence in its chat (LOOP T-08): its face, with a quiet
+ * motion around it while it thinks or works, and one line saying what it is
+ * doing. The face is never redrawn; the motion is a soft ring in the accent,
+ * still under `prefers-reduced-motion`, and the line changes at the theme's
+ * status pace (T-10).
+ *
+ * @module chat/presence/Presence
+ */
+import { Box, Text } from '@primer/react';
+import { PRESENCE_LINES } from './presenceStatus';
+const ACCENT = 'var(--loop-accent, var(--fgColor-accent))';
+export function PresenceFace({ face, size, state, }) {
+    const active = state === 'thinking' || state === 'working';
+    return (_jsxs(Box, { as: "span", "aria-hidden": true, "data-presence": state, sx: {
+            position: 'relative',
+            display: 'inline-flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            width: size + 8,
+            height: size + 8,
+            flexShrink: 0,
+            fontSize: size,
+            lineHeight: 1,
+        }, children: [_jsx(Box, { as: "span", sx: {
+                    position: 'absolute',
+                    inset: 0,
+                    borderRadius: '50%',
+                    boxShadow: `0 0 0 2px ${ACCENT}`,
+                    opacity: active ? 0.9 : state === 'waiting' ? 0.9 : 0,
+                    transition: 'opacity var(--theme-motion-status, 0ms) var(--theme-motion-easing, ease)',
+                    animation: active
+                        ? 'loopPresenceBreath 1.8s ease-in-out infinite'
+                        : 'none',
+                    '@keyframes loopPresenceBreath': {
+                        '0%, 100%': { transform: 'scale(0.92)', opacity: 0.35 },
+                        '50%': { transform: 'scale(1.06)', opacity: 0.9 },
+                    },
+                    '@media (prefers-reduced-motion: reduce)': {
+                        animation: 'none',
+                    },
+                } }), face] }));
+}
+export function PresenceLine({ state }) {
+    return (_jsx(Text, { role: "status", "aria-live": "polite", "data-presence-line": state, sx: {
+            fontSize: 0,
+            color: state === 'waiting' ? 'fg.default' : 'fg.muted',
+            fontWeight: state === 'waiting' ? 'semibold' : 'normal',
+            whiteSpace: 'nowrap',
+            flexShrink: 0,
+        }, children: PRESENCE_LINES[state] }));
+}

package/lib/chat/presence/presenceStatus.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What an application is doing, in plain words (LOOP T-08): the one line of
+ * status beside its face.
+ *
+ * @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';
+/** The line each state is said by. */
+export declare const PRESENCE_LINES: Record<PresenceState, string>;
+/** The newest tool call of the conversation, as far as presence reads it. */
+export interface PresenceTool {
+    /** It has not returned. */
+    open: boolean;
+    /** It waits on a person's approval. */
+    pendingApproval: boolean;
+}
+/**
+ * The state, from whether a turn is running and the newest tool call.
+ *
+ * Waiting for an approval is said whether or not the turn is still
+ * streaming — the stream may end while the approval is asked. A tool that
+ * has not returned counts as work only during a turn: a stopped turn can
+ * 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/chat/presence/presenceStatus.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The line each state is said by. */
+export const PRESENCE_LINES = {
+    idle: 'Ready',
+    thinking: 'Thinking…',
+    working: 'Working…',
+    waiting: 'Waiting for you',
+};
+/**
+ * The state, from whether a turn is running and the newest tool call.
+ *
+ * Waiting for an approval is said whether or not the turn is still
+ * streaming — the stream may end while the approval is asked. A tool that
+ * has not returned counts as work only during a turn: a stopped turn can
+ * leave one open, and the application is not working then.
+ */
+export function presenceState(busy, tool) {
+    if (tool?.open && tool.pendingApproval) {
+        return 'waiting';
+    }
+    if (!busy) {
+        return 'idle';
+    }
+    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,6 +1,7 @@
 import type { ReactorPlugin } from '@datalayer/reactor';
 import type { AppSpec } from '../../types/agentspecs';
 import { type LoopEmbedProps } from '../embed/LoopEmbed';
+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;
 /**
@@ -30,6 +31,12 @@ export type AppRendererProps = Omit<LoopEmbedProps, 'agentId'> & {
     app: AppSpec;
     /** What its record is kept under, on Datalayer: the application, its deployment. */
     instance?: AppInstance;
+    /**
+     * Told what the application is doing — idle, thinking, working, waiting for
+     * you — for a host that draws its face in a frame of its own (T-08). A
+     * stable function, such as a state setter.
+     */
+    onPresence?: (state: PresenceState) => void;
 };
 /**
  * An application in a LOOP workspace: its agent, its starters, its layout.
@@ -40,5 +47,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, ...embed }: AppRendererProps): React.JSX.Element;
+export declare function AppRenderer({ app, plugins, instance, onPresence, ...embed }: AppRendererProps): React.JSX.Element;
 export default AppRenderer;

package/lib/loop/apps/AppRenderer.js

@@ -76,7 +76,7 @@ export function defineAppPlugin(app) {
 /** The agentspec a runtime is allocated with before an application's agent is created on it. */
 export const DATALAYER_BOOTSTRAP_AGENTSPEC = 'example-simple';
 const NO_PLUGINS = [];
-export function AppRenderer({ app, plugins = NO_PLUGINS, instance, ...embed }) {
+export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, ...embed }) {
     const chatOnly = app.interface.layout === 'chat';
     /*
      * The application plugin, made once per application. `LoopEmbed` rebuilds
@@ -142,6 +142,7 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, ...embed }) {
             name: app.name,
             face: app.emoji,
             welcome: app.interface.welcome || app.description,
+            onPresence,
         }, showTokenUsage: false, datalayerCreatePayload: datalayerCreatePayload, ...embed, plugins: allPlugins }));
 }
 export default AppRenderer;

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

@@ -24,13 +24,17 @@
  *
  * @module loop/apps/appspec
  */
-import type { AppAccent, AppKind, AppLayout, AppSpec } from '../../types/agentspecs';
+import type { AppAccent, AppAssistantCharacter, AppEmbedMode, AppKind, AppLayout, AppSpec } from '../../types/agentspecs';
 /** The version of the spec itself. */
 export declare const APP_SCHEMA = "loop.app/v1";
 /** The face of an application that has not chosen one. */
 export declare const DEFAULT_EMOJI = "\uD83D\uDC40";
 export declare const APP_KINDS: AppKind[];
 export declare const APP_ACCENTS: AppAccent[];
+/** The four ways an application sits in another product's page (LOOP D-07). */
+export declare const APP_EMBED_MODES: AppEmbedMode[];
+/** The characters an Appspec may name for its floating assistant (LOOP T-24). */
+export declare const APP_ASSISTANT_CHARACTERS: AppAssistantCharacter[];
 /** The layout a kind starts with. */
 export declare const DEFAULT_LAYOUTS: Record<AppKind, AppLayout>;
 /** What an application keeps of what it did, when it does not say. */

package/lib/loop/apps/appspec.js

@@ -16,6 +16,20 @@ export const APP_ACCENTS = [
     'sun',
     'violet',
 ];
+/** The four ways an application sits in another product's page (LOOP D-07). */
+export const APP_EMBED_MODES = [
+    'inline',
+    'bubble',
+    'panel',
+    'assistant',
+];
+/** The characters an Appspec may name for its floating assistant (LOOP T-24). */
+export const APP_ASSISTANT_CHARACTERS = [
+    'paperclip',
+    'wizard',
+    'cat',
+    'eyes',
+];
 const ACTION_CLASS_NAMES = [
     'read',
     'write',
@@ -203,6 +217,9 @@ function parseInterface(data, kind) {
     if (isData(data.surface)) {
         parsed.surface = parseSurface(data.surface);
     }
+    if (APP_ASSISTANT_CHARACTERS.includes(data.assistant)) {
+        parsed.assistant = data.assistant;
+    }
     return parsed;
 }
 function parseCriterion(data) {
@@ -239,7 +256,7 @@ function parseDeployment(data) {
     }
     if (isData(data.embedded)) {
         deployment.embedded = {
-            mode: oneOf(data.embedded.mode, ['inline', 'bubble', 'panel'], 'inline'),
+            mode: oneOf(data.embedded.mode, APP_EMBED_MODES, 'inline'),
             origins: texts(data.embedded.origins),
         };
     }
@@ -454,6 +471,9 @@ function dumpInterface(spec, kind) {
     if (spec.surface) {
         writer.data.surface = dumpSurface(spec.surface);
     }
+    if (spec.assistant) {
+        writer.data.assistant = spec.assistant;
+    }
     return writer.data;
 }
 function dumpDecision(decision) {

package/lib/loop/apps/checks.js

@@ -370,7 +370,8 @@ const ENUMS = {
         'feedback',
     ],
     visibility: ['private', 'invited', 'organization', 'link', 'public'],
-    mode: ['inline', 'bubble', 'panel'],
+    mode: ['inline', 'bubble', 'panel', 'assistant'],
+    character: ['paperclip', 'wizard', 'cat', 'eyes'],
     trigger: ['schedule', 'event', 'once'],
     criterion: ['metric', 'noul', 'choice', 'score'],
     direction: ['higher', 'lower'],
@@ -498,6 +499,7 @@ export function documentShapeProblems(document) {
     mapping(d.interface, 'interface', ui => {
         oneOf(ui.layout, ENUMS.layout, 'interface.layout');
         oneOf(ui.accent, ENUMS.accent, 'interface.accent');
+        oneOf(ui.assistant, ENUMS.character, 'interface.assistant');
         text(ui.welcome, 'interface.welcome');
         texts(ui.components, 'interface.components');
         records(ui.starters, 'interface.starters', (item, where) => {

package/lib/loop/core/index.d.ts

@@ -4,6 +4,8 @@ import type { ExecutionState } from '@datalayer/jupyter-react/kernel-indicator';
 import type { ToolbarItem } from '@datalayer/primer-addons';
 import type { FrontendToolDefinition } from '../../types/tools';
 import type { ContextSnapshotData } from '../../types/context';
+import type { AssistantCharacter } from '../../chat/assistant/characters';
+import type { AssistantCharacterData } from '../../chat/assistant/formats/types';
 /** Lifecycle of the sandbox a workspace is attached to. */
 export type SandboxState = 'idle' | 'starting' | 'running' | 'stopping' | 'error';
 /** What the workspace knows about the sandbox behind it. */
@@ -503,6 +505,19 @@ export type ChatSuggestionContribution = {
     suggestions: ChatSuggestionItem[];
 };
 export declare const LoopChatSuggestion: import("@datalayer/reactor").ContributionPoint<ChatSuggestionContribution>;
+/**
+ * A character the floating assistant may show (LOOP T-24): a drawing — one
+ * of Datalayer's own (T-25) or a plugin's — or a character read from a file
+ * a person holds the rights to (T-26). The catalogue of characters is what
+ * the enabled plugins contribute here, and nothing else; an application
+ * names one by id (`interface.assistant`).
+ */
+export type AssistantCharacterContribution = {
+    /** Stable id, what an application names. */
+    id: string;
+    character: AssistantCharacter | AssistantCharacterData;
+};
+export declare const LoopAssistantCharacter: import("@datalayer/reactor").ContributionPoint<AssistantCharacterContribution>;
 /**
  * The per-example chat extras a host feeds the loop's conversation live.
  *