@datalayer/agent-runtimes 1.3.81 → 1.3.83

package/lib/loop/apps/checks.js

@@ -39,8 +39,9 @@ import { getTeamSpec } from '../../specs/teams';
 import { getBackendToolSpec } from '../../specs/backendTools';
 import { getTrack } from '../../specs/tracks';
 import { pluginsOffSetupNotes } from '../plugins/canvas-blocks';
-import { isAssistantCharacterId, parseAppspec } from './appspec';
+import { APP_THEME_MODES, APP_THEME_VARIANTS, isAssistantCharacterId, parseAppspec, } from './appspec';
 import { classesOf, splitRef, toolBehaviours } from './rules';
+import { COMMAND_INPUT, COMMAND_NAME, MODE_ID } from './composer';
 import { HOST_NAME, hostToolsOf } from './hostTools';
 export const NOT_READY = 'Not ready';
 export const NEEDS_ATTENTION = 'Needs attention';
@@ -94,6 +95,14 @@ function shapeProblems(app) {
     if (Boolean(app.agent) === Boolean(app.team)) {
         problems.push('An application names who does the work: an `agent`, or a `team`, and not both.');
     }
+    // agentspecs refuses either way round (LOOP E-01): off says why, on says nothing.
+    const because = (app.unavailable_because ?? '').trim();
+    if (!app.enabled && !because) {
+        problems.push('An application that is not offered says why, under `unavailable_because`.');
+    }
+    if (app.enabled && because) {
+        problems.push('An application offered today is available: remove `unavailable_because`, or set `enabled: false`.');
+    }
     if (app.kind === 'decision' && !app.decision) {
         problems.push('A decision application says what it decides, under `decision`.');
     }
@@ -269,6 +278,14 @@ function referenceProblems(app, organizationFrames) {
     if (app.model && !getModel(app.model)) {
         missing('model', app.model);
     }
+    // The model a mode runs on is the catalogue's (LOOP P-19).
+    for (const mode of app.interface.modes ?? []) {
+        for (const option of mode.options) {
+            if (option.model && !getModel(option.model)) {
+                problems.push(`The mode “${mode.id}” runs “${option.id}” on “${option.model}”, which is no model.`);
+            }
+        }
+    }
     // The components it may use, and those its surface uses, are the catalog's (C-13).
     for (const name of app.interface.components ?? []) {
         if (!componentNamed(name)) {
@@ -463,7 +480,6 @@ const ENUMS = {
     behaviour: ['do_it', 'if_asked', 'ask_first', 'leave_to_me'],
     layout: ['chat', 'page', 'split'],
     accent: ['green', 'rose', 'sky', 'lime', 'sun', 'violet'],
-    settingType: ['select', 'text', 'toggle', 'slider', 'number'],
     record: [
         'conversations',
         'actions',
@@ -477,6 +493,8 @@ const ENUMS = {
     visibility: ['private', 'invited', 'organization', 'link', 'public'],
     mode: ['inline', 'bubble', 'panel', 'assistant'],
     balloon: ['history', 'current'],
+    themeVariant: APP_THEME_VARIANTS,
+    themeMode: APP_THEME_MODES,
     trigger: ['schedule', 'event', 'once'],
     criterion: ['metric', 'noul', 'choice', 'score'],
     direction: ['higher', 'lower'],
@@ -534,6 +552,13 @@ export function documentShapeProblems(document) {
         if (item[key] === undefined)
             at(`${where}.${key}`, 'is missing');
     };
+    const unknownKeys = (item, known, where, what) => {
+        for (const key of Object.keys(item)) {
+            if (!known.includes(key)) {
+                at(`${where}.${key}`, `is not a key of ${what}: ${known.join(', ')}`);
+            }
+        }
+    };
     const d = document;
     for (const key of [
         'id',
@@ -605,6 +630,17 @@ export function documentShapeProblems(document) {
         oneOf(ui.layout, ENUMS.layout, 'interface.layout');
         oneOf(ui.accent, ENUMS.accent, 'interface.accent');
         oneOf(ui.balloon, ENUMS.balloon, 'interface.balloon');
+        // The theme it runs in by default (T-30): a theme of Appearance's, a mode.
+        mapping(ui.theme, 'interface.theme', theme => {
+            required(theme, 'variant', 'interface.theme');
+            oneOf(theme.variant, ENUMS.themeVariant, 'interface.theme.variant');
+            oneOf(theme.mode, ENUMS.themeMode, 'interface.theme.mode');
+            for (const key of Object.keys(theme)) {
+                if (key !== 'variant' && key !== 'mode') {
+                    at(`interface.theme.${key}`, 'is not a key of a theme: variant, mode');
+                }
+            }
+        });
         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`');
         }
@@ -614,13 +650,94 @@ export function documentShapeProblems(document) {
             required(item, 'label', where);
             required(item, 'message', where);
         });
-        records(ui.settings, 'interface.settings', (item, where) => {
-            required(item, 'id', where);
-            required(item, 'type', where);
-            required(item, 'label', where);
-            oneOf(item.type, ENUMS.settingType, `${where}.type`);
-            texts(item.options, `${where}.options`);
+        // Its commands and modes in the composer (LOOP P-19), as agentspecs
+        // refuses them: names and ids slash-safe and said once, no key unknown.
+        const named = new Set();
+        records(ui.commands, 'interface.commands', (item, where) => {
+            for (const key of ['name', 'description', 'prompt']) {
+                required(item, key, where);
+                text(item[key], `${where}.${key}`);
+            }
+            unknownKeys(item, ['name', 'description', 'prompt'], where, 'a command');
+            if (typeof item.name === 'string') {
+                if (!COMMAND_NAME.test(item.name)) {
+                    at(`${where}.name`, 'is what follows the slash: lower-case letters, digits and hyphens, a letter first');
+                }
+                if (named.has(item.name)) {
+                    at(`${where}.name`, `names /${item.name} a second time`);
+                }
+                named.add(item.name);
+            }
+            if (typeof item.prompt === 'string') {
+                for (const placeholder of item.prompt.match(/\{[^{}]*\}/g) ?? []) {
+                    if (placeholder !== COMMAND_INPUT) {
+                        at(`${where}.prompt`, `takes the words typed after the command as ${COMMAND_INPUT}, not ${placeholder}`);
+                    }
+                }
+            }
+        });
+        const modeIds = new Set();
+        const choosingModel = [];
+        records(ui.modes, 'interface.modes', (mode, where) => {
+            required(mode, 'id', where);
+            required(mode, 'label', where);
+            required(mode, 'options', where);
+            text(mode.label, `${where}.label`);
+            text(mode.default, `${where}.default`);
+            unknownKeys(mode, ['id', 'label', 'options', 'default'], where, 'a mode');
+            if (typeof mode.id === 'string') {
+                if (!MODE_ID.test(mode.id)) {
+                    at(`${where}.id`, 'is lower-case letters, digits, `_` and `-`, a letter first');
+                }
+                if (modeIds.has(mode.id)) {
+                    at(`${where}.id`, `names the mode ${mode.id} a second time`);
+                }
+                modeIds.add(mode.id);
+            }
+            const optionIds = [];
+            let model = false;
+            records(mode.options, `${where}.options`, (option, place) => {
+                required(option, 'id', place);
+                required(option, 'label', place);
+                for (const key of ['label', 'description', 'instructions', 'model']) {
+                    text(option[key], `${place}.${key}`);
+                }
+                unknownKeys(option, ['id', 'label', 'description', 'instructions', 'model'], place, 'an option');
+                if (typeof option.id === 'string') {
+                    if (!MODE_ID.test(option.id)) {
+                        at(`${place}.id`, 'is lower-case letters, digits, `_` and `-`, a letter first');
+                    }
+                    if (optionIds.includes(option.id)) {
+                        at(`${place}.id`, `names the option ${option.id} a second time`);
+                    }
+                    optionIds.push(option.id);
+                }
+                model ||= typeof option.model === 'string' && option.model !== '';
+            });
+            if (Array.isArray(mode.options) && mode.options.length < 2) {
+                at(`${where}.options`, 'are two at least');
+            }
+            if (typeof mode.default === 'string' &&
+                !optionIds.includes(mode.default)) {
+                at(`${where}.default`, 'is one of its options');
+            }
+            if (model) {
+                choosingModel.push(String(mode.id));
+            }
         });
+        if (choosingModel.length > 1) {
+            at('interface.modes', `let only one mode choose the model, not ${choosingModel.join(', ')}`);
+        }
+        // Its settings are the JSON Schema of a form (C-16), checked as a Form's
+        // schema is; the list of settings of earlier versions is refused.
+        if (Array.isArray(ui.settings)) {
+            at('interface.settings', 'is the JSON Schema of a form, an object of named fields (LOOP C-16), not a list of settings: say each one as a property, its title and its default');
+        }
+        else {
+            mapping(ui.settings, 'interface.settings', settings => {
+                problems.push(...formProblems({ id: 'settings', schema: settings }));
+            });
+        }
         mapping(ui.surface, 'interface.surface', surface => {
             records(surface.components, 'interface.surface.components', (item, where) => {
                 required(item, 'id', where);

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

@@ -0,0 +1,37 @@
+/**
+ * Commands and modes in the composer (LOOP P-19), as rules: what a command
+ * sends, and which option of each mode a run is in. agentspecs' own
+ * (`command_prompt`, `AppInterface.mode_choice`, `mode_effect`), said again
+ * for the page.
+ *
+ * Pure: no React, no network.
+ *
+ * @module loop/apps/composer
+ */
+import type { AppCommandSpec, AppModeEffect, AppSpec } from '../../types/agentspecs';
+/** Where a command's prompt takes the words typed after it. */
+export declare const COMMAND_INPUT = "{input}";
+/** What follows the slash: lower-case letters, digits and hyphens, a letter first. */
+export declare const COMMAND_NAME: RegExp;
+/** The id of a mode or of one of its options. */
+export declare const MODE_ID: RegExp;
+/**
+ * What a command sends: its prompt, the words typed after it in place of
+ * `{input}` — or after the prompt, when it has no `{input}`.
+ */
+export declare function commandPrompt(command: Pick<AppCommandSpec, 'prompt'>, words?: string): string;
+/** The option each mode starts on: its default, else its first. */
+export declare function modeDefaults(app: Pick<AppSpec, 'interface'>): Record<string, string>;
+/**
+ * The option of every mode a run is in: what was chosen, else where each
+ * starts. A mode or an option the application does not have is refused, in a
+ * sentence, as the runtime refuses it.
+ */
+export declare function modeChoice(app: Pick<AppSpec, 'name' | 'interface'>, chosen?: Record<string, string>): Record<string, string>;
+/**
+ * What a run in the modes chosen is told, and the model it runs on —
+ * agentspecs' `mode_effect`: the instructions of every option chosen, in the
+ * order of the modes, and the model of the first that names one. Refused as
+ * {@link modeChoice} refuses.
+ */
+export declare function modeEffect(app: Pick<AppSpec, 'name' | 'interface'>, chosen?: Record<string, string>): AppModeEffect;

package/lib/loop/apps/composer.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Where a command's prompt takes the words typed after it. */
+export const COMMAND_INPUT = '{input}';
+/** What follows the slash: lower-case letters, digits and hyphens, a letter first. */
+export const COMMAND_NAME = /^[a-z](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
+/** The id of a mode or of one of its options. */
+export const MODE_ID = /^[a-z][a-z0-9_-]{0,39}$/;
+/**
+ * What a command sends: its prompt, the words typed after it in place of
+ * `{input}` — or after the prompt, when it has no `{input}`.
+ */
+export function commandPrompt(command, words = '') {
+    const said = words.trim();
+    if (command.prompt.includes(COMMAND_INPUT)) {
+        return command.prompt.split(COMMAND_INPUT).join(said).trim();
+    }
+    return said ? `${command.prompt}\n\n${said}` : command.prompt;
+}
+/** The option each mode starts on: its default, else its first. */
+export function modeDefaults(app) {
+    return Object.fromEntries((app.interface.modes ?? [])
+        .filter(mode => mode.options.length > 0)
+        .map(mode => [mode.id, mode.default || mode.options[0].id]));
+}
+/**
+ * The option of every mode a run is in: what was chosen, else where each
+ * starts. A mode or an option the application does not have is refused, in a
+ * sentence, as the runtime refuses it.
+ */
+export function modeChoice(app, chosen = {}) {
+    const modes = app.interface.modes ?? [];
+    for (const [modeId, optionId] of Object.entries(chosen)) {
+        const mode = modes.find(candidate => candidate.id === modeId);
+        if (!mode) {
+            throw new Error(`${app.name} has no mode “${modeId}”.`);
+        }
+        if (!mode.options.some(option => option.id === optionId)) {
+            throw new Error(`The mode ${mode.label} has no option “${optionId}”.`);
+        }
+    }
+    return { ...modeDefaults(app), ...chosen };
+}
+/**
+ * What a run in the modes chosen is told, and the model it runs on —
+ * agentspecs' `mode_effect`: the instructions of every option chosen, in the
+ * order of the modes, and the model of the first that names one. Refused as
+ * {@link modeChoice} refuses.
+ */
+export function modeEffect(app, chosen = {}) {
+    const choice = modeChoice(app, chosen);
+    const options = (app.interface.modes ?? []).flatMap(mode => mode.options.filter(option => option.id === choice[mode.id]));
+    const instructions = options
+        .map(option => (option.instructions ?? '').trim())
+        .filter(Boolean)
+        .join('\n\n');
+    const model = options.find(option => option.model)?.model ?? undefined;
+    return model ? { instructions, model } : { instructions };
+}

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

@@ -4,11 +4,13 @@
  * @module loop/apps
  */
 export * from './agent';
+export * from './AppComposer';
 export * from './AppFeedback';
 export * from './AppKept';
 export * from './AppRenderer';
 export * from './appspec';
 export * from './checks';
+export * from './composer';
 export * from './computer';
 export * from './feedback';
 export * from './kept';

package/lib/loop/apps/index.js

@@ -8,11 +8,13 @@
  * @module loop/apps
  */
 export * from './agent';
+export * from './AppComposer';
 export * from './AppFeedback';
 export * from './AppKept';
 export * from './AppRenderer';
 export * from './appspec';
 export * from './checks';
+export * from './composer';
 export * from './computer';
 export * from './feedback';
 export * from './kept';

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

@@ -3,6 +3,7 @@ import type { ComponentType, ReactNode } from 'react';
 import type { ExecutionState } from '@datalayer/jupyter-react/kernel-indicator';
 import type { ToolbarItem } from '@datalayer/primer-addons';
 import type { FrontendToolDefinition } from '../../types/tools';
+import type { AppModeEffect } from '../../types/agentspecs';
 import type { ContextSnapshotData } from '../../types/context';
 import type { AssistantCharacter } from '../../chat/assistant/characters';
 import type { AssistantCharacterData } from '../../chat/assistant/formats/types';
@@ -331,8 +332,25 @@ export type CommandContribution = {
      */
     keybinding?: string;
     args?: readonly CommandArgSpec[];
+    /**
+     * Listed in the composer's `/` menu, as an application's commands are
+     * (LOOP P-19). Most commands are not: the menu is for what a person sends,
+     * the palette and `/help` for the rest.
+     */
+    composer?: boolean;
     run: (ctx: LoopCommandContext) => Promise<CommandResult | void>;
 };
+/**
+ * What goes with every run besides the message, as AG-UI's `forwardedProps`:
+ * an application's modes say there which option the person is in (LOOP
+ * P-19). Read when a message is sent, so it says what is true then; what a
+ * page says with its own message (its action, its files) is merged over it,
+ * the `loop` part key by key.
+ */
+export type RunPropsContribution = {
+    id: string;
+    props: () => Record<string, unknown>;
+};
 /** A candidate offered by an `@` namespace. */
 export type MentionCandidate = {
     id: string;
@@ -496,6 +514,12 @@ export type AgentBlueprintContribution = {
     instructions?: string;
     /** The model it runs on in the page, in place of its spec's. */
     model?: string;
+    /**
+     * What the modes chosen in the composer (`forwardedProps.loop.modes`, LOOP
+     * P-19) tell a run turned in the page, and the model it runs on — as the
+     * runtime's session API applies them. Unsaid for an agent with no modes.
+     */
+    modeEffect?: (chosen: Record<string, string>) => AppModeEffect;
 };
 export declare const LoopAgentBlueprint: import("@datalayer/reactor").ContributionPoint<AgentBlueprintContribution>;
 /** One conversation opener a plugin offers on the empty chat. */
@@ -781,6 +805,13 @@ export { onSurfaceRequest, requestSurface, type SurfaceRequestListener, } from '
 export { focusPrompt, onPromptFocusRequest } from './focusRequests';
 /** Slash commands, shared in shape with the CLI. */
 export declare const LoopCommand: import("@datalayer/reactor").ContributionPoint<CommandContribution>;
+/** What goes with every run besides the message (`forwardedProps`). */
+export declare const LoopRunProps: import("@datalayer/reactor").ContributionPoint<RunPropsContribution>;
+/**
+ * The `forwardedProps` of a run: what the contributions say, then what the
+ * sender gave, the `loop` part merged key by key.
+ */
+export declare function runForwardedProps(contributed: readonly RunPropsContribution[], given?: Record<string, unknown>): Record<string, unknown> | undefined;
 /** `@` namespaces. */
 export declare const LoopMention: import("@datalayer/reactor").ContributionPoint<MentionContribution>;
 /** Slot names the shell renders. Slots render everything; points choose one. */

package/lib/loop/core/index.js

@@ -189,6 +189,28 @@ export { onSurfaceRequest, requestSurface, } from './surfaceRequests';
 export { focusPrompt, onPromptFocusRequest } from './focusRequests';
 /** Slash commands, shared in shape with the CLI. */
 export const LoopCommand = defineContributionPoint('loop.command');
+/** What goes with every run besides the message (`forwardedProps`). */
+export const LoopRunProps = defineContributionPoint('loop.runProps');
+/**
+ * The `forwardedProps` of a run: what the contributions say, then what the
+ * sender gave, the `loop` part merged key by key.
+ */
+export function runForwardedProps(contributed, given) {
+    let merged;
+    for (const part of [...contributed.map(entry => entry.props()), given]) {
+        if (!part)
+            continue;
+        const loop = {
+            ...(merged?.loop ?? {}),
+            ...(part.loop ?? {}),
+        };
+        merged = { ...merged, ...part };
+        if (Object.keys(loop).length > 0) {
+            merged.loop = loop;
+        }
+    }
+    return merged;
+}
 /** `@` namespaces. */
 export const LoopMention = defineContributionPoint('loop.mention');
 /** Slot names the shell renders. Slots render everything; points choose one. */

package/lib/loop/embed/AppEmbed.d.ts

@@ -1,7 +1,7 @@
 import type { CSSProperties, JSX, ReactNode } from 'react';
 import type { PluginRef } from '@datalayer/reactor';
-import type { AppAccent, AppEmbedMode, AppSpec } from '../../types/agentspecs';
-import type { ThemeOverrides } from '../../types/chat';
+import type { AppAccent, AppEmbedMode, AppSpec, AppThemeVariant } from '../../types/agentspecs';
+import type { ResumedThread, ThemeOverrides } from '../../types/chat';
 import type { AssistantCharacter } from '../../chat/assistant/characters';
 import type { AssistantCharacterData } from '../../chat/assistant/formats/types';
 import type { PresenceState } from '../../chat/presence/presenceStatus';
@@ -17,7 +17,10 @@ export type AppEmbedProps = {
     mode?: AppEmbedMode;
     /** The host's accent; the application's own by default. */
     accent?: AppAccent;
-    /** Light, dark, or the visitor's system. */
+    /**
+     * Light, dark, or the visitor's system: the host's, else the one the
+     * Appspec names (`interface.theme.mode`, T-30), else the system's.
+     */
     colorMode?: EmbedColorMode;
     /** The host's face, a CSS font family; the theme's by default. */
     font?: string;
@@ -56,7 +59,38 @@ export type AppEmbedProps = {
      * gives under `deployment.embedded.host`.
      */
     host?: AppEmbedHost;
+    /**
+     * Keep the visit's session in the host's storage, and pick it up again
+     * after the page reloads (LOOP D-13); on by default. Off, the session
+     * lasts as long as the page.
+     */
+    resume?: boolean;
+};
+/** What `useEmbedSession` gives the conversation. */
+export type EmbedSession = {
+    /** Whether the kept session was asked for: nothing is drawn before. */
+    ready: boolean;
+    /** The thread the chat goes on with; none where no session is kept. */
+    thread?: ResumedThread;
+    /** Said once, when the session kept is gone: a new one started. */
+    said?: string;
 };
+/**
+ * The visit's session, kept and picked up again (LOOP D-13): on the host's
+ * server with an embed token that names its visit, the session the chat
+ * opens is kept under the application and the visit — in the host's
+ * storage unless `resume` is off, in memory always — and, when the
+ * application is drawn again (the page reloaded, or a token renewed for the
+ * visit), its conversation is asked for and drawn again. One that is gone
+ * or refused is forgotten, said once, and a new one starts. Elsewhere —
+ * on a Datalayer runtime, without a token — nothing is kept.
+ */
+export declare function useEmbedSession({ app, serverUrl, embedToken, resume, }: {
+    app: Pick<AppSpec, 'id' | 'name'>;
+    serverUrl?: string;
+    embedToken?: string;
+    resume?: boolean;
+}): EmbedSession;
 /**
  * The page and the application talking (LOOP D-10): the tools of the host
  * the Appspec names, given to its agent through a chat-extras plugin made
@@ -81,6 +115,8 @@ export type AppFloatingProps = {
     app: AppSpec;
     view: 'floating-small' | 'panel' | 'assistant';
     colorMode: 'light' | 'dark';
+    /** The theme it is drawn in (T-30); the page's when unsaid. */
+    themeVariant?: AppThemeVariant;
     /** The accent and face inside the conversation. */
     themeOverrides: ThemeOverrides;
     /** The assistant's character, in the assistant mode. */
@@ -98,6 +134,8 @@ export type AppFloatingProps = {
     renderer?: Partial<Pick<AppRendererProps, 'pluginsOff' | 'datalayerVisitors' | 'datalayerKept'>>;
     /** What the page gives the application (D-10). */
     host?: AppEmbedHost;
+    /** The visit's session, picked up again after a reload (D-13). */
+    session?: EmbedSession;
 };
 /**
  * The bubble, the panel and the assistant: `ChatFloating`'s chrome in that
@@ -108,14 +146,15 @@ export type AppFloatingProps = {
  * The workspace tells the chrome what the application is doing and what it
  * last said (`onPresence`, `onSaying`).
  */
-export declare function AppFloating({ app, view, colorMode, themeOverrides, character, serverUrl, instance, embedToken, renderer, host, }: AppFloatingProps): JSX.Element;
-/** The `loop` theme, with the application's (or the host's) accent and face. */
-export declare function EmbedThemed({ accent, colorMode, font, children, style, }: {
+export declare function AppFloating({ app, view, colorMode, themeVariant, themeOverrides, character, serverUrl, instance, embedToken, renderer, host, session, }: AppFloatingProps): JSX.Element;
+/** The application's theme (`loop` unless it names one), with its (or the host's) accent and face. */
+export declare function EmbedThemed({ accent, colorMode, font, variant, children, style, }: {
     accent: AppAccent;
     colorMode: 'light' | 'dark';
     font?: string;
+    variant: AppThemeVariant;
     children: ReactNode;
     style?: CSSProperties;
 }): JSX.Element;
-export declare function AppEmbed({ app, mode, accent, colorMode, font, serverUrl, instance, embedToken, height, ownPortal, plugins, host, }: AppEmbedProps): JSX.Element;
+export declare function AppEmbed({ app, mode, accent, colorMode, font, serverUrl, instance, embedToken, height, ownPortal, plugins, host, resume, }: AppEmbedProps): JSX.Element;
 export default AppEmbed;