@datalayer/agent-runtimes 1.3.28 → 1.3.30

package/lib/loop/plugins/app-page/appPage.js

@@ -0,0 +1,443 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The id of the editor surface an application's page is drawn in. */
+export const APP_PAGE_SURFACE = 'app-page';
+/** The id of the A2UI surface itself, inside it. */
+export const APP_PAGE_SURFACE_ID = 'app';
+const APP = {
+    path: '/app',
+    meaning: "The application's name.",
+    words: 'Its name',
+};
+const STATUS = {
+    path: '/status',
+    meaning: 'Where its answer stands, in a word: Ready, Thinking, Answering, Answered or Stopped.',
+    words: 'Where its answer stands',
+};
+const DRAFT = {
+    path: '/draft',
+    meaning: 'A message written on the page, which a Send button sends.',
+    words: 'A message to send',
+};
+const SEND = {
+    name: 'send',
+    meaning: 'Send a message to the application: the context’s message, or what is written at /draft.',
+    words: 'Send the message',
+    context: ['message'],
+    asks: { message: 'The message it sends' },
+};
+const STOP = {
+    name: 'stop',
+    meaning: 'Stop the answer being written.',
+    words: 'Stop the answer',
+    context: [],
+    asks: {},
+};
+/**
+ * What each kind publishes to its page and takes from it, by path — the
+ * least that is real today, read from the conversation it runs as.
+ */
+export const APP_KIND_PATHS = {
+    chat: {
+        publishes: [
+            APP,
+            {
+                path: '/question',
+                meaning: 'The question last asked.',
+                words: 'The question last asked',
+            },
+            {
+                path: '/answer',
+                meaning: 'Its answer to it, as it is written.',
+                words: 'Its answer',
+            },
+            STATUS,
+        ],
+        accepts: [DRAFT],
+        actions: [
+            SEND,
+            STOP,
+            {
+                name: 'new',
+                meaning: 'Start the conversation over.',
+                words: 'Start over',
+                context: [],
+                asks: {},
+            },
+        ],
+        inputs: true,
+    },
+    widget: {
+        publishes: [
+            APP,
+            {
+                path: '/output',
+                meaning: 'What it gave for the inputs last run, as it is written.',
+                words: 'What it gave',
+            },
+            STATUS,
+        ],
+        accepts: [],
+        actions: [
+            {
+                name: 'run',
+                meaning: 'Run it on its inputs: every value written under /inputs is sent, with the context’s message when there is one.',
+                words: 'Run it on its inputs',
+                context: ['message'],
+                asks: { message: 'What it says before the inputs' },
+            },
+            STOP,
+        ],
+        inputs: true,
+    },
+    worker: {
+        publishes: [
+            APP,
+            {
+                path: '/goal',
+                meaning: 'What it works toward.',
+                words: 'What it works toward',
+            },
+            {
+                path: '/activity',
+                meaning: 'What it is doing right now, in a short line, or nothing.',
+                words: 'What it is doing now',
+            },
+            {
+                path: '/report',
+                meaning: 'What it last said, as it is written.',
+                words: 'What it last said',
+            },
+            STATUS,
+        ],
+        accepts: [DRAFT],
+        actions: [SEND, STOP],
+        inputs: false,
+    },
+};
+/** Whether a kind runs as its conversation and has its paths here. */
+export const isAppPageKind = (kind) => Object.prototype.hasOwnProperty.call(APP_KIND_PATHS, kind);
+/** The path a setting, an input of the page, is kept at. */
+export const inputPath = (id) => `/inputs/${id}`;
+/**
+ * What an application publishes and takes, with its own settings: the kind's
+ * list, and for a kind that has inputs each setting at `/inputs/<id>`, both
+ * shown and written. Empty lists for a decision, or a kind not known.
+ */
+export function appKindPaths(app) {
+    if (!isAppPageKind(app.kind)) {
+        return { publishes: [], accepts: [], actions: [], inputs: false };
+    }
+    const kind = APP_KIND_PATHS[app.kind];
+    if (!kind.inputs) {
+        return kind;
+    }
+    const inputs = app.interface.settings.map(setting => ({
+        path: inputPath(setting.id),
+        meaning: `The setting “${setting.label || setting.id}”.`,
+        words: setting.label || setting.id,
+    }));
+    return {
+        ...kind,
+        publishes: [...kind.publishes, ...inputs],
+        accepts: [...kind.accepts, ...inputs],
+    };
+}
+/** The components its surface has, or none. */
+const surfaceComponents = (app) => app.interface.surface?.components ?? [];
+/**
+ * Whether the workspace draws the application's page: a chat, a widget or a
+ * worker whose layout has one (`page`, `split`). A `chat` layout is the
+ * conversation alone: a surface composed for it is not drawn, which
+ * `surfaceUnshown` says in a sentence.
+ */
+export function hasAppPage(app) {
+    if (!app.agent || !isAppPageKind(app.kind)) {
+        return false;
+    }
+    return app.interface.layout !== 'chat';
+}
+/**
+ * Why a composed surface is not drawn, or `null` when it is (or there is
+ * none): the application's layout is `chat`, the conversation alone.
+ */
+export function surfaceUnshown(app) {
+    if (!app.agent ||
+        !isAppPageKind(app.kind) ||
+        app.interface.layout !== 'chat' ||
+        surfaceComponents(app).length === 0) {
+        return null;
+    }
+    return 'Its page is composed but its layout is chat, the conversation alone: choose page or split to show it.';
+}
+const STATUS_WORDS = {
+    idle: 'Ready',
+    thinking: 'Thinking',
+    streaming: 'Answering',
+    done: 'Answered',
+    error: 'Stopped',
+};
+/** A setting's first value, as its input holds it. */
+export function initialInput(setting) {
+    switch (setting.type) {
+        case 'toggle':
+            return Boolean(setting.default ?? false);
+        case 'select':
+            // A ChoicePicker holds a list of the values chosen.
+            return setting.default === undefined ? [] : [String(setting.default)];
+        case 'slider':
+            return Number(setting.default ?? setting.min ?? 0);
+        case 'number':
+            return setting.max === undefined
+                ? String(setting.default ?? '')
+                : Number(setting.default ?? setting.min ?? 0);
+        default:
+            return String(setting.default ?? '');
+    }
+}
+/** What the conversation publishes to the page, by path, now. */
+export function appPageData(app, turn) {
+    const data = {
+        '/app': app.name,
+        '/status': STATUS_WORDS[turn.status] ?? '',
+    };
+    switch (app.kind) {
+        case 'chat':
+            data['/question'] = turn.user ?? '';
+            data['/answer'] = turn.assistant ?? '';
+            break;
+        case 'widget':
+            data['/output'] = turn.assistant ?? '';
+            break;
+        case 'worker':
+            data['/goal'] = app.goal;
+            data['/activity'] = turn.activity ?? '';
+            data['/report'] = turn.assistant ?? '';
+            break;
+        default:
+            break;
+    }
+    return data;
+}
+/** The page's data model when it is drawn: what is published, the inputs, the draft. */
+export function appPageInitialData(app) {
+    const tree = {};
+    for (const [path, value] of Object.entries(appPageData(app, { id: 0, status: 'idle' }))) {
+        tree[path.slice(1)] = value;
+    }
+    const paths = appKindPaths(app);
+    if (paths.inputs) {
+        tree.inputs = Object.fromEntries(app.interface.settings.map(setting => [
+            setting.id,
+            initialInput(setting),
+        ]));
+    }
+    if (paths.accepts.some(entry => entry.path === DRAFT.path)) {
+        tree.draft = '';
+    }
+    return tree;
+}
+/** One input in words: `Plan: Team`; nothing for an empty one. */
+function inputWords(label, value) {
+    const shown = Array.isArray(value)
+        ? value.map(String).join(', ')
+        : typeof value === 'boolean'
+            ? value
+                ? 'yes'
+                : 'no'
+            : value === undefined || value === null
+                ? ''
+                : String(value);
+    return shown.trim() ? `${label}: ${shown}` : '';
+}
+/**
+ * The inputs written on the page, in words, one per line: each setting by
+ * its label, then any other value a block wrote under `/inputs` by its id.
+ */
+export function inputsInWords(app, inputs) {
+    const values = inputs && typeof inputs === 'object'
+        ? inputs
+        : {};
+    const lines = [];
+    const seen = new Set();
+    for (const setting of app.interface.settings) {
+        seen.add(setting.id);
+        lines.push(inputWords(setting.label || setting.id, values[setting.id]));
+    }
+    for (const [id, value] of Object.entries(values)) {
+        if (!seen.has(id)) {
+            lines.push(inputWords(id, value));
+        }
+    }
+    return lines.filter(Boolean).join('\n');
+}
+/**
+ * What a button pressed on the page does.
+ *
+ * `read` gives what is in the surface's data model at a path; `lastInputs`
+ * is the inputs in words as last sent, so that a chat's message carries its
+ * settings only when they changed.
+ */
+export function appPageAction(app, event, read, lastInputs = '') {
+    const paths = appKindPaths(app);
+    if (!paths.actions.some(action => action.name === event.name)) {
+        const offered = paths.actions.map(action => action.name).join(', ');
+        return {
+            refused: offered
+                ? `“${event.name}” is not something ${app.name} does: it does ${offered}.`
+                : `${app.name} handles no button.`,
+        };
+    }
+    const given = event.context?.message;
+    const message = typeof given === 'string' ? given.trim() : '';
+    const inputs = paths.inputs ? inputsInWords(app, read('/inputs')) : '';
+    switch (event.name) {
+        case 'stop':
+            return { stop: true };
+        case 'new':
+            return { newChat: true };
+        case 'run': {
+            const text = [message, inputs].filter(Boolean).join('\n');
+            return text
+                ? { send: text, inputs, clear: [] }
+                : { refused: `${app.name} has no inputs to run on: set one first.` };
+        }
+        default: {
+            const draft = read(DRAFT.path);
+            const written = message || (typeof draft === 'string' ? draft.trim() : '');
+            if (!written) {
+                return { refused: 'Nothing to send: write a message first.' };
+            }
+            const changed = inputs && inputs !== lastInputs;
+            return {
+                send: changed ? `${written}\n\n${inputs}` : written,
+                inputs,
+                clear: message ? [] : [DRAFT.path],
+            };
+        }
+    }
+}
+const text = (id, path, variant) => ({
+    id,
+    component: 'Text',
+    text: { path },
+    ...(variant ? { variant } : {}),
+});
+const button = (id, label, name, primary = false) => [
+    {
+        id,
+        component: 'Button',
+        child: `${id}-label`,
+        ...(primary ? { variant: 'primary' } : {}),
+        action: { event: { name } },
+    },
+    { id: `${id}-label`, component: 'Text', text: label },
+];
+/** A setting as the input of the catalog that holds its value. */
+function settingInput(setting) {
+    const base = {
+        id: `input-${setting.id}`,
+        label: setting.label || setting.id,
+        value: { path: inputPath(setting.id) },
+    };
+    switch (setting.type) {
+        case 'toggle':
+            return { ...base, component: 'CheckBox' };
+        case 'select':
+            return {
+                ...base,
+                component: 'ChoicePicker',
+                options: setting.options.map(option => ({
+                    label: option,
+                    value: option,
+                })),
+            };
+        case 'slider':
+            return {
+                ...base,
+                component: 'Slider',
+                min: setting.min ?? 0,
+                max: setting.max ?? 100,
+            };
+        case 'number':
+            return setting.max === undefined
+                ? { ...base, component: 'TextField', variant: 'number' }
+                : {
+                    ...base,
+                    component: 'Slider',
+                    min: setting.min ?? 0,
+                    max: setting.max,
+                };
+        default:
+            return { ...base, component: 'TextField' };
+    }
+}
+/**
+ * The page drawn when the application has a page layout and no surface
+ * composed: what its kind publishes, its settings as inputs, and the
+ * buttons its kind handles that the conversation does not already give.
+ */
+export function defaultAppSurface(app) {
+    const inputs = appKindPaths(app).inputs
+        ? app.interface.settings.map(settingInput)
+        : [];
+    const body = [];
+    switch (app.kind) {
+        case 'chat':
+            body.push(text('question', '/question', 'h3'), text('answer', '/answer'), text('status', '/status', 'caption'), ...inputs);
+            break;
+        case 'widget':
+            body.push(...inputs, { id: 'actions', component: 'Row', children: ['run', 'stop'] }, ...button('run', 'Run', 'run', true), ...button('stop', 'Stop', 'stop'), text('status', '/status', 'caption'), text('output', '/output'));
+            break;
+        case 'worker':
+            body.push(text('goal', '/goal', 'h3'), text('status', '/status', 'caption'), text('activity', '/activity', 'caption'), text('report', '/report'));
+            break;
+        default:
+            break;
+    }
+    // The root's children: what is not inside a Row or a Button.
+    const inner = new Set(body.flatMap(component => [
+        ...(Array.isArray(component.children) ? component.children : []),
+        component.child,
+    ].filter((id) => typeof id === 'string')));
+    return [
+        {
+            id: 'root',
+            component: 'Column',
+            children: body
+                .map(component => component.id)
+                .filter(id => !inner.has(id)),
+        },
+        ...body,
+    ];
+}
+/**
+ * The A2UI messages that draw the application's page: its surface composed,
+ * or the default page of its kind, fed its first data.
+ */
+export function appPageMessages(app, catalogId) {
+    const composed = surfaceComponents(app);
+    return [
+        {
+            version: 'v0.9',
+            createSurface: { surfaceId: APP_PAGE_SURFACE_ID, catalogId },
+        },
+        {
+            version: 'v0.9',
+            updateComponents: {
+                surfaceId: APP_PAGE_SURFACE_ID,
+                components: composed.length > 0 ? composed : defaultAppSurface(app),
+            },
+        },
+        {
+            version: 'v0.9',
+            updateDataModel: {
+                surfaceId: APP_PAGE_SURFACE_ID,
+                path: '/',
+                value: appPageInitialData(app),
+            },
+        },
+    ];
+}

