@datalayer/agent-runtimes 1.3.34 → 1.3.35

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

@@ -33,8 +33,15 @@ 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[];
+/**
+ * How an Appspec names the character of its floating assistant (LOOP T-24):
+ * the id a plugin contributes it under, `paperclip` or `acme-owl` — as
+ * agentspecs' `ASSISTANT_CHARACTER_ID`. Which ids exist is what the enabled
+ * plugins contribute (`assistantCharacterNamed`), not the spec's to say.
+ */
+export declare const APP_ASSISTANT_CHARACTER_ID: RegExp;
+/** Whether a value is shaped as a character id an Appspec may name. */
+export declare function isAssistantCharacterId(value: unknown): value is 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

@@ -23,13 +23,19 @@ export const APP_EMBED_MODES = [
     'panel',
     'assistant',
 ];
-/** The characters an Appspec may name for its floating assistant (LOOP T-24). */
-export const APP_ASSISTANT_CHARACTERS = [
-    'paperclip',
-    'wizard',
-    'cat',
-    'eyes',
-];
+/**
+ * How an Appspec names the character of its floating assistant (LOOP T-24):
+ * the id a plugin contributes it under, `paperclip` or `acme-owl` — as
+ * agentspecs' `ASSISTANT_CHARACTER_ID`. Which ids exist is what the enabled
+ * plugins contribute (`assistantCharacterNamed`), not the spec's to say.
+ */
+export const APP_ASSISTANT_CHARACTER_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/** Whether a value is shaped as a character id an Appspec may name. */
+export function isAssistantCharacterId(value) {
+    return (typeof value === 'string' &&
+        value.length <= 64 &&
+        APP_ASSISTANT_CHARACTER_ID.test(value));
+}
 const ACTION_CLASS_NAMES = [
     'read',
     'write',
@@ -218,7 +224,7 @@ function parseInterface(data, kind) {
     if (isData(data.surface)) {
         parsed.surface = parseSurface(data.surface);
     }
-    if (APP_ASSISTANT_CHARACTERS.includes(data.assistant)) {
+    if (isAssistantCharacterId(data.assistant)) {
         parsed.assistant = data.assistant;
     }
     return parsed;

package/lib/loop/apps/checks.js

@@ -39,7 +39,7 @@ import { getTeamSpec } from '../../specs/teams';
 import { getToolSpec } from '../../specs/tools';
 import { getTrack } from '../../specs/tracks';
 import { pluginsOffSetupNotes } from '../plugins/canvas-blocks';
-import { parseAppspec } from './appspec';
+import { isAssistantCharacterId, parseAppspec } from './appspec';
 import { classesOf, splitRef, toolBehaviours } from './rules';
 export const NOT_READY = 'Not ready';
 export const NEEDS_ATTENTION = 'Needs attention';
@@ -378,7 +378,6 @@ const ENUMS = {
     ],
     visibility: ['private', 'invited', 'organization', 'link', 'public'],
     mode: ['inline', 'bubble', 'panel', 'assistant'],
-    character: ['paperclip', 'wizard', 'cat', 'eyes'],
     trigger: ['schedule', 'event', 'once'],
     criterion: ['metric', 'noul', 'choice', 'score'],
     direction: ['higher', 'lower'],
@@ -506,7 +505,9 @@ 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');
+        if (ui.assistant !== undefined && !isAssistantCharacterId(ui.assistant)) {
+            at('interface.assistant', 'names a character by the id a plugin contributes it under, lowercase words joined by a hyphen: `paperclip`, `acme-owl`');
+        }
         text(ui.welcome, 'interface.welcome');
         texts(ui.components, 'interface.components');
         records(ui.starters, 'interface.starters', (item, where) => {

package/lib/loop/plugins/assistant/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The floating assistant in the LOOP workspace (LOOP T-24): the character a
+ * page draws over its workspace, chosen from what the enabled plugins
+ * contribute to `loop.assistant.character` — the application's own
+ * (`interface.assistant`) when its Appspec names one, else the person's
+ * choice from their settings, else the paper clip. It acts out the chat's
+ * turn (T-22), says the agent's newest words in its balloon while the
+ * conversation is out of sight (T-23), opens the conversation when clicked,
+ * is dragged about and sent away as the chat's own assistant is (T-27).
+ *
+ * The workspace's chat is the conversation: on a page layout, its side panel
+ * is opened and closed; where the conversation is always on screen, a click
+ * takes the person to its composer.
+ *
+ * @module loop/plugins/assistant
+ */
+import type { JSX } from 'react';
+import { type AssistantState } from '../../../chat/assistant/state';
+import { type ChatTurnSnapshot } from '../../core';
+export declare const LOOP_ASSISTANT_PLUGIN_NAME = "@datalayer/loop-plugin-assistant";
+export type LoopAssistantConfig = {
+    /** The character the application's Appspec names; it wins. */
+    app?: string;
+    /** The character the person chose in their settings. */
+    person?: string;
+};
+/**
+ * What the character acts out, from the workspace's chat turn (T-22): it
+ * thinks while the agent thinks, works while a tool runs (the turn's
+ * `activity`), speaks while the answer is written, and idles otherwise.
+ */
+export declare function assistantStateOfTurn(turn: ChatTurnSnapshot, moment?: {
+    arriving?: boolean;
+    leaving?: boolean;
+}): AssistantState;
+export declare function LoopAssistant({ app, person, }: LoopAssistantConfig): JSX.Element | null;
+export declare const LoopAssistantPlugin: import("@datalayer/reactor").ReactorPlugin<LoopAssistantConfig, unknown, unknown>;
+export default LoopAssistantPlugin;

package/lib/loop/plugins/assistant/index.js

@@ -0,0 +1,140 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { definePlugin, signal } from '@datalayer/reactor';
+import { useContributions, useSignalValue } from '@datalayer/reactor/react';
+import { Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { pageLayoutPanelOpen, togglePagePanel, } from '@datalayer/primer-addons/lib/reactor';
+import { AssistantStage } from '../../../chat/assistant/AssistantStage';
+import { assistantStateOf, keepAway, keptAway, latestSaying, } from '../../../chat/assistant/state';
+import { useViewportDrag } from '../../../chat/useViewportDrag';
+import { LoopAssistantCharacter, LoopChatLayout, LoopChatTurn, LoopSlots, } from '../../core';
+import { assistantCharacterFor } from '../assistant-characters';
+export const LOOP_ASSISTANT_PLUGIN_NAME = '@datalayer/loop-plugin-assistant';
+/** The character's size, in pixels, as the chat's own assistant. */
+const SIZE = 88;
+/* A signal to read when no chat contributed a turn: the hook needs one. */
+const NO_TURN = signal({ id: 0, status: 'idle' });
+/**
+ * What the character acts out, from the workspace's chat turn (T-22): it
+ * thinks while the agent thinks, works while a tool runs (the turn's
+ * `activity`), speaks while the answer is written, and idles otherwise.
+ */
+export function assistantStateOfTurn(turn, moment = {}) {
+    const busy = turn.status === 'thinking' || turn.status === 'streaming';
+    const presence = !busy
+        ? 'idle'
+        : turn.activity
+            ? 'working'
+            : 'thinking';
+    return assistantStateOf(presence, {
+        ...moment,
+        speaking: turn.status === 'streaming' && !turn.activity,
+    });
+}
+/** Take the person to the workspace's composer. */
+function focusComposer() {
+    const composer = document.querySelector('[data-chat-composer] textarea, [data-chat-composer] [contenteditable="true"]');
+    composer?.focus();
+}
+export function LoopAssistant({ app, person, }) {
+    const contributed = useContributions(LoopAssistantCharacter).map(entry => entry.value);
+    const chosen = assistantCharacterFor(contributed, { app, person });
+    const turnEntries = useContributions(LoopChatTurn);
+    const turn = useSignalValue(turnEntries[0]?.value.turn ?? NO_TURN);
+    // On a page layout the conversation is its side panel; elsewhere it is
+    // always on screen.
+    const onPageLayout = useContributions(LoopChatLayout).some(entry => entry.value.id === 'page-layout');
+    const panelOpen = useSignalValue(pageLayoutPanelOpen);
+    const open = onPageLayout && panelOpen;
+    const [away, setAway] = useState(keptAway);
+    const [arriving, setArriving] = useState(true);
+    const [leaving, setLeaving] = useState(false);
+    useEffect(() => {
+        const timer = setTimeout(() => setArriving(false), 1800);
+        return () => clearTimeout(timer);
+    }, []);
+    /* The agent's newest words, said in the balloon until heard (T-23). */
+    const saying = turn.assistant
+        ? latestSaying([
+            { id: String(turn.id), role: 'assistant', content: turn.assistant },
+        ])
+        : undefined;
+    const [heardId, setHeardId] = useState();
+    const [fresh, setFresh] = useState(false);
+    useEffect(() => {
+        if (!saying || open) {
+            return;
+        }
+        setFresh(true);
+        const timer = setTimeout(() => setFresh(false), 12000);
+        return () => clearTimeout(timer);
+    }, [saying?.id, saying?.text, open]);
+    useEffect(() => {
+        if (open && saying) {
+            setHeardId(saying.id);
+        }
+    }, [open, saying?.id]);
+    const stageRef = useRef(null);
+    const drag = useViewportDrag(stageRef, { whole: true });
+    if (away !== 'none') {
+        return null;
+    }
+    if ('problem' in chosen) {
+        // Not replaced by another: what was named is said, where it would stand.
+        return (_jsx(Box, { role: "status", "data-assistant-problem": chosen.saidBy, sx: {
+                position: 'fixed',
+                right: 24,
+                bottom: 24,
+                zIndex: 1000,
+                maxWidth: 320,
+                p: 2,
+                borderRadius: 2,
+                border: '1px solid',
+                borderColor: 'attention.muted',
+                bg: 'attention.subtle',
+                boxShadow: 'shadow.medium',
+            }, children: _jsx(Text, { sx: { fontSize: 1 }, children: chosen.problem }) }));
+    }
+    const state = assistantStateOfTurn(turn, { arriving, leaving });
+    const unheard = !!saying && saying.id !== heardId;
+    const balloon = unheard && saying
+        ? { text: saying.text, more: saying.more }
+        : { text: 'Click me to open the conversation.' };
+    const insist = state === 'greeting' || (unheard && (state === 'speaking' || fresh));
+    const onToggle = () => {
+        if (onPageLayout) {
+            togglePagePanel();
+        }
+        else {
+            focusComposer();
+        }
+    };
+    const onDismiss = (next) => {
+        keepAway(next);
+        setLeaving(true);
+        setTimeout(() => {
+            setLeaving(false);
+            setAway(next);
+        }, 600);
+    };
+    return (_jsx(AssistantStage, { character: chosen.character, state: state, size: SIZE, place: drag.position
+            ? { left: `${drag.position.left}px`, top: `${drag.position.top}px` }
+            : { right: '24px', bottom: '24px' }, stageRef: stageRef, onDragStart: drag.onHandlePointerDown, open: open, onToggle: onToggle, balloon: balloon, insist: insist, onDismiss: onDismiss }));
+}
+export const LoopAssistantPlugin = definePlugin({
+    name: LOOP_ASSISTANT_PLUGIN_NAME,
+    config: { app: undefined, person: undefined },
+    displayName: 'Floating assistant',
+    description: 'The chat as a character on the page: the application’s own, or the one the person chose, from the characters the enabled plugins contribute.',
+    octicon: 'paperclip',
+    build: ({ config }) => {
+        const Configured = () => (_jsx(LoopAssistant, { app: config.app, person: config.person }));
+        return {
+            components: [
+                { id: 'loop-assistant', slot: LoopSlots.root, Component: Configured },
+            ],
+        };
+    },
+});
+export default LoopAssistantPlugin;

package/lib/loop/plugins/assistant-characters/index.d.ts

@@ -27,4 +27,29 @@ export declare function assistantCharactersOf(reactor: ContributionsReader): {
  * enabled plugin contributes is an error that says which ids there are.
  */
 export declare function assistantCharacterNamed(reactor: ContributionsReader, id: string): AssistantCharacter | AssistantCharacterData;
+/** Whose choice the character drawn is (T-24). */
+export type AssistantCharacterSaidBy = 'app' | 'person' | 'default';
+/** The character drawn, or why none can be. */
+export type AssistantCharacterChosen = {
+    id: string;
+    character: AssistantCharacter | AssistantCharacterData;
+    saidBy: AssistantCharacterSaidBy;
+} | {
+    problem: string;
+    saidBy: AssistantCharacterSaidBy;
+};
+/**
+ * The character the floating assistant draws on a page (T-24): the one the
+ * application's Appspec names (`interface.assistant`), which wins; else the
+ * one the person chose in their settings; else the paper clip — each looked
+ * up in what the enabled plugins contribute. An id no enabled plugin gives
+ * is not replaced by another: it is said, with the ids there are.
+ */
+export declare function assistantCharacterFor(contributed: ReadonlyArray<{
+    id: string;
+    character: AssistantCharacter | AssistantCharacterData;
+}>, choice: {
+    app?: string;
+    person?: string;
+}): AssistantCharacterChosen;
 export default AssistantCharactersPlugin;

package/lib/loop/plugins/assistant-characters/index.js

@@ -10,7 +10,7 @@
  * @module loop/plugins/assistant-characters
  */
 import { contribution, definePlugin, } from '@datalayer/reactor';
-import { ASSISTANT_CHARACTERS, } from '../../../chat/assistant/characters';
+import { ASSISTANT_CHARACTERS, DEFAULT_ASSISTANT_CHARACTER, } from '../../../chat/assistant/characters';
 import { LoopAssistantCharacter, } from '../../core';
 export const ASSISTANT_CHARACTERS_PLUGIN_NAME = '@datalayer/loop-plugin-assistant-characters';
 export const AssistantCharactersPlugin = definePlugin({
@@ -38,4 +38,32 @@ export function assistantCharacterNamed(reactor, id) {
     }
     return found.character;
 }
+/**
+ * The character the floating assistant draws on a page (T-24): the one the
+ * application's Appspec names (`interface.assistant`), which wins; else the
+ * one the person chose in their settings; else the paper clip — each looked
+ * up in what the enabled plugins contribute. An id no enabled plugin gives
+ * is not replaced by another: it is said, with the ids there are.
+ */
+export function assistantCharacterFor(contributed, choice) {
+    const saidBy = choice.app
+        ? 'app'
+        : choice.person
+            ? 'person'
+            : 'default';
+    const id = choice.app ?? choice.person ?? DEFAULT_ASSISTANT_CHARACTER;
+    const found = contributed.find(entry => entry.id === id);
+    if (found) {
+        return { id, character: found.character, saidBy };
+    }
+    const whose = saidBy === 'app'
+        ? 'This application names'
+        : saidBy === 'person'
+            ? 'Your settings name'
+            : 'The default is';
+    return {
+        saidBy,
+        problem: `${whose} the character “${id}”, which nothing enabled here draws; the characters are ${contributed.map(entry => entry.id).join(', ') || 'none'}.`,
+    };
+}
 export default AssistantCharactersPlugin;

package/lib/specs/appspecSchema.js

@@ -314,14 +314,17 @@ export const APPSPEC_SCHEMA = {
                 assistant: {
                     anyOf: [
                         {
-                            $ref: '#/$defs/AssistantCharacter',
+                            maxLength: 64,
+                            pattern: '^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$',
+                            type: 'string',
                         },
                         {
                             type: 'null',
                         },
                     ],
                     default: null,
-                    description: 'The character its floating assistant shows: `paperclip`, `wizard`, `cat` or `eyes`. The paper clip when unsaid; a person may choose another in their settings',
+                    description: "The character its floating assistant shows, by the id a plugin contributes it under (lowercase letters and digits, words joined by a hyphen): Datalayer's are `paperclip`, `wizard`, `cat` and `eyes`. The paper clip when unsaid; an id no enabled plugin contributes is refused where the plugins are known, the runtime and the page. Said here, it wins over a person's own choice in their settings",
+                    title: 'Assistant',
                 },
             },
             title: 'AppInterface',
@@ -677,12 +680,6 @@ export const APPSPEC_SCHEMA = {
             title: 'AppTrigger',
             type: 'object',
         },
-        AssistantCharacter: {
-            description: "The character an application's floating assistant shows (LOOP T-24):\none of those a UI plugin contributes. Datalayer's are these four.",
-            enum: ['paperclip', 'wizard', 'cat', 'eyes'],
-            title: 'AssistantCharacter',
-            type: 'string',
-        },
         Behaviour: {
             description: 'What an application does when it meets an action: the four a person chooses from.',
             enum: ['do_it', 'if_asked', 'ask_first', 'leave_to_me'],

package/lib/types/agentspecs.d.ts

@@ -384,10 +384,13 @@ export type AppLayout = 'chat' | 'page' | 'split';
 /** The one colour of an application; everything else is neutral. */
 export type AppAccent = 'green' | 'rose' | 'sky' | 'lime' | 'sun' | 'violet';
 /**
- * The character an application's floating assistant shows (LOOP T-24): one of
- * those Datalayer's plugin contributes.
+ * The character an application's floating assistant shows (LOOP T-24): the id
+ * an enabled plugin contributes it under to `loop.assistant.character` —
+ * Datalayer's are `paperclip`, `wizard`, `cat` and `eyes`. The spec checks
+ * its shape (`APP_ASSISTANT_CHARACTER_ID`); whether a plugin gives it is
+ * known only where the plugins are.
  */
-export type AppAssistantCharacter = 'paperclip' | 'wizard' | 'cat' | 'eyes';
+export type AppAssistantCharacter = string;
 /** How an application sits in another product's page (LOOP D-07). */
 export type AppEmbedMode = 'inline' | 'bubble' | 'panel' | 'assistant';
 /** Something an application reaches. */
@@ -456,7 +459,10 @@ export interface AppInterfaceSpec {
     /** The components of the catalog the surface may use. */
     components: string[];
     surface?: AppSurfaceSpec;
-    /** The character its floating assistant shows; the paper clip when unsaid. */
+    /**
+     * The character its floating assistant shows; the paper clip when unsaid.
+     * Said, it wins over the one the person chose in their settings.
+     */
     assistant?: AppAssistantCharacter;
 }
 export interface AppTestCaseSpec {

package/package.json

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