@datalayer/agent-runtimes 1.3.81 → 1.3.82

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

@@ -108,6 +108,12 @@ export type AppRendererProps = Omit<LoopEmbedProps, 'agentId'> & {
      * `instance.appUid`.
      */
     sidebar?: boolean;
+    /**
+     * Draw its computer alone beside its page (R-23): what a deployment's
+     * owner and the editors of its application see of it at its address — its
+     * runtime shows it to them only (decided 2026-10-06). Implied by `sidebar`.
+     */
+    computer?: boolean;
     /**
      * Draw the application in a window (the `window-frame` plugin), its title
      * the application's face and name. A host's own `frameTitle` wins.
@@ -157,11 +163,13 @@ export type AppPreset = {
  *   its page (`app-page`) when it has one, with the Canvas's block plugins
  *   but those of the UI plugins its organization turned off (`pluginsOff`),
  *   whose contributions are the blocks it may draw (R-01b); a thumb and a
- *   comment on each answer when its record keeps feedback (V-18); what it
+ *   comment on each answer when its record keeps feedback (V-18); its
+ *   commands in the composer's `/` menu and its modes beside it (P-19); what it
  *   keeps and for how long, under its prompt before the first message, when
  *   `kept` says it (R-31); with
  *   `sidebar`, its rules and approvals card, its activity feed and its
- *   computer (R-01b, R-23);
+ *   computer (R-01b, R-23); with `computer`, its computer alone — at its
+ *   address, for its owner and the editors of its application;
  *   laid out as `interface.layout` says;
  * - a **decision**: the page its host draws (`page`), as the one view of a
  *   workspace without a conversation (R-02).
@@ -174,6 +182,8 @@ export declare function appPreset(app: AppSpec, options?: {
     pluginsOff?: readonly string[];
     /** Its rules and approvals, its activity and its computer, beside its page. */
     sidebar?: boolean;
+    /** Its computer alone beside its page (R-23): for its owner and editors at its address. */
+    computer?: boolean;
     /** What its record is kept under: its activity's. */
     appUid?: string;
     /**
@@ -207,8 +217,9 @@ export declare const DATALAYER_BOOTSTRAP_AGENTSPEC = "example-simple";
  * The application's accent over the theme its conversation wears, in both
  * modes (LOOP T-05): its bubbles and its one button in its own colour, and
  * not in the theme's default — the chat sets its theme again inside it, so
- * what the page around it set does not reach in.
+ * what the page around it set does not reach in. The accents are `loop`'s
+ * colours: over another theme (T-30) nothing is laid, the theme's own rule.
  */
-export declare function appThemeOverrides(app: AppSpec): ThemeOverrides | undefined;
-export declare function AppRenderer({ app, plugins, instance, onPresence, onSaying, paused, sidebar, frame, page, pluginsOff, ...embed }: AppRendererProps): React.JSX.Element;
+export declare function appThemeOverrides(app: AppSpec, variant: string): ThemeOverrides | undefined;
+export declare function AppRenderer({ app, plugins, instance, onPresence, onSaying, paused, sidebar, computer, frame, page, pluginsOff, ...embed }: AppRendererProps): React.JSX.Element;
 export default AppRenderer;

package/lib/loop/apps/AppRenderer.js

@@ -45,7 +45,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * @module loop/apps/AppRenderer
  */
 import { useMemo } from 'react';
-import { loopAccentStyles } from '@datalayer/primer-addons';
+import { loopAccentStyles, useSystemColorMode, useThemeStore, } from '@datalayer/primer-addons';
 import { defineAgentCapacityPlugin } from '../plugins/agent-capacity';
 import { APP_PAGE_SURFACE, defineAppHostPagePlugin, defineAppPagePlugin, hasAppPage, } from '../plugins/app-page';
 import { CANVAS_BLOCK_PLUGINS, canvasBlocksPluginName, } from '../plugins/canvas-blocks';
@@ -54,6 +54,8 @@ import { dumpAppspec } from './appspec';
 import { defineAppActivityPlugin } from '../plugins/app-activity';
 import { defineAppComputerPlugin } from '../plugins/app-computer';
 import { defineAppRulesPlugin } from '../plugins/app-rules';
+import { defineAppComposerPlugin } from './AppComposer';
+import { modeEffect } from './composer';
 import { defineAppFeedbackPlugin } from './AppFeedback';
 import { defineAppKeptPlugin } from './AppKept';
 import { keepsFeedback } from './feedback';
@@ -105,6 +107,14 @@ export function defineAppPlugin(app) {
         // application's model when it names one (`loop/apps/agent`).
         instructions: app.instructions,
         model: app.model,
+        // Its modes (LOOP P-19), as the session API applies them: the
+        // instructions of the options chosen and the model one names, for the
+        // run they are sent with.
+        ...((app.interface.modes ?? []).length > 0
+            ? {
+                modeEffect: (chosen) => modeEffect(app, chosen),
+            }
+            : {}),
     });
 }
 /**
@@ -146,11 +156,13 @@ export function appLayoutOptions(app) {
  *   its page (`app-page`) when it has one, with the Canvas's block plugins
  *   but those of the UI plugins its organization turned off (`pluginsOff`),
  *   whose contributions are the blocks it may draw (R-01b); a thumb and a
- *   comment on each answer when its record keeps feedback (V-18); what it
+ *   comment on each answer when its record keeps feedback (V-18); its
+ *   commands in the composer's `/` menu and its modes beside it (P-19); what it
  *   keeps and for how long, under its prompt before the first message, when
  *   `kept` says it (R-31); with
  *   `sidebar`, its rules and approvals card, its activity feed and its
- *   computer (R-01b, R-23);
+ *   computer (R-01b, R-23); with `computer`, its computer alone — at its
+ *   address, for its owner and the editors of its application;
  *   laid out as `interface.layout` says;
  * - a **decision**: the page its host draws (`page`), as the one view of a
  *   workspace without a conversation (R-02).
@@ -180,6 +192,12 @@ export function appPreset(app, options = {}) {
         plugins: [
             defineAppPlugin(app),
             ...(withPage ? [defineAppPagePlugin(app), ...blocks] : []),
+            // Its commands in the composer's `/` menu and its modes beside the
+            // composer (LOOP P-19): only for an application that has some.
+            ...((app.interface.commands ?? []).length > 0 ||
+                (app.interface.modes ?? []).length > 0
+                ? [defineAppComposerPlugin(app)]
+                : []),
             // A thumb and a comment on each answer, kept in its record (LOOP
             // V-18): only for an application whose record keeps feedback.
             ...(keepsFeedback(app) ? [defineAppFeedbackPlugin(app)] : []),
@@ -196,7 +214,9 @@ export function appPreset(app, options = {}) {
                     // Its computer, live (R-23).
                     defineAppComputerPlugin(app),
                 ]
-                : []),
+                : options.computer
+                    ? [defineAppComputerPlugin(app)]
+                    : []),
         ],
         workspace: appLayoutOptions(app),
     };
@@ -249,18 +269,19 @@ const NO_PLUGINS = [];
  * The application's accent over the theme its conversation wears, in both
  * modes (LOOP T-05): its bubbles and its one button in its own colour, and
  * not in the theme's default — the chat sets its theme again inside it, so
- * what the page around it set does not reach in.
+ * what the page around it set does not reach in. The accents are `loop`'s
+ * colours: over another theme (T-30) nothing is laid, the theme's own rule.
  */
