@datalayer/agent-runtimes 1.3.27 → 1.3.28

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 '../plugins/chat/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/plugins/chat/ChatView.js

@@ -43,6 +43,8 @@ import { turnWritersOf } from './turnState';
 import { isInactiveSurfaceContribution, orderToolContributions, toolsForChatView, } from './chatViewTools';
 import { useAgentCommandTools } from '../../../tools/adapters/commands';
 import { NONE_EDITOR, seedEditorChoice, setEditorOptions, } from '../shell/editorChoice';
+import { PresenceFace, PresenceLine } from './Presence';
+import { presenceState } from './presenceStatus';
 /** No editor: the conversation on its own. */
 const NO_SURFACE = '';
 /**
@@ -186,6 +188,16 @@ export default function ChatView({ workspace }) {
      */
     const [busy, setBusy] = useState(false);
     const [sendReady, setSendReady] = useState(false);
+    const [presenceTool, setPresenceTool] = useState({
+        open: false,
+        pendingApproval: false,
+    });
+    const presenceNow = presenceState(busy, presenceTool);
+    const onPresence = config?.presence?.onPresence;
+    // A host drawing the face in a frame of its own is told as it changes.
+    useEffect(() => {
+        onPresence?.(presenceNow);
+    }, [onPresence, presenceNow]);
     const handleSendReady = useCallback((controls) => {
         controlsRef.current = controls;
         setSendReady(!!controls);
@@ -199,6 +211,22 @@ export default function ChatView({ workspace }) {
      * Cleared when nothing is running.
      */
     const handleDisplayItemsChange = useCallback((items) => {
+        // The newest tool call, for an application's line of status (T-08).
+        let newest;
+        for (let index = items.length - 1; index >= 0; index -= 1) {
+            const item = items[index];
+            if (typeof item.toolName === 'string' && item.toolCallId) {
+                newest = item;
+                break;
+            }
+        }
+        const open = !!newest && newest.status !== 'complete' && newest.status !== 'error';
+        const pendingApproval = open &&
+            newest?.result
+                ?.pending_approval === true;
+        setPresenceTool(previous => previous.open === open && previous.pendingApproval === pendingApproval
+            ? previous
+            : { open, pendingApproval });
         const feed = turnFeedRef.current;
         if (!feed) {
             return;
@@ -1436,7 +1464,10 @@ export default function ChatView({ workspace }) {
                         // Big enough to read as the agent's mark rather than as
                         // punctuation before its name, and still short enough not to
                         // set the header's height.
-                        brandIcon: presence?.face ? (_jsx("span", { "aria-hidden": true, style: { fontSize: 20, lineHeight: 1 }, children: presence.face })) : (_jsx(BrandIcon, { size: 20 })), emptyState: {
+                        brandIcon: presence?.face ? (_jsx(PresenceFace, { face: presence.face, size: 20, state: presenceNow })) : (_jsx(BrandIcon, { size: 20 })), 
+                        // An application says what it is doing, in plain words, beside
+                        // its name (T-08); an agent's chat keeps its header as it is.
+                        headerContent: presence ? _jsx(PresenceLine, { state: presenceNow }) : undefined, emptyState: {
                             // An application's own face, large: the thing a person's eye
                             // lands on first (LOOP T-08).
                             icon: presence?.face ? (_jsx("span", { "aria-hidden": true, style: { fontSize: 48, lineHeight: 1 }, children: presence.face })) : (_jsx(BrandIcon, { size: 48 })),

package/lib/loop/plugins/chat/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/loop/plugins/chat/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 loop/plugins/chat/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/loop/plugins/chat/index.d.ts

@@ -1,3 +1,4 @@
+import type { PresenceState } from './presenceStatus';
 /** What a host may set on the chat. */
 /** Who is answering, as the person meets them. */
 export interface ChatPresence {
@@ -6,6 +7,13 @@ export interface ChatPresence {
     face?: string;
     /** What it says before anyone writes. */
     welcome?: string;
+    /**
+     * Told what it is doing as it changes — idle, thinking, working, waiting
+     * for you — for a host that draws the face itself, in a frame of its own.
+     * Read once, when the workspace is built: pass a stable function, such as
+     * a state setter.
+     */
+    onPresence?: (state: PresenceState) => void;
 }
 export type ChatPluginConfig = {
     /**

package/lib/loop/plugins/chat/presenceStatus.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What an application is doing, in plain words (LOOP T-08): the one line of
+ * status beside its face.
+ *
+ * @module loop/plugins/chat/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;

package/lib/loop/plugins/chat/presenceStatus.js

@@ -0,0 +1,28 @@
+/*
+ * 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';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.27",
+    "version": "1.3.28",
     "type": "module",
     "workspaces": [
         ".",