package/lib/loop/plugins/app-page/index.d.ts

@@ -0,0 +1,8 @@
+import { type ReactorPlugin } from '@datalayer/reactor';
+import type { AppSpec } from '../../../types/agentspecs';
+export declare const APP_PAGE_PLUGIN_NAME = "@datalayer/loop-plugin-app-page";
+/** The plugin that draws an application's page beside its conversation. */
+export declare function defineAppPagePlugin(app: AppSpec): ReactorPlugin<Record<string, never>, unknown, unknown>;
+export { AppPage, type AppPageProps } from './AppPage';
+export * from './appPage';
+export default defineAppPagePlugin;

package/lib/loop/plugins/app-page/index.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { BrowserIcon } from '@primer/octicons-react';
+import { contribution, definePlugin, } from '@datalayer/reactor';
+import { LoopEditorView } from '../../core';
+import { AppPage } from './AppPage';
+import { APP_PAGE_SURFACE } from './appPage';
+export const APP_PAGE_PLUGIN_NAME = '@datalayer/loop-plugin-app-page';
+/** The plugin that draws an application's page beside its conversation. */
+export function defineAppPagePlugin(app) {
+    // One component per plugin: the editor keeps it, and the application with it.
+    function Page({ workspace }) {
+        return _jsx(AppPage, { app: app, workspace: workspace });
+    }
+    const plugin = definePlugin({
+        name: `${APP_PAGE_PLUGIN_NAME}-${app.id}`,
+        displayName: `${app.name}: its page`,
+        description: `The page of ${app.name}, drawn beside its conversation.`,
+        octicon: 'browser',
+        emoji: app.emoji || undefined,
+        contributes: [
+            contribution(LoopEditorView, {
+                surfaceId: APP_PAGE_SURFACE,
+                title: app.name,
+                icon: BrowserIcon,
+                order: -10,
+                load: async () => ({ default: Page }),
+            }, { id: APP_PAGE_SURFACE, order: -10 }),
+        ],
+    });
+    return plugin;
+}
+export { AppPage } from './AppPage';
+export * from './appPage';
+export default defineAppPagePlugin;

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