-export function appThemeOverrides(app) {
+export function appThemeOverrides(app, variant) {
     const accent = app.interface?.accent;
-    return accent
+    return accent && variant === 'loop'
         ? {
             light: loopAccentStyles(accent, 'light'),
             dark: loopAccentStyles(accent, 'dark'),
         }
         : undefined;
 }
-export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, onSaying, paused = false, sidebar = false, frame = false, page, pluginsOff, ...embed }) {
+export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, onSaying, paused = false, sidebar = false, computer = false, frame = false, page, pluginsOff, ...embed }) {
     /*
      * The kind's plugins, made once per application. `LoopEmbed` rebuilds its
      * whole reactor when its plugins change, so a new plugin on every render
@@ -282,6 +303,7 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, o
                 page,
                 pluginsOff,
                 sidebar,
+                computer,
                 appUid: instance?.appUid,
                 ...(deployed ? { kept: { visitor } } : {}),
             });
@@ -293,7 +315,7 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, o
         }
     }, 
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [source, page, off, sidebar, instance?.appUid, deployed, visitor]);
+    [source, page, off, sidebar, computer, instance?.appUid, deployed, visitor]);
     const allPlugins = useMemo(() => ('problem' in preset ? plugins : [...preset.plugins, ...plugins]), [preset, plugins]);
     /*
      * On Datalayer, the application runs on a runtime: allocated with a plain
@@ -311,10 +333,24 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, o
         instance?.deploymentUid,
         instance?.version,
     ]);
+    /*
+     * The theme it runs in (T-30): the one its host says, else the one its
+     * Appspec names, else the page's — the person's own. Its mode likewise;
+     * `auto` is the device's.
+     */
+    const pageTheme = useThemeStore(state => state.theme);
+    const system = useSystemColorMode();
+    const named = app.interface?.theme;
+    const worn = embed.themeVariant ?? named?.variant ?? pageTheme;
+    const namedMode = named?.mode === 'auto'
+        ? system
+        : named?.mode === 'light' || named?.mode === 'dark'
+            ? named.mode
+            : undefined;
     const accent = app.interface?.accent;
-    const themeOverrides = useMemo(() => appThemeOverrides(app), 
+    const themeOverrides = useMemo(() => appThemeOverrides(app, worn), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [accent]);
+    [accent, worn]);
     if ('problem' in preset) {
         return (_jsx("div", { role: "status", style: { padding: 16 }, children: preset.problem }));
     }
@@ -330,13 +366,10 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, o
             }
             : {}), 
         // Its rules, activity and computer on a rail, one at a time (T-07).
