@datalayer/agent-runtimes 1.3.83 → 1.3.84

package/lib/loop/apps/appspec.js

@@ -3,8 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { BEHAVIOURS } from './rules';
+import { DEFAULT_MAX_FILES, DEFAULT_UPLOAD_MB } from './uploads';
 /** The version of the spec itself. */
 export const APP_SCHEMA = 'loop.app/v1';
+/** The language an application's own words are in, unless it says (LOOP P-26). */
+export const DEFAULT_LANGUAGE = 'en';
 /** The face of an application that has not chosen one. */
 export const DEFAULT_EMOJI = '\u{1F440}';
 export const APP_KINDS = ['chat', 'widget', 'decision', 'worker'];
@@ -124,6 +127,9 @@ export function emptyAppspec(kind = 'chat') {
             starters: [],
             commands: [],
             modes: [],
+            profiles: [],
+            language: DEFAULT_LANGUAGE,
+            translations: {},
             components: [],
             outputs: [],
         },
@@ -170,6 +176,7 @@ const KNOWN_KEYS = [
     'model',
     'skills',
     'backend_tools',
+    'tools',
     'context',
     'contents',
     'connections',
@@ -193,6 +200,19 @@ const KNOWN_KEYS = [
     'avatar',
     'banner',
 ];
+/** Where a check of its code runs (LOOP P-06). */
+const CHECK_STAGES = ['answer', 'tool_call'];
+/** A tool of its own, written in its code (LOOP P-06); a wrong one is said by the checks. */
+function parseTool(data) {
+    return {
+        name: text(data.name),
+        description: text(data.description),
+        parameters: isData(data.parameters)
+            ? data.parameters
+            : { ...NO_HOST_PARAMETERS },
+        does: texts(data.does),
+    };
+}
 function parseConnection(data) {
     return {
         server: text(data.server),
@@ -243,6 +263,67 @@ function parseMode(data) {
     }
     return mode;
 }
+/** A starter, its category said only when it has one (LOOP P-20). */
+function parseStarter(data) {
+    const starter = {
+        label: text(data.label),
+        message: text(data.message),
+    };
+    if (typeof data.category === 'string' && data.category) {
+        starter.category = data.category;
+    }
+    return starter;
+}
+/** One of several assistants in one application (LOOP P-20). */
+function parseProfile(data) {
+    return {
+        id: text(data.id),
+        label: text(data.label),
+        description: text(data.description),
+        instructions: text(data.instructions),
+        model: typeof data.model === 'string' && data.model ? data.model : null,
+        starters: records(data.starters).map(parseStarter),
+    };
+}
+/** Words by key, what is not a word left out. */
+function wordsBy(value) {
+    return Object.fromEntries(Object.entries(isData(value) ? value : {}).filter((entry) => typeof entry[1] === 'string'));
+}
+/** Records by key, what is not one left out. */
+function recordsBy(value) {
+    return Object.fromEntries(Object.entries(isData(value) ? value : {}).filter((entry) => isData(entry[1])));
+}
+const mapValues = (value, map) => Object.fromEntries(Object.entries(value).map(([key, item]) => [key, map(item)]));
+/** An application's words in one other language (LOOP P-26), every key present. */
+function parseTranslation(data) {
+    return {
+        name: text(data.name),
+        description: text(data.description),
+        welcome: text(data.welcome),
+        starters: mapValues(recordsBy(data.starters), starter => ({
+            label: text(starter.label),
+            message: text(starter.message),
+        })),
+        categories: wordsBy(data.categories),
+        settings: mapValues(recordsBy(data.settings), field => ({
+            title: text(field.title),
+            description: text(field.description),
+            options: wordsBy(field.options),
+        })),
+        commands: wordsBy(data.commands),
+        modes: mapValues(recordsBy(data.modes), mode => ({
+            label: text(mode.label),
+            options: mapValues(recordsBy(mode.options), option => ({
+                label: text(option.label),
+                description: text(option.description),
+            })),
+        })),
+        profiles: mapValues(recordsBy(data.profiles), profile => ({
+            label: text(profile.label),
+            description: text(profile.description),
+        })),
+    };
+}
 function parseSurface(data) {
     return {
         protocol: text(data.protocol, DEFAULT_PROTOCOL),
@@ -272,17 +353,27 @@ function parseVoice(data) {
         where: oneOf(voice.where, ['auto', 'device', 'server'], DEFAULT_VOICE.where),
     };
 }
+/** What a person may send without being asked (P-21), as the spec says it. */
+function parseUploads(data) {
+    return {
+        kinds: records(data.kinds).map(kind => ({
+            type: text(kind.type),
+            maxMb: numberOf(kind.max_mb, DEFAULT_UPLOAD_MB),
+        })),
+        maxFiles: numberOf(data.max_files, DEFAULT_MAX_FILES),
+    };
+}
 function parseInterface(data, kind) {
     const parsed = {
         layout: oneOf(data.layout, ['chat', 'page', 'split'], DEFAULT_LAYOUTS[kind]),
         accent: oneOf(data.accent, APP_ACCENTS, 'green'),
         welcome: text(data.welcome),
-        starters: records(data.starters).map(starter => ({
-            label: text(starter.label),
-            message: text(starter.message),
-        })),
+        starters: records(data.starters).map(parseStarter),
         commands: records(data.commands).map(parseCommand),
         modes: records(data.modes).map(parseMode),
+        profiles: records(data.profiles).map(parseProfile),
+        language: text(data.language, DEFAULT_LANGUAGE),
+        translations: mapValues(recordsBy(data.translations), parseTranslation),
         components: texts(data.components),
         voice: parseVoice(data.voice),
         outputs: texts(data.outputs),
@@ -293,6 +384,14 @@ function parseInterface(data, kind) {
     if (isData(data.settings)) {
         parsed.settings = JSON.parse(JSON.stringify(data.settings));
     }
+    // How its settings' fields are drawn (P-20), kept as written: a wrong
+    // widget is said by the checks.
+    if (isData(data.settings_ui)) {
+        parsed.settingsUi = JSON.parse(JSON.stringify(data.settings_ui));
+    }
+    if (isData(data.uploads)) {
+        parsed.uploads = parseUploads(data.uploads);
+    }
     if (isData(data.surface)) {
         parsed.surface = parseSurface(data.surface);
     }
@@ -416,6 +515,12 @@ export function parseAppspec(document) {
     const verified = isData(tests.verified) ? tests.verified : {};
     const record = isData(data.record) ? data.record : {};
     const checks = isData(data.checks) ? data.checks : {};
+    // A check of its code runs on an answer or a tool call (LOOP P-06).
+    for (const check of records(checks.code)) {
+        if (!CHECK_STAGES.includes(check.on)) {
+            problems.push(`The check \`${text(check.name)}\` of its code runs on answer or tool_call, not \`${String(check.on)}\`.`);
+        }
+    }
     const keepFor = text(record.keep_for, DEFAULT_KEEP_FOR);
     if (retentionDays(keepFor) === 0) {
         problems.push(`Cannot read the retention \`${keepFor}\`: write 90_days, 18_months or 1_years.`);
@@ -435,6 +540,7 @@ export function parseAppspec(document) {
         model: text(data.model),
         skills: texts(data.skills),
         backendTools: texts(data.backend_tools),
+        tools: records(data.tools).map(parseTool),
         context: texts(data.context),
         contents: texts(data.contents),
         connections: records(data.connections).map(parseConnection),
@@ -457,6 +563,8 @@ export function parseAppspec(document) {
             cases: records(tests.cases).map(testCase => ({
                 ask: text(testCase.ask),
                 expect: text(testCase.expect),
+                // Decided by its code (LOOP P-06), when it names the function.
+                ...(text(testCase.code) ? { code: text(testCase.code) } : {}),
             })),
             verified: {
                 live: texts(verified.live),
@@ -476,6 +584,11 @@ export function parseAppspec(document) {
             guards: texts(checks.guards),
             gates: texts(checks.gates),
             track: text(checks.track),
+            code: records(checks.code).map(check => ({
+                name: text(check.name),
+                on: oneOf(check.on, CHECK_STAGES, 'answer'),
+                description: text(check.description),
+            })),
         },
         deployment: parseDeployment(isData(data.deployment) ? data.deployment : {}),
         goal: text(data.goal),
@@ -557,16 +670,44 @@ function dumpSurface(surface) {
         .text('composed_by', surface.composedBy)
         .text('composed_at', surface.composedAt).data;
 }
+function dumpStarter(starter) {
+    return new Writer()
+        .text('label', starter.label, '\u0000')
+        .text('message', starter.message, '\u0000')
+        .text('category', starter.category ?? '').data;
+}
+/** Words by key, what is empty left out. */
+const saidWords = (words) => Object.fromEntries(Object.entries(words).filter(([, said]) => said !== ''));
+/** One translation as it is written (P-26): only what it says. */
+function dumpTranslation(words) {
+    const parts = (value, dump) => Object.fromEntries(Object.entries(value).map(([key, item]) => [key, dump(item)]));
+    return new Writer()
+        .text('name', words.name)
+        .text('description', words.description)
+        .text('welcome', words.welcome)
+        .part('starters', parts(words.starters, starter => new Writer()
+        .text('label', starter.label)
+        .text('message', starter.message).data))
+        .part('categories', saidWords(words.categories))
+        .part('settings', parts(words.settings, field => new Writer()
+        .text('title', field.title)
+        .text('description', field.description)
+        .part('options', saidWords(field.options)).data))
+        .part('commands', saidWords(words.commands))
+        .part('modes', parts(words.modes, mode => new Writer().text('label', mode.label).part('options', parts(mode.options, option => new Writer()
+        .text('label', option.label)
+        .text('description', option.description).data)).data))
+        .part('profiles', parts(words.profiles, profile => new Writer()
+        .text('label', profile.label)
+        .text('description', profile.description).data)).data;
+}
 function dumpInterface(spec, kind) {
     const writer = new Writer()
         // A layout is written when it is not the one its kind starts with.
         .value('layout', spec.layout, DEFAULT_LAYOUTS[kind])
         .value('accent', spec.accent, 'green')
         .text('welcome', spec.welcome)
-        .list('starters', spec.starters.map(starter => ({
-        label: starter.label,
-        message: starter.message,
-    })))
+        .list('starters', spec.starters.map(dumpStarter))
         .list('commands', spec.commands.map(command => ({
         name: command.name,
         description: command.description,
@@ -587,8 +728,30 @@ function dumpInterface(spec, kind) {
         }
         return written.data;
     }))
-        .part('settings', spec.settings ? { ...spec.settings } : {})
-        .list('components', spec.components);
+        .list('profiles', (spec.profiles ?? []).map(profile => new Writer()
+        .text('id', profile.id, '\u0000')
+        .text('label', profile.label, '\u0000')
+        .text('description', profile.description)
+        .text('instructions', profile.instructions)
+        .text('model', profile.model ?? '')
+        .list('starters', profile.starters.map(dumpStarter)).data))
+        .part('settings', spec.settings ? { ...spec.settings } : {});
+    // How its settings' fields are drawn (P-20): written when said.
+    if (spec.settingsUi) {
+        writer.data.settings_ui = { ...spec.settingsUi };
+    }
+    writer
+        .text('language', spec.language ?? DEFAULT_LANGUAGE, DEFAULT_LANGUAGE)
+        .part('translations', mapValues(spec.translations ?? {}, dumpTranslation));
+    // What a person may send without being asked (P-21): written when said.
+    if (spec.uploads) {
+        writer.data.uploads = new Writer()
+            .list('kinds', spec.uploads.kinds.map(kind => new Writer()
+            .text('type', kind.type, '\u0000')
+            .value('max_mb', kind.maxMb, DEFAULT_UPLOAD_MB).data))
+            .value('max_files', spec.uploads.maxFiles, DEFAULT_MAX_FILES).data;
+    }
+    writer.list('components', spec.components);
     if (spec.surface) {
         writer.data.surface = dumpSurface(spec.surface);
     }
@@ -664,6 +827,16 @@ export function dumpAppspec(app) {
         .text('model', app.model)
         .list('skills', app.skills)
         .list('backend_tools', app.backendTools)
+        .list('tools', (app.tools ?? []).map(tool => ({
+        name: tool.name,
+        description: tool.description,
+        // No arguments is what it is unless said.
+        ...(JSON.stringify(tool.parameters) ===
+            JSON.stringify(NO_HOST_PARAMETERS)
+            ? {}
+            : { parameters: tool.parameters }),
+        does: tool.does,
+    })))
         .list('context', app.context)
         .list('contents', app.contents)
         .list('connections', app.connections.map(connection => new Writer()
@@ -692,6 +865,7 @@ export function dumpAppspec(app) {
         .list('cases', app.tests.cases.map(testCase => ({
         ask: testCase.ask,
         expect: testCase.expect,
+        ...(testCase.code ? { code: testCase.code } : {}),
     })))
         .part('verified', new Writer()
         .list('live', app.tests.verified.live)
@@ -704,7 +878,12 @@ export function dumpAppspec(app) {
         .part('checks', new Writer()
         .list('guards', app.checks.guards)
         .list('gates', app.checks.gates)
-        .text('track', app.checks.track).data)
+        .text('track', app.checks.track)
+        .list('code', (app.checks.code ?? []).map(check => ({
+        name: check.name,
+        on: check.on,
+        description: check.description,
+    }))).data)
         .part('deployment', new Writer()
         .present('hosted', app.deployment.hosted &&
         new Writer()

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

@@ -14,6 +14,12 @@ export interface AppCheck {
  * UI plugins, by the name a surface gives it.
  */
 export declare const componentNamed: (name: string) => ComponentSpec | undefined;
+/**
+ * What its code declares that agentspecs refuses (LOOP P-06): its tools,
+ * its checks and the tests it decides, each by a Python name, each name
+ * once; a tool says what it does, by class, each class once.
+ */
+export declare function ownCodeProblems(app: AppSpec): string[];
 /** How an organization's own context is named: never a catalogue id (agentspecs' `ORGANIZATION_FRAME_PREFIX`). */
 /**
  * What stops a Form block from asking (LOOP C-16), in agentspecs'

package/lib/loop/apps/checks.js

@@ -43,6 +43,9 @@ import { APP_THEME_MODES, APP_THEME_VARIANTS, isAssistantCharacterId, parseAppsp
 import { classesOf, splitRef, toolBehaviours } from './rules';
 import { COMMAND_INPUT, COMMAND_NAME, MODE_ID } from './composer';
 import { HOST_NAME, hostToolsOf } from './hostTools';
+import { MAX_UPLOAD_MB, UPLOAD_KIND } from './uploads';
+import { formUiProblems } from './settingsInputs';
+import { translationProblems } from './language';
 export const NOT_READY = 'Not ready';
 export const NEEDS_ATTENTION = 'Needs attention';
 export const PASSES = 'Passes the instant checks';
@@ -80,6 +83,54 @@ const matches = (name, pattern) => new RegExp('^' +
             ? '[\\s\\S]'
             : c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('') +
     '$').test(name);
+/** The name of a function of an application's code (agentspecs' `CODE_NAME`). */
+const CODE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * What its code declares that agentspecs refuses (LOOP P-06): its tools,
+ * its checks and the tests it decides, each by a Python name, each name
+ * once; a tool says what it does, by class, each class once.
+ */
+export function ownCodeProblems(app) {
+    const problems = [];
+    const tools = app.tools ?? [];
+    for (const tool of tools) {
+        if (!CODE_NAME.test(tool.name)) {
+            problems.push(`Cannot use “${tool.name}” as a tool's name: letters, digits and \`_\`, as in Python.`);
+        }
+        if (!tool.description.trim()) {
+            problems.push(`The tool “${tool.name}” says what it does, for the agent.`);
+        }
+        if (tool.does.length === 0) {
+            problems.push(`The tool “${tool.name}” says what it does: read, write, send, buy, delete or publish.`);
+        }
+        for (const action of tool.does) {
+            if (!CLASS_NAMES.has(action)) {
+                problems.push(`The tool “${tool.name}” does “${action}”, which is no class of action.`);
+            }
+        }
+        if (new Set(tool.does).size !== tool.does.length) {
+            problems.push('A tool says each thing it does once.');
+        }
+    }
+    const names = tools.map(tool => tool.name);
+    if (new Set(names).size !== names.length) {
+        problems.push('Two of its tools have the same name.');
+    }
+    const checks = (app.checks.code ?? []).map(check => check.name);
+    for (const name of checks) {
+        if (!CODE_NAME.test(name)) {
+            problems.push(`Cannot use “${name}” as a check's name: letters, digits and \`_\`, as in Python.`);
+        }
+    }
+    if (new Set(checks).size !== checks.length) {
+        problems.push('Two checks of its code have the same name.');
+    }
+    const decided = app.tests.cases.flatMap(testCase => testCase.code ? [testCase.code] : []);
+    if (new Set(decided).size !== decided.length) {
+        problems.push('Two tests are decided by the same function of its code.');
+    }
+    return problems;
+}
 /** What the spec says of itself that the tolerant reader lets through. */
 function shapeProblems(app) {
     const problems = [];
@@ -120,6 +171,36 @@ function shapeProblems(app) {
     else if (app.triggers.length > 0) {
         problems.push(`A ${app.kind} application starts when somebody opens it: \`triggers\` are a worker's.`);
     }
+    // Its profiles (LOOP P-20): two at least, or none; each id slash-safe and
+    // said once, each with a label.
+    const profiles = app.interface.profiles ?? [];
+    if (profiles.length === 1) {
+        problems.push('One profile is the application itself: say two at least, or put its instructions, model and starters on the application.');
+    }
+    const profileIds = new Set();
+    for (const profile of profiles) {
+        if (!MODE_ID.test(profile.id)) {
+            problems.push(`Cannot use “${profile.id}” as a profile's id: lower-case letters, digits, \`_\` and \`-\`, a letter first.`);
+        }
+        if (!profile.label.trim()) {
+            problems.push(`The profile “${profile.id}” has no label.`);
+        }
+        if (profileIds.has(profile.id)) {
+            problems.push(`Two profiles are “${profile.id}”.`);
+        }
+        profileIds.add(profile.id);
+    }
+    // How its settings' fields are drawn (P-20): by a widget that draws each.
+    if (app.interface.settingsUi) {
+        if (!app.interface.settings) {
+            problems.push('`settings_ui` draws the settings’ fields: say `settings` first.');
+        }
+        else {
+            problems.push(...formUiProblems('The form “settings”', app.interface.settings, app.interface.settingsUi));
+        }
+    }
+    // Its words in other languages (P-26): of languages, of what it says.
+    problems.push(...translationProblems(app.interface));
     // What the host page passes and offers (D-10): named once each, in words
     // its agent's tools can carry, each function saying what it does.
     const host = app.deployment.embedded?.host;
@@ -154,6 +235,8 @@ function shapeProblems(app) {
             }
         }
     }
+    // What its code declares (LOOP P-06), as agentspecs refuses it.
+    problems.push(...ownCodeProblems(app));
     const servers = app.connections.map(connection => idOf(connection.server));
     if (new Set(servers).size !== servers.length) {
         problems.push('The application connects to the same server twice.');
@@ -212,6 +295,10 @@ export function formProblems(node) {
     if (missing.length > 0) {
         problems.push(`${said} requires ${missing.map(name => `“${String(name)}”`).join(', ')}, which it does not ask.`);
     }
+    // How its fields are drawn (P-20): by a widget that draws each.
+    if (node.ui !== undefined && node.ui !== null) {
+        problems.push(...formUiProblems(said, schema, node.ui));
+    }
     return problems;
 }
 const isPlainRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -278,6 +365,12 @@ function referenceProblems(app, organizationFrames) {
     if (app.model && !getModel(app.model)) {
         missing('model', app.model);
     }
+    // The model a profile runs on is the catalogue's (LOOP P-20).
+    for (const profile of app.interface.profiles ?? []) {
+        if (profile.model && !getModel(profile.model)) {
+            problems.push(`The profile “${profile.id}” runs on “${profile.model}”, which is no 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) {
@@ -336,6 +429,9 @@ function referenceProblems(app, organizationFrames) {
             if (server === undefined) {
                 if (hostTools.includes(target))
                     continue;
+                // A tool of its own, written in its code (LOOP P-06).
+                if ((app.tools ?? []).some(tool => tool.name === target))
+                    continue;
                 if (!getBackendToolSpec(name)) {
                     problems.push(`The rule “${rule.action}” names the tool “${target}”, which the catalogue does not have.`);
                 }
@@ -646,9 +742,44 @@ export function documentShapeProblems(document) {
         }
         text(ui.welcome, 'interface.welcome');
         texts(ui.components, 'interface.components');
-        records(ui.starters, 'interface.starters', (item, where) => {
+        const starter = (item, where) => {
             required(item, 'label', where);
             required(item, 'message', where);
+            text(item.category, `${where}.category`);
+            unknownKeys(item, ['label', 'message', 'category'], where, 'a starter');
+        };
+        records(ui.starters, 'interface.starters', starter);
+        // Its profiles (LOOP P-20), as agentspecs refuses them: no key unknown.
+        records(ui.profiles, 'interface.profiles', (profile, where) => {
+            required(profile, 'id', where);
+            required(profile, 'label', where);
+            for (const key of [
+                'id',
+                'label',
+                'description',
+                'instructions',
+                'model',
+            ]) {
+                text(profile[key], `${where}.${key}`);
+            }
+            unknownKeys(profile, ['id', 'label', 'description', 'instructions', 'model', 'starters'], where, 'a profile');
+            records(profile.starters, `${where}.starters`, starter);
+        });
+        text(ui.language, 'interface.language');
+        mapping(ui.translations, 'interface.translations', translations => {
+            for (const [tag, words] of Object.entries(translations)) {
+                mapping(words, `interface.translations.${tag}`, said => unknownKeys(said, [
+                    'name',
+                    'description',
+                    'welcome',
+                    'starters',
+                    'categories',
+                    'settings',
+                    'commands',
+                    'modes',
+                    'profiles',
+                ], `interface.translations.${tag}`, 'a translation'));
+            }
         });
         // 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.
@@ -738,6 +869,44 @@ export function documentShapeProblems(document) {
                 problems.push(...formProblems({ id: 'settings', schema: settings }));
             });
         }
+        // What a person may send without being asked (LOOP P-21), as agentspecs
+        // refuses it: a kind at least, each a type said once, sizes it takes.
+        mapping(ui.uploads, 'interface.uploads', uploads => {
+            unknownKeys(uploads, ['kinds', 'max_files'], 'interface.uploads', 'uploads');
+            required(uploads, 'kinds', 'interface.uploads');
+            const types = new Set();
+            records(uploads.kinds, 'interface.uploads.kinds', (kind, where) => {
+                required(kind, 'type', where);
+                unknownKeys(kind, ['type', 'max_mb'], where, 'a kind of upload');
+                if (kind.type !== undefined) {
+                    if (typeof kind.type !== 'string' || !UPLOAD_KIND.test(kind.type)) {
+                        at(`${where}.type`, 'is a media type (application/pdf), a family (image/*) or an extension (.csv), lowercase');
+                    }
+                    else if (types.has(kind.type)) {
+                        at(`${where}.type`, `names ${kind.type} a second time`);
+                    }
+                    else {
+                        types.add(kind.type);
+                    }
+                }
+                const size = kind.max_mb;
+                if (size !== undefined &&
+                    (typeof size !== 'number' || size <= 0 || size > MAX_UPLOAD_MB)) {
+                    at(`${where}.max_mb`, `is more than 0 and ${MAX_UPLOAD_MB} at most`);
+                }
+            });
+            if (Array.isArray(uploads.kinds) && uploads.kinds.length === 0) {
+                at('interface.uploads.kinds', 'are one at least');
+            }
+            const most = uploads.max_files;
+            if (most !== undefined &&
+                (typeof most !== 'number' ||
+                    !Number.isInteger(most) ||
+                    most < 1 ||
+                    most > 20)) {
+                at('interface.uploads.max_files', 'is a whole number from 1 to 20');
+            }
+        });
         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

@@ -1,14 +1,15 @@
 /**
- * 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.
+ * Commands, modes and profiles in the composer (LOOP P-19, P-20), as rules:
+ * what a command sends, which option of each mode a run is in, which profile
+ * a conversation is with and what it offers. agentspecs' own
+ * (`command_prompt`, `AppInterface.mode_choice`, `mode_effect`,
+ * `profile_choice`, `starters_for`), said again for the page.
  *
  * Pure: no React, no network.
  *
  * @module loop/apps/composer
  */
-import type { AppCommandSpec, AppModeEffect, AppSpec } from '../../types/agentspecs';
+import type { AppCommandSpec, AppModeEffect, AppProfileSpec, AppSpec, AppStarterSpec } 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. */
@@ -29,9 +30,19 @@ export declare function modeDefaults(app: Pick<AppSpec, 'interface'>): Record<st
  */
 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.
+ * The profile a conversation is with (LOOP P-20): the one chosen, else the
+ * first; undefined for an application without profiles. One it does not have
+ * is refused, in a sentence, as the runtime refuses it.
  */
-export declare function modeEffect(app: Pick<AppSpec, 'name' | 'interface'>, chosen?: Record<string, string>): AppModeEffect;
+export declare function profileChoice(app: Pick<AppSpec, 'name' | 'interface'>, chosen?: string): AppProfileSpec | undefined;
+/** The starters offered with a profile: its own, else the application's (P-20). */
+export declare function startersFor(app: Pick<AppSpec, 'name' | 'interface'>, profile?: string): AppStarterSpec[];
+/**
+ * What a run in the modes chosen, with the profile chosen, is told, and the
+ * model it runs on — agentspecs' `mode_effect`, and the runtime's
+ * `run_effect`: the profile's instructions first, then those of every option
+ * chosen, in the order of the modes; the model of the first option that
+ * names one, else the profile's. Refused as {@link modeChoice} and
+ * {@link profileChoice} refuse.
+ */
+export declare function modeEffect(app: Pick<AppSpec, 'name' | 'interface'>, chosen?: Record<string, string>, profile?: string): AppModeEffect;