@@ -0,0 +1,30 @@
+/**
+ * Datalayer's own characters for the floating assistant, contributed
+ * (LOOP T-24, T-25): the paper clip, the wizard, the cat and the L👀P eyes.
+ * Disabled, they leave the catalogue; another plugin may contribute others.
+ *
+ * @module loop/plugins/assistant-characters
+ */
+import { type ReactorPlugin } from '@datalayer/reactor';
+import { type AssistantCharacter } from '../../../chat/assistant/characters';
+import type { AssistantCharacterData } from '../../../chat/assistant/formats/types';
+import { LoopAssistantCharacter, type AssistantCharacterContribution } from '../../core';
+/** What is read of a reactor here: its contributions to the point. */
+type ContributionsReader = {
+    getContributions: (point: typeof LoopAssistantCharacter) => ReadonlyArray<{
+        value: AssistantCharacterContribution;
+    }>;
+};
+export declare const ASSISTANT_CHARACTERS_PLUGIN_NAME = "@datalayer/loop-plugin-assistant-characters";
+export declare const AssistantCharactersPlugin: ReactorPlugin<Record<string, never>, unknown, unknown>;
+/** The characters the enabled plugins contribute, in contribution order. */
+export declare function assistantCharactersOf(reactor: ContributionsReader): {
+    id: string;
+    character: AssistantCharacter | AssistantCharacterData;
+}[];
+/**
+ * The character an application names, from what is contributed; an id no
+ * enabled plugin contributes is an error that says which ids there are.
+ */
+export declare function assistantCharacterNamed(reactor: ContributionsReader, id: string): AssistantCharacter | AssistantCharacterData;
+export default AssistantCharactersPlugin;

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

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Datalayer's own characters for the floating assistant, contributed
+ * (LOOP T-24, T-25): the paper clip, the wizard, the cat and the L👀P eyes.
+ * Disabled, they leave the catalogue; another plugin may contribute others.
+ *
+ * @module loop/plugins/assistant-characters
+ */
+import { contribution, definePlugin, } from '@datalayer/reactor';
+import { ASSISTANT_CHARACTERS, } from '../../../chat/assistant/characters';
+import { LoopAssistantCharacter, } from '../../core';
+export const ASSISTANT_CHARACTERS_PLUGIN_NAME = '@datalayer/loop-plugin-assistant-characters';
+export const AssistantCharactersPlugin = definePlugin({
+    name: ASSISTANT_CHARACTERS_PLUGIN_NAME,
+    displayName: 'Assistant characters',
+    description: "Datalayer's own characters for the floating assistant: a paper clip, a wizard, a cat and the L👀P eyes.",
+    octicon: 'paperclip',
+    contributes: ASSISTANT_CHARACTERS.map(character => contribution(LoopAssistantCharacter, { id: character.id, character }, { id: character.id })),
+});
+/** The characters the enabled plugins contribute, in contribution order. */
+export function assistantCharactersOf(reactor) {
+    return reactor
+        .getContributions(LoopAssistantCharacter)
+        .map(entry => entry.value);
+}
+/**
+ * The character an application names, from what is contributed; an id no
+ * enabled plugin contributes is an error that says which ids there are.
+ */
+export function assistantCharacterNamed(reactor, id) {
+    const all = assistantCharactersOf(reactor);
+    const found = all.find(entry => entry.id === id);
+    if (!found) {
+        throw new Error(`No enabled plugin contributes the assistant character "${id}"; the characters are ${all.map(entry => entry.id).join(', ') || 'none'}.`);
+    }
+    return found.character;
+}
+export default AssistantCharactersPlugin;