-        sidebarRail: sidebar, teamPicker: false, showAgentVariants: false, graph: false, pluginsPanel: false, datalayerAgentSpecId: DATALAYER_BOOTSTRAP_AGENTSPEC, 
+        sidebarRail: sidebar || computer, teamPicker: false, showAgentVariants: false, graph: false, pluginsPanel: false, datalayerAgentSpecId: DATALAYER_BOOTSTRAP_AGENTSPEC, 
         // Where an application runs is decided by its host — the Studio's
         // Preview, the hosted page — not offered to its user.
-        targetFixed: true, 
-        // Applications first (LOOP T-12): an application's conversation wears
-        // the `loop` theme; a host may say otherwise.
-        themeVariant: "loop", themeOverrides: themeOverrides, 
+        targetFixed: true, ...(named ? { themeVariant: named.variant } : {}), ...(namedMode ? { colorMode: namedMode } : {}), themeOverrides: themeOverrides, 
         // Its own face, name and welcome in the chat (T-08); no counters: a
         // person using an application is not asking about tokens.
         presence: {

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

@@ -24,13 +24,20 @@
  *
  * @module loop/apps/appspec
  */
-import type { AppAccent, AppAssistantCharacter, AppEmbedMode, AppVoiceSpec, AppKind, AppLayout, AppSpec } from '../../types/agentspecs';
+import type { AppAccent, AppThemeMode, AppThemeVariant, AppAssistantCharacter, AppEmbedMode, AppVoiceSpec, 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 themes an application may run in (LOOP T-30): Appearance's, as
+ * primer-addons lists them (`themeVariants`), in its order.
+ */
+export declare const APP_THEME_VARIANTS: AppThemeVariant[];
+/** The colour modes a theme is worn in. */
+export declare const APP_THEME_MODES: AppThemeMode[];
 /** The four ways an application sits in another product's page (LOOP D-07). */
 export declare const APP_EMBED_MODES: AppEmbedMode[];
 /**

package/lib/loop/apps/appspec.js

@@ -16,6 +16,23 @@ export const APP_ACCENTS = [
     'sun',
     'violet',
 ];
+/**
+ * The themes an application may run in (LOOP T-30): Appearance's, as
+ * primer-addons lists them (`themeVariants`), in its order.
+ */
+export const APP_THEME_VARIANTS = [
+    'datalayer',
+    'spatial',
+    'lovely',
+    'matrix',
+    'earth',
+    'sand',
+    'ivory',
+    'sun',
+    'loop',
+];
+/** The colour modes a theme is worn in. */
+export const APP_THEME_MODES = ['light', 'dark', 'auto'];
 /** The four ways an application sits in another product's page (LOOP D-07). */
 export const APP_EMBED_MODES = [
     'inline',
@@ -105,6 +122,8 @@ export function emptyAppspec(kind = 'chat') {
             accent: 'green',
             welcome: '',
             starters: [],
+            commands: [],
+            modes: [],
             settings: [],
             components: [],
             outputs: [],
@@ -190,6 +209,39 @@ function parseRule(data) {
         behaviour: oneOf(data.behaviour, BEHAVIOURS, 'ask_first'),
     };
 }
+/** A slash command (LOOP P-19); a wrong one is said by the checks. */
+function parseCommand(data) {
+    return {
+        name: text(data.name),
+        description: text(data.description),
+        prompt: text(data.prompt),
+    };
+}
+/** One position of a mode switch, what it does said only when said. */
+function parseModeOption(data) {
+    const option = {
+        id: text(data.id),
+        label: text(data.label),
+    };
+    for (const key of ['description', 'instructions', 'model']) {
+        if (typeof data[key] === 'string' && data[key]) {
+            option[key] = data[key];
+        }
+    }
+    return option;
+}
+/** A mode switch (LOOP P-19). */
+function parseMode(data) {
+    const mode = {
+        id: text(data.id),
+        label: text(data.label),
+        options: records(data.options).map(parseModeOption),
+    };
+    if (typeof data.default === 'string' && data.default) {
+        mode.default = data.default;
+    }
+    return mode;
+}
 function parseSetting(data) {
     const setting = {
         id: text(data.id),
@@ -246,6 +298,8 @@ function parseInterface(data, kind) {
             label: text(starter.label),
             message: text(starter.message),
         })),
+        commands: records(data.commands).map(parseCommand),
+        modes: records(data.modes).map(parseMode),
         settings: records(data.settings).map(parseSetting),
         components: texts(data.components),
         voice: parseVoice(data.voice),
@@ -260,6 +314,14 @@ function parseInterface(data, kind) {
     if (data.balloon === 'history' || data.balloon === 'current') {
         parsed.balloon = data.balloon;
     }
+    // A theme of Appearance's, or none: an unknown one is said by the checks.
+    if (isData(data.theme) &&
+        APP_THEME_VARIANTS.includes(data.theme.variant)) {
+        parsed.theme = { variant: data.theme.variant };
+        if (APP_THEME_MODES.includes(data.theme.mode)) {
+            parsed.theme.mode = data.theme.mode;
+        }
+    }
     return parsed;
 }
 function parseCriterion(data) {
@@ -516,6 +578,26 @@ function dumpInterface(spec, kind) {
         label: starter.label,
         message: starter.message,
     })))
+        .list('commands', spec.commands.map(command => ({
+        name: command.name,
+        description: command.description,
+        prompt: command.prompt,
+    })))
+        .list('modes', spec.modes.map(mode => {
+        const written = new Writer()
+            .text('id', mode.id, '\u0000')
+            .text('label', mode.label, '\u0000')
+            .list('options', mode.options.map(option => new Writer()
+            .text('id', option.id, '\u0000')
+            .text('label', option.label, '\u0000')
+            .text('description', option.description ?? '')
+            .text('instructions', option.instructions ?? '')
+            .text('model', option.model ?? '').data));
+        if (mode.default) {
+            written.data.default = mode.default;
+        }
+        return written.data;
+    }))
         .list('settings', spec.settings.map(setting => {
         const written = new Writer()
             .text('id', setting.id, '\u0000')
@@ -539,6 +621,11 @@ function dumpInterface(spec, kind) {
     if (spec.balloon) {
         writer.data.balloon = spec.balloon;
     }
+    if (spec.theme) {
+        writer.data.theme = spec.theme.mode
+            ? { variant: spec.theme.variant, mode: spec.theme.mode }
+            : { variant: spec.theme.variant };
+    }
     // Its voice, when it says one (VO-41): a spec made before voice has none.
     if (spec.voice) {
         writer.part('voice', new Writer()

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';
@@ -269,6 +270,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)) {
@@ -477,6 +486,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 +545,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 +623,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,6 +643,84 @@ export function documentShapeProblems(document) {
             required(item, 'label', where);
             required(item, 'message', where);
         });
+        // 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(', ')}`);
+        }
         records(ui.settings, 'interface.settings', (item, where) => {
             required(item, 'id', where);
             required(item, 'type', 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';