@datalayer/agent-runtimes 1.3.80 → 1.3.82

package/lib/loop/apps/checks.js

@@ -39,8 +39,10 @@ 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';
 export const PASSES = 'Passes the instant checks';
@@ -110,6 +112,40 @@ 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.`);
     }
+    // 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;
+    if (host) {
+        for (const name of host.context) {
+            if (!HOST_NAME.test(name)) {
+                problems.push(`Cannot use “${name}” as a value of the host: lower-case letters, digits and \`_\`.`);
+            }
+        }
+        if (new Set(host.context).size !== host.context.length) {
+            problems.push('The host’s values are named once each.');
+        }
+        for (const fn of host.functions) {
+            if (!HOST_NAME.test(fn.name)) {
+                problems.push(`Cannot use “${fn.name}” as a host function: lower-case letters, digits and \`_\`.`);
+            }
+            if (!fn.description.trim()) {
+                problems.push(`The host function “${fn.name}” says what it does.`);
+            }
+            if (fn.parameters.type !== 'object') {
+                problems.push(`The host function “${fn.name}” takes its arguments as a JSON Schema of \`type: object\`.`);
+            }
+        }
+        const names = host.functions.map(fn => fn.name);
+        if (new Set(names).size !== names.length) {
+            problems.push('The host’s functions are named once each.');
+        }
+        const named = new Set(app.rules.flatMap(rule => rule.appliesTo));
+        for (const tool of hostToolsOf(host)) {
+            if (!named.has(tool)) {
+                problems.push(`No rule names “${tool}”, which the host page offers it: it is left to the person until a rule decides it.`);
+            }
+        }
+    }
     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.');
@@ -234,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)) {
@@ -274,12 +318,16 @@ function referenceProblems(app, organizationFrames) {
             problems.push(`The application may write through “${connection.server}”, whose tools nobody has classed: every one of them is left to the person until they are.`);
         }
     }
+    // The tools of the host page are the application's own (D-10).
+    const hostTools = hostToolsOf(app.deployment.embedded?.host);
     for (const rule of app.rules) {
         for (const target of rule.appliesTo) {
             if (CLASS_NAMES.has(target))
                 continue;
             const [server, name] = splitRef(target);
             if (server === undefined) {
+                if (hostTools.includes(target))
+                    continue;
                 if (!getBackendToolSpec(name)) {
                     problems.push(`The rule “${rule.action}” names the tool “${target}”, which the catalogue does not have.`);
                 }
@@ -438,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'],
@@ -495,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',
@@ -566,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`');
         }
@@ -575,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);
@@ -628,6 +774,10 @@ export function documentShapeProblems(document) {
                         !/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(hosted.slug)))) {
                 at('deployment.hosted.slug', 'is lower-case letters, digits and hyphens');
             }
+            if (hosted.character_alone !== undefined &&
+                typeof hosted.character_alone !== 'boolean') {
+                at('deployment.hosted.character_alone', 'is true or false');
+            }
         });
         mapping(deployment.embedded, 'deployment.embedded', embedded => {
             oneOf(embedded.mode, ENUMS.mode, 'deployment.embedded.mode');
@@ -640,6 +790,16 @@ export function documentShapeProblems(document) {
                     }
                 });
             }
+            mapping(embedded.host, 'deployment.embedded.host', host => {
+                texts(host.context, 'deployment.embedded.host.context');
+                records(host.functions, 'deployment.embedded.host.functions', (item, where) => {
+                    required(item, 'name', where);
+                    required(item, 'description', where);
+                    text(item.name, `${where}.name`);
+                    text(item.description, `${where}.description`);
+                    mapping(item.parameters, `${where}.parameters`, () => undefined);
+                });
+            });
         });
     });
     records(d.triggers, 'triggers', (item, 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/hostTools.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The tools an embedded application is given for its host page (LOOP D-10),
+ * by name: `host_context` for the values the page passes, `host_<name>` for
+ * each function it offers. Apart from `embed/hostBridge`, which calls the
+ * page, so that the checks read them as a pure module.
+ *
+ * @module loop/apps/hostTools
+ */
+import type { AppHostBridgeSpec } from '../../types/agentspecs';
+/** The tool its agent reads what the page passes it with. */
+export declare const HOST_CONTEXT_TOOL = "host_context";
+/** The tool its agent calls a function of the page with. */
+export declare const hostTool: (name: string) => string;
+/** How a value or a function of the host is named. */
+export declare const HOST_NAME: RegExp;
+/** The tools its agent is given for the host. */
+export declare function hostToolsOf(bridge: AppHostBridgeSpec | undefined): string[];

package/lib/loop/apps/hostTools.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The tool its agent reads what the page passes it with. */
+export const HOST_CONTEXT_TOOL = 'host_context';
+/** The tool its agent calls a function of the page with. */
+export const hostTool = (name) => `host_${name}`;
+/** How a value or a function of the host is named. */
+export const HOST_NAME = /^[a-z][a-z0-9_]{0,62}$/;
+/** The tools its agent is given for the host. */
+export function hostToolsOf(bridge) {
+    if (!bridge) {
+        return [];
+    }
+    return [
+        ...(bridge.context.length > 0 ? [HOST_CONTEXT_TOOL] : []),
+        ...bridge.functions.map(fn => hostTool(fn.name)),
+    ];
+}

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/apps/rules.d.ts

@@ -28,11 +28,32 @@ export declare function matchesPattern(name: string, pattern: string): boolean;
 export declare const isComparable: (value: unknown) => boolean;
 /** Whether the arguments of a call make a condition true. */
 export declare function conditionHolds(condition: ActionConditionSpec, args: ToolArguments): boolean;
+/** Where a call of a tool that forwards mail says what it forwards, from where, and to whom. */
+export type Forwarding = {
+    /** The argument naming the message forwarded; a call without it does not forward. */
+    message: string;
+    /** The argument holding the address of the mailbox it sends from. */
+    mailbox: string;
+    /** The arguments holding its recipients. */
+    recipients: string[];
+};
+/** The tools that forward a message, by `server.tool` — as `agentspecs.actions.FORWARDING`. */
+export declare const FORWARDING: Record<string, Forwarding>;
+/** The mail addresses an argument holds — one, several separated by commas, or a list — in lower case. */
+export declare function addresses(value: unknown): string[];
+/**
+ * Whether a call forwards a message to somebody outside the organization
+ * (LOOP W-04): the domain of the mailbox it sends from. Fails closed: a
+ * forward that does not say its mailbox is outside. A reply is not a forward.
+ */
+export declare function forwardsOutside(server: string, name: string, args: ToolArguments): boolean;
 /**
  * The classes of a tool, by reference; empty when nobody classed it.
  *
  * With the arguments of a call, the classes of that call. Without them,
- * everything the tool can do: nobody said what it is asked.
+ * everything the tool can do: nobody said what it is asked. A forward
+ * outside the organization is told from the call (`forwardsOutside`): it
+ * publishes besides sending.
  */
 export declare function classesOf(ref: string, args?: ToolArguments): ActionClass[];
 /** Whether a tool only reads. An unknown tool — no class — does not. */

package/lib/loop/apps/rules.js

@@ -129,11 +129,53 @@ function entryOf(server, name) {
     }
     return [[...actions.default], []];
 }
+/** The tools that forward a message, by `server.tool` — as `agentspecs.actions.FORWARDING`. */
+export const FORWARDING = {
+    'google-workspace.send_gmail_message': {
+        message: 'forward_message_id',
+        mailbox: 'user_google_email',
+        recipients: ['to', 'cc', 'bcc'],
+    },
+};
+/** The mail addresses an argument holds — one, several separated by commas, or a list — in lower case. */
+export function addresses(value) {
+    const items = Array.isArray(value) ? value : [value];
+    return items
+        .filter((item) => typeof item === 'string')
+        .flatMap(item => item.split(','))
+        .map(part => {
+        const angled = /<([^>]*)>/.exec(part);
+        return (angled ? angled[1] : part).trim().toLowerCase();
+    })
+        .filter(address => address.includes('@'));
+}
+const domainOf = (address) => address.slice(address.lastIndexOf('@') + 1).trim();
+/**
+ * Whether a call forwards a message to somebody outside the organization
+ * (LOOP W-04): the domain of the mailbox it sends from. Fails closed: a
+ * forward that does not say its mailbox is outside. A reply is not a forward.
+ */
+export function forwardsOutside(server, name, args) {
+    const forwarding = own(FORWARDING, `${server}.${name}`);
+    const message = forwarding ? args[forwarding.message] : undefined;
+    if (!forwarding || typeof message !== 'string' || !message.trim()) {
+        return false;
+    }
+    const [home] = addresses(args[forwarding.mailbox]);
+    if (!home) {
+        return true;
+    }
+    return forwarding.recipients
+        .flatMap(field => addresses(args[field]))
+        .some(address => domainOf(address) !== domainOf(home));
+}
 /**
  * The classes of a tool, by reference; empty when nobody classed it.
  *
  * With the arguments of a call, the classes of that call. Without them,
- * everything the tool can do: nobody said what it is asked.
+ * everything the tool can do: nobody said what it is asked. A forward
+ * outside the organization is told from the call (`forwardsOutside`): it
+ * publishes besides sending.
  */
 export function classesOf(ref, args) {
     const [server, name] = splitRef(ref);
@@ -150,6 +192,12 @@ export function classesOf(ref, args) {
             }
         }
     }
+    if (args !== undefined &&
+        classes.length > 0 &&
+        !classes.includes('publish') &&
+        forwardsOutside(server, name, args)) {
+        classes.push('publish');
+    }
     return classes;
 }
 /** Whether a tool only reads. An unknown tool — no class — does not. */

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. */