@datalayer/agent-runtimes 1.3.81 → 1.3.82

package/lib/loop/embed/embedSession.js

@@ -0,0 +1,136 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Where a visit's session is kept in the host's storage: `<prefix>:<app>:<visit>`. */
+export const EMBED_SESSION_KEY_PREFIX = 'datalayer-app:session';
+/**
+ * The visit an embed token was issued for: its `visit` claim, read without
+ * checking the signature — the runtime checks the token; the page only
+ * needs the name to keep the session under.
+ */
+export function visitOfToken(token) {
+    const payload = token?.split('.')[1];
+    if (!payload) {
+        return undefined;
+    }
+    try {
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+        const claims = JSON.parse(atob(padded));
+        return typeof claims.visit === 'string' && claims.visit
+            ? claims.visit
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The key a visit's session is kept under. */
+export function embedSessionKey(app, visit) {
+    return `${EMBED_SESSION_KEY_PREFIX}:${app}:${visit}`;
+}
+/** The sessions of this page, while it lives. */
+const IN_MEMORY = new Map();
+/** The host's `localStorage`, when there is one the page may use. */
+function hostStorage() {
+    try {
+        return typeof window !== 'undefined' ? window.localStorage : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The keeper of a visit's session: in memory, and — unless the host opted
+ * out — in its storage too, read first. Every access to the storage is
+ * guarded: a page whose storage is blocked, full or absent keeps the
+ * session in memory and resumes nothing after a reload.
+ */
+export function sessionKeeper({ persist, storage = hostStorage, }) {
+    return {
+        read: key => {
+            if (persist) {
+                try {
+                    const kept = storage()?.getItem(key);
+                    if (kept) {
+                        return kept;
+                    }
+                }
+                catch {
+                    // No storage: what the page holds in memory.
+                }
+            }
+            return IN_MEMORY.get(key);
+        },
+        keep: (key, uid) => {
+            IN_MEMORY.set(key, uid);
+            if (persist) {
+                try {
+                    storage()?.setItem(key, uid);
+                }
+                catch {
+                    // Kept in memory only.
+                }
+            }
+        },
+        forget: key => {
+            IN_MEMORY.delete(key);
+            try {
+                storage()?.removeItem(key);
+            }
+            catch {
+                // Nothing kept there to forget.
+            }
+        },
+    };
+}
+/** Forget what this page holds in memory (a test). */
+export function forgetSessionsInMemory() {
+    IN_MEMORY.clear();
+}
+/**
+ * A session's conversation as the chat draws it, from the AG-UI messages
+ * the runtime says (`GET …/sessions/{uid}/messages`): what was said and
+ * answered, in words. A page an answer drew is not drawn again here.
+ */
+export function messagesOfThread(messages) {
+    if (!Array.isArray(messages)) {
+        return [];
+    }
+    const drawn = [];
+    for (const message of messages) {
+        if (!message || typeof message !== 'object') {
+            continue;
+        }
+        const { id, role, content } = message;
+        if ((role === 'user' || role === 'assistant') &&
+            typeof id === 'string' &&
+            typeof content === 'string' &&
+            content.trim()) {
+            drawn.push({ id, role, content, createdAt: new Date() });
+        }
+    }
+    return drawn;
+}
+/**
+ * Ask the server that runs the application for a session's conversation,
+ * with the visit's token. Anything but an answer — a session the runtime
+ * let go, another visit's, a token refused, a server out of reach — is
+ * `gone`: a new session starts.
+ */
+export async function reattachSession({ serverUrl, uid, token, fetcher = fetch, }) {
+    try {
+        const response = await fetcher(`${serverUrl.replace(/\/+$/, '')}/api/v1/apps/sessions/${encodeURIComponent(uid)}/messages`, { headers: { Authorization: `Bearer ${token}` } });
+        if (!response.ok) {
+            return { kind: 'gone', uid };
+        }
+        const body = (await response.json());
+        return { kind: 'resumed', uid, messages: messagesOfThread(body.messages) };
+    }
+    catch {
+        return { kind: 'gone', uid };
+    }
+}
+/** What the page says, once, when the conversation it kept is gone. */
+export const sessionGoneSentence = (name) => `Your earlier conversation with ${name} has ended, so this is a new one.`;

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

@@ -1,24 +1,27 @@
 import { type ThemeStyles } from '@datalayer/primer-addons';
-import type { AppAccent } from '../../types/agentspecs';
+import type { AppAccent, AppThemeVariant } from '../../types/agentspecs';
 import type { ThemeOverrides } from '../../types/chat';
 /**
- * The `loop` theme as the embed wears it: the application's accent over it
- * in both modes (T-05), and the host's face when it named one.
+ * The theme as the embed wears it — `loop`, or the one the application
+ * names (T-30) — with the application's accent over `loop` in both modes
+ * (T-05), and the host's face when it named one.
  */
-export declare function embedThemeStyles({ accent, font, }: {
+export declare function embedThemeStyles({ accent, font, variant, }: {
     accent: AppAccent;
     font?: string;
+    variant?: AppThemeVariant;
 }): ThemeStyles;
 /**
  * The same accent and face laid over the conversation's own theme (T-05,
- * D-11): the chat sets the `loop` theme again inside it, which would put the
- * theme's mint and face back over what the embed set around it. The
- * accent's properties in each mode, and, when the host named a face, every
- * property of the theme that names its own.
+ * D-11): the chat sets its theme again inside it, which would put the
+ * theme's colours and face back over what the embed set around it. The
+ * accent's properties in each mode (over `loop` only), and, when the host
+ * named a face, every property of the theme that names its own.
  */
-export declare function embedThemeOverrides({ accent, font, }: {
+export declare function embedThemeOverrides({ accent, font, variant, }: {
     accent: AppAccent;
     font?: string;
+    variant?: AppThemeVariant;
 }): ThemeOverrides;
 /**
  * The element's own stylesheet, written into its shadow root.

package/lib/loop/embed/embedTheme.js

@@ -2,46 +2,56 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { loopAccentStyles, loopFontFamily, loopThemeStyles, scopeThemeCss, THEME_SCOPE_ATTRIBUTE, } from '@datalayer/primer-addons';
+import { getThemeConfig, loopAccentStyles, loopFontFamily, scopeThemeCss, THEME_SCOPE_ATTRIBUTE, } from '@datalayer/primer-addons';
 /** One mode's properties, with the theme's face replaced by the host's. */
-function withFace(styles, font) {
-    if (!font) {
+function withFace(styles, font, own) {
+    if (!font || !own) {
         return styles;
     }
     return Object.fromEntries(Object.entries(styles).map(([name, value]) => [
         name,
-        typeof value === 'string'
-            ? value.split(loopFontFamily).join(font)
-            : value,
+        typeof value === 'string' ? value.split(own).join(font) : value,
     ]));
 }
+/** The face a theme names in a mode: `loop`'s own, or the theme's `fontFamily`. */
+function faceOf(variant, styles) {
+    if (variant === 'loop') {
+        return loopFontFamily;
+    }
+    return typeof styles.fontFamily === 'string' ? styles.fontFamily : '';
+}
+/** The accent over a theme: `loop`'s colours, over `loop` only (T-30). */
+const accentOver = (variant, accent, which) => variant === 'loop' ? loopAccentStyles(accent, which) : {};
 /**
- * The `loop` theme as the embed wears it: the application's accent over it
- * in both modes (T-05), and the host's face when it named one.
+ * The theme as the embed wears it — `loop`, or the one the application
+ * names (T-30) — with the application's accent over `loop` in both modes
+ * (T-05), and the host's face when it named one.
  */
-export function embedThemeStyles({ accent, font = '', }) {
-    const mode = (which) => withFace({
-        ...loopThemeStyles[which],
-        ...loopAccentStyles(accent, which),
-    }, font);
+export function embedThemeStyles({ accent, font = '', variant = 'loop', }) {
+    const base = getThemeConfig(variant).themeStyles;
+    const mode = (which) => {
+        const theme = base[which];
+        return withFace({ ...theme, ...accentOver(variant, accent, which) }, font, faceOf(variant, theme));
+    };
     return {
-        ...loopThemeStyles,
+        ...base,
         light: mode('light'),
         dark: mode('dark'),
     };
 }
 /**
  * The same accent and face laid over the conversation's own theme (T-05,
- * D-11): the chat sets the `loop` theme again inside it, which would put the
- * theme's mint and face back over what the embed set around it. The
- * accent's properties in each mode, and, when the host named a face, every
- * property of the theme that names its own.
+ * D-11): the chat sets its theme again inside it, which would put the
+ * theme's colours and face back over what the embed set around it. The
+ * accent's properties in each mode (over `loop` only), and, when the host
+ * named a face, every property of the theme that names its own.
  */
-export function embedThemeOverrides({ accent, font = '', }) {
+export function embedThemeOverrides({ accent, font = '', variant = 'loop', }) {
+    const base = getThemeConfig(variant).themeStyles;
     const mode = (which) => {
-        const theme = loopThemeStyles[which];
-        const faced = Object.fromEntries(Object.entries(withFace(theme, font)).filter(([name, value]) => typeof value === 'string' && value !== theme[name]));
-        return { ...faced, ...loopAccentStyles(accent, which) };
+        const theme = base[which];
+        const faced = Object.fromEntries(Object.entries(withFace(theme, font, faceOf(variant, theme))).filter(([name, value]) => typeof value === 'string' && value !== theme[name]));
+        return { ...faced, ...accentOver(variant, accent, which) };
     };
     return { light: mode('light'), dark: mode('dark') };
 }

package/lib/loop/index.d.ts

@@ -6,7 +6,7 @@
  *
  * @module loop
  */
-export { LoopCommand, LoopDocumentToolbar, LoopMention, LoopNotebookToolbar, LoopSlots, LoopViewType, canOpenView, createPromptChannel, parseCommand, type CommandArgSpec, type CommandContribution, type CommandResult, type EditorToolbarContext, type EditorToolbarContribution, type LoopCommandContext, type LoopViewProps, type LoopWorkspaceContext, type MentionCandidate, type MentionContribution, type PromptChannel, type SandboxSnapshot, type SandboxState, type ViewControls, type ViewTypeContribution, useLoopPromptStore, suggestLoopPrompt, focusPrompt, onPromptFocusRequest, type LoopPromptState, type SuggestedPrompt, } from './core';
+export { LoopCommand, LoopDocumentToolbar, LoopMention, LoopNotebookToolbar, LoopRunProps, LoopSlots, LoopViewType, canOpenView, createPromptChannel, parseCommand, runForwardedProps, type CommandArgSpec, type CommandContribution, type CommandResult, type EditorToolbarContext, type EditorToolbarContribution, type LoopCommandContext, type LoopViewProps, type LoopWorkspaceContext, type MentionCandidate, type MentionContribution, type PromptChannel, type RunPropsContribution, type SandboxSnapshot, type SandboxState, type ViewControls, type ViewTypeContribution, useLoopPromptStore, suggestLoopPrompt, focusPrompt, onPromptFocusRequest, type LoopPromptState, type SuggestedPrompt, } from './core';
 export { useEditorToolbar } from './core/toolbar';
 export { LoopWorkspace, PluginToggles, ViewSwitcher, WorkspaceFullScreenAction, buildLoopReactor, useWorkspaceFullScreen, type LoopWorkspaceProps, type PluginTogglesProps, type ViewSwitcherProps, } from './shell';
 export { A2uiPlugin, A2UI_PLUGIN_NAME } from './plugins/a2ui';
@@ -67,10 +67,11 @@ export { WindowFrame, WindowFramePlugin, WINDOW_ACTIONS_SLOT, WINDOW_CONTROLS_SL
 export { LoopCommandsPlugin, COMMANDS_PLUGIN_NAME } from './plugins/commands';
 export { PromptPlugin, PROMPT_PLUGIN_NAME } from './plugins/prompt';
 export { LoopEmbed, type LoopEmbedProps } from './embed/LoopEmbed';
-export { AppEmbed, AppFloating, embedAssistantCharacter, type AppEmbedProps, type AppFloatingProps, useHostBridge, } from './embed/AppEmbed';
+export { AppEmbed, AppFloating, embedAssistantCharacter, type AppEmbedProps, type AppFloatingProps, type EmbedSession, useEmbedSession, useHostBridge, } from './embed/AppEmbed';
+export { EMBED_SESSION_KEY_PREFIX, embedSessionKey, visitOfToken, } from './embed/embedSession';
 export { HOST_CONTEXT_TOOL, hostFrontendTools, hostNotAllowed, hostRefused, hostTool, hostToolsOf, type AppEmbedHost, type HostEvent, type HostFunction, type HostQuestion, } from './embed/hostBridge';
 export { defineDatalayerAppElement, type DatalayerAppElementOptions, } from './embed/element';
-export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, type EmbedLook, type EmbedSnippetOptions, } from './embed/embedConfig';
+export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, resumeOf, type EmbedLook, type EmbedSnippetOptions, } from './embed/embedConfig';
 export { SubagentActivityPlugin, SubagentPulse, SUBAGENT_ACTIVITY_PLUGIN_NAME, } from './plugins/subagent-activity';
 export { loopPlugins, type LoopPresetOptions } from './presets';
 export { DocumentExtension, NotebookExtension } from './extensions';

package/lib/loop/index.js

@@ -11,7 +11,7 @@
  * @module loop
  */
 // The contracts. A plugin depends on these and on the reactor, never on the shell.
-export { LoopCommand, LoopDocumentToolbar, LoopMention, LoopNotebookToolbar, LoopSlots, LoopViewType, canOpenView, createPromptChannel, parseCommand, useLoopPromptStore, suggestLoopPrompt, focusPrompt, onPromptFocusRequest, } from './core';
+export { LoopCommand, LoopDocumentToolbar, LoopMention, LoopNotebookToolbar, LoopRunProps, LoopSlots, LoopViewType, canOpenView, createPromptChannel, parseCommand, runForwardedProps, useLoopPromptStore, suggestLoopPrompt, focusPrompt, onPromptFocusRequest, } from './core';
 export { useEditorToolbar } from './core/toolbar';
 // The shell.
 export { LoopWorkspace, PluginToggles, ViewSwitcher, WorkspaceFullScreenAction, buildLoopReactor, useWorkspaceFullScreen, } from './shell';
@@ -87,11 +87,12 @@ export { PromptPlugin, PROMPT_PLUGIN_NAME } from './plugins/prompt';
 export { LoopEmbed } from './embed/LoopEmbed';
 // An application in another product's page: the React component, the
 // `<datalayer-app>` element, and the snippet a host pastes (LOOP D-07 to D-09).
-export { AppEmbed, AppFloating, embedAssistantCharacter, useHostBridge, } from './embed/AppEmbed';
+export { AppEmbed, AppFloating, embedAssistantCharacter, useEmbedSession, useHostBridge, } from './embed/AppEmbed';
+export { EMBED_SESSION_KEY_PREFIX, embedSessionKey, visitOfToken, } from './embed/embedSession';
 // The host page and an embedded application, talking (LOOP D-10).
 export { HOST_CONTEXT_TOOL, hostFrontendTools, hostNotAllowed, hostRefused, hostTool, hostToolsOf, } from './embed/hostBridge';
 export { defineDatalayerAppElement, } from './embed/element';
-export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, } from './embed/embedConfig';
+export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, resumeOf, } from './embed/embedConfig';
 export { SubagentActivityPlugin, SubagentPulse, SUBAGENT_ACTIVITY_PLUGIN_NAME, } from './plugins/subagent-activity';
 // The set a workspace normally has, so a host starts from a working Loop
 // rather than assembling one — and never from the example.

package/lib/loop/plugins/agent-capacity/index.d.ts

@@ -17,7 +17,7 @@
  * @module loop/plugins/agent-capacity
  */
 import { type ReactorPlugin } from '@datalayer/reactor';
-import { type ChatSuggestionItem } from '../../core';
+import { type AgentBlueprintContribution, type ChatSuggestionItem } from '../../core';
 export type AgentCapacityOptions = {
     /** Short slug: `hooks`, `codemode`, … names the plugin `…-agent-<key>`. */
     key: string;
@@ -38,6 +38,8 @@ export type AgentCapacityOptions = {
     instructions?: string;
     /** The model it runs on in the page, in place of its spec's. */
     model?: string;
+    /** What its modes tell a run turned in the page (LOOP P-19). */
+    modeEffect?: AgentBlueprintContribution['modeEffect'];
 };
 export declare function defineAgentCapacityPlugin(options: AgentCapacityOptions): ReactorPlugin<Record<string, never>, unknown, unknown>;
 export default defineAgentCapacityPlugin;

package/lib/loop/plugins/agent-capacity/index.js

@@ -23,7 +23,7 @@
 import { contribution, definePlugin, } from '@datalayer/reactor';
 import { LoopAgentBlueprint, LoopChatSuggestion, } from '../../core';
 export function defineAgentCapacityPlugin(options) {
-    const { key, displayName, description, specId, octicon, emoji, codemode, createPayload, suggestions, instructions, model, } = options;
+    const { key, displayName, description, specId, octicon, emoji, codemode, createPayload, suggestions, instructions, model, modeEffect, } = options;
     return definePlugin({
         name: `@datalayer/loop-plugin-agent-${key}`,
         displayName,
@@ -42,6 +42,7 @@ export function defineAgentCapacityPlugin(options) {
                 },
                 ...(instructions ? { instructions } : {}),
                 ...(model ? { model } : {}),
+                ...(modeEffect ? { modeEffect } : {}),
             }, { id: key }),
             ...(suggestions && suggestions.length > 0
                 ? [

package/lib/loop/plugins/chat/ChatView.js

@@ -41,7 +41,7 @@ import { AGENTS_PLUGIN_NAME } from '../agents/plugin';
 import { useConfig } from '../../../hooks/useConfig';
 import { useSkills, useSkillActions } from '../../../hooks/useSkills';
 import { AI_MODEL_CATALOGUE, isChatModel } from '../../../specs/models';
-import { LoopAgentBlueprint, LoopAgentGate, LoopChatComposer, LoopChatExtras, LoopChatHeader, LoopChatLayout, LoopChatSuggestion, LoopChatSurface, LoopChatTurn, LoopFrontendTool, LoopSlots, canOpenView, onPromptFocusRequest, onSurfaceRequest, useLoopPromptStore, } from '../../core';
+import { LoopAgentBlueprint, LoopAgentGate, LoopChatComposer, LoopChatExtras, LoopChatHeader, LoopChatLayout, LoopChatSuggestion, LoopChatSurface, LoopChatTurn, LoopCommand, LoopFrontendTool, LoopRunProps, LoopSlots, canOpenView, runForwardedProps, onPromptFocusRequest, onSurfaceRequest, useLoopPromptStore, } from '../../core';
 import { messageText, turnWritersOf } from './turnState';
 import { isInactiveSurfaceContribution, orderToolContributions, toolsForChatView, } from './chatViewTools';
 import { useAgentCommandTools } from '../../../tools/adapters/commands';
@@ -353,6 +353,10 @@ export default function ChatView({ workspace }) {
     const heldForAdapter = useRef([]);
     /** Whether the agent is turned in this page: read by `sendNow`, set below. */
     const inPageRef = useRef(false);
+    /** What goes with every run (an application's modes, LOOP P-19), read when it is sent. */
+    const runProps = useContributions(LoopRunProps);
+    const runPropsRef = useRef(runProps);
+    runPropsRef.current = runProps;
     /*
      * Every message that goes to the agent goes through here: the composer's
      * (through the workspace's dispatch and the prompt channel), a host's, and
@@ -362,13 +366,17 @@ export default function ChatView({ workspace }) {
      * What the page did besides the message goes with it as AG-UI's
      * `forwardedProps` (`loop`, LOOP R-04): the application's session takes a
      * file there. An agent turned in this page has no session, and no file is
-     * handed to it: said, rather than dropped.
+     * handed to it: said, rather than dropped. What the workspace's plugins
+     * send with every run (`LoopRunProps`: the modes the person is in, LOOP
+     * P-19) goes under it — and an agent turned in this page applies the modes
+     * itself (`modeEffect`, `BrowserAgentAdapter`).
      */
-    const sendNow = useCallback((message, forwardedProps) => {
-        const loop = forwardedProps?.loop;
+    const sendNow = useCallback((message, given) => {
+        const loop = given?.loop;
         if (inPageRef.current && loop?.files && loop.files.length > 0) {
             return 'A file is given to an application running on a runtime: run it on Datalayer or on your machine to give it one.';
         }
+        const forwardedProps = runForwardedProps(runPropsRef.current.map(entry => entry.value), given);
         // A new turn: whatever the panel showed is gone, this message is it.
         turnFeedRef.current?.begin(message, controlsRef.current?.thread());
         const send = controlsRef.current?.send;
@@ -936,6 +944,18 @@ export default function ChatView({ workspace }) {
      * silent no-ops. Derived here rather than in the plugin because it changes
      * with the selected member.
      */
+    /*
+     * The commands the composer lists while `/` is typed: those contributed for
+     * it, an application's (LOOP P-19). Picking one writes `/<name> `, and the
+     * workspace runs it when the message is sent.
+     */
+    const commands = useContributions(LoopCommand);
+    const composerCommands = useMemo(() => commands
+        .filter(entry => entry.value.composer)
+        .map(entry => ({
+        name: entry.value.name,
+        description: entry.value.description,
+    })), [commands]);
     const mentionable = useMemo(() => {
         if (!team || !member) {
             // No team: the spec's own subagents, which the in-page loop can reach
@@ -1175,6 +1195,10 @@ export default function ChatView({ workspace }) {
             // server's monitoring stream fills, so the side panel and the
             // composer's pulse draw an in-page delegation like any other.
             onSubagentEvent: event => agentRuntimeStore.getState().appendSubagentEvent(event),
+            // An application's modes (LOOP P-19): the options sent with a
+            // run tell it their instructions, on the model one names, as
+            // its session API does on a runtime.
+            modeEffect: blueprintTurn?.modeEffect,
         })
         : {
             type: 'ag-ui',
@@ -1402,6 +1426,7 @@ export default function ChatView({ workspace }) {
         // because focusing an input on mount scrolls the browser to it.
         autoFocus: config?.autoFocusPrompt ?? true,
         mentionableAgents: mentionable,
+        promptCommands: composerCommands,
         headerContent: inpromptMenu.length > 0 ? (_jsx(ReactorSlot, { slot: LoopSlots.inpromptMenu, props: { workspace } })) : undefined,
         footerExtras: promptActions.length > 0 ? (_jsx(ReactorSlot, { slot: LoopSlots.promptAction, props: { workspace } })) : undefined,
         /*
@@ -1531,6 +1556,8 @@ export default function ChatView({ workspace }) {
                     , { 
                         // The theme it wears, when the host names one (an application's).
                         themeVariant: config?.themeVariant, themeOverrides: config?.themeOverrides, colorMode: config?.colorMode, 
+                        // The session an embed goes on with after a reload (LOOP D-13).
+                        thread: config?.thread, 
                         // The header says why, beside the title, for the same reason the
                         // placeholder does: a dead control with no explanation is worse
                         // than an absent one.

package/lib/loop/plugins/chat/index.d.ts

@@ -1,6 +1,6 @@
 import type { PresenceState } from '../../../chat/presence/presenceStatus';
 import type { AssistantSaying } from '../../../chat/assistant/state';
-import type { ThemeOverrides } from '../../../types/chat';
+import type { ResumedThread, ThemeOverrides } from '../../../types/chat';
 /** What a host may set on the chat. */
 /** Who is answering, as the person meets them. */
 export interface ChatPresence {
@@ -62,6 +62,11 @@ export type ChatPluginConfig = {
      * application sets its own.
      */
     presence?: ChatPresence;
+    /**
+     * The conversation to go on with (LOOP D-13): an embedded application's
+     * session, reattached after its page reloaded, and what it holds.
+     */
+    thread?: ResumedThread;
     /**
      * Whether the counters — tokens, context — are shown under the prompt.
      * On unless said: a person using an application is not asking.

package/lib/loop/presets.d.ts

@@ -23,7 +23,7 @@ import { type PluginRef } from '@datalayer/reactor';
 import { type AgentsConfig, type SandboxTarget } from './plugins/agents';
 import { type ChatPluginConfig, type ChatPresence } from './plugins/chat';
 import { type PageSize } from './plugins/page-layout';
-import type { ThemeOverrides } from '../types/chat';
+import type { ResumedThread, ThemeOverrides } from '../types/chat';
 export type LoopPresetOptions = {
     /** Where the agent runtimes service is. */
     serverUrl?: string;
@@ -155,6 +155,8 @@ export type LoopPresetOptions = {
     presence?: ChatPresence;
     /** Whether the counters are shown under the prompt; on unless said. */
     showTokenUsage?: boolean;
+    /** The conversation to go on with: an embed's session after a reload (LOOP D-13). */
+    thread?: ResumedThread;
     /**
      * The agentspec the local agent is created from, by id.
      *

package/lib/loop/presets.js

@@ -52,7 +52,7 @@ import { LoopPageLayoutPlugin } from './plugins/page-layout';
  * be installed or signed into, and the switches a demonstration wants are off.
  */
 export function loopPlugins(options = {}) {
-    const { serverUrl, target = 'browser', defaultEditor: askedEditor, showViewSelector = true, hideChatHeader = false, chatHeaderButtons = false, promptPlacement, autoFocusPrompt = true, suggestionLabels = true, fullScreenTopOffset = 0, showAgentVariants = false, agentSummary = true, teamId, teamPicker = true, pageLayout = false, pageLayoutArrangement = 'page', pageLayoutTurnPanel = 'below', pageLayoutPrompt = 'docked', pageLayoutPromptAnchor = 'top', pageLayoutSize, pageLayoutTurnPanelFooter = 'full', localAgent, localAgentSpec, datalayerAgentSpecId, datalayerCreatePayload, datalayerVisitors, datalayerKept, embedToken, targetFixed, themeVariant, themeOverrides, colorMode, presence, showTokenUsage, floatingPrompt = false, editorSelector = false, editors = true, conversation = true, graph = false, commandPalette = false, pluginsPanel = false, windowFrame = false, firstPromptHook, } = options;
+    const { serverUrl, target = 'browser', defaultEditor: askedEditor, showViewSelector = true, hideChatHeader = false, chatHeaderButtons = false, promptPlacement, autoFocusPrompt = true, suggestionLabels = true, fullScreenTopOffset = 0, showAgentVariants = false, agentSummary = true, teamId, teamPicker = true, pageLayout = false, pageLayoutArrangement = 'page', pageLayoutTurnPanel = 'below', pageLayoutPrompt = 'docked', pageLayoutPromptAnchor = 'top', pageLayoutSize, pageLayoutTurnPanelFooter = 'full', localAgent, localAgentSpec, datalayerAgentSpecId, datalayerCreatePayload, datalayerVisitors, datalayerKept, embedToken, targetFixed, themeVariant, themeOverrides, colorMode, presence, showTokenUsage, thread, floatingPrompt = false, editorSelector = false, editors = true, conversation = true, graph = false, commandPalette = false, pluginsPanel = false, windowFrame = false, firstPromptHook, } = options;
     const defaultEditor = askedEditor ?? (editors ? 'notebook' : 'none');
     // A workspace without a conversation: the theme, the shell's points, and
     // the host's chrome; its view is a host's plugin's.
@@ -89,6 +89,7 @@ export function loopPlugins(options = {}) {
             colorMode,
             presence,
             showTokenUsage,
+            ...(thread ? { thread } : {}),
         }),
         // The composer and the title bar are plugins of their own: the chat
         // assembles their props, these render them. In the preset by default —

package/lib/loop/shell/LoopWorkspace.js

@@ -91,8 +91,11 @@ function WorkspaceBody({ serverUrl, agentId: initialAgentId, conversationId, mod
             workspace: currentWorkspace.current,
             argv: command.argv,
         });
+        // What a command sends goes to the agent as if typed: an
+        // application's command sends its prompt (LOOP P-19).
         if (result?.prompt) {
             onSend?.(result.prompt, currentWorkspace.current);
+            prompts.submit(result.prompt);
         }
         return {
             handled: true,

package/lib/protocols/BrowserAgentAdapter.d.ts

@@ -26,6 +26,7 @@ import { type LanguageModel } from 'ai';
 import type { ProtocolAdapterConfig } from '../types/protocol';
 import type { ChatMessage } from '../types/messages';
 import type { FrontendToolDefinition } from '../types/tools';
+import type { AppModeEffect } from '../types/agentspecs';
 import type { AgentStreamSubagentPayload } from '../types/stream';
 import { BaseProtocolAdapter } from './BaseProtocolAdapter';
 import type { TeamContextSharing } from '../types/teams';
@@ -63,6 +64,13 @@ export interface BrowserAgentAdapterConfig extends ProtocolAdapterConfig, Fronte
     sharing?: TeamContextSharing;
     /** Told what a delegated run does, as it does it — see `subagentTools`. */
     onSubagentEvent?: (event: AgentStreamSubagentPayload) => void;
+    /**
+     * What the modes a run is sent in (`forwardedProps.loop.modes`, LOOP P-19)
+     * tell it, and the model it runs on: an application's, by agentspecs'
+     * rules. Unsaid for an agent with no modes, which refuses a run sent in
+     * some.
+     */
+    modeEffect?: (chosen: Record<string, string>) => AppModeEffect;
 }
 /**
  * An agent loop running in the page, speaking the protocol adapter interface.
@@ -111,6 +119,15 @@ export declare class BrowserAgentAdapter extends BaseProtocolAdapter {
      * `languageModel` is the host's own choice and is not swapped out.
      */
     private resolveModel;
+    /**
+     * What the modes a run is sent in tell it, and the model it runs on (LOOP
+     * P-19) — the runtime's session API applies the same, for that run only.
+     *
+     * Refused, in a sentence, rather than run without them: modes sent to an
+     * agent that has none, modes that are not the application's, and a mode
+     * naming a model for an agent whose model is the host's own.
+     */
+    private runModes;
     /**
      * Run one turn of the loop and report it as it happens.
      *
@@ -121,5 +138,6 @@ export declare class BrowserAgentAdapter extends BaseProtocolAdapter {
     sendMessage(message: ChatMessage, options?: {
         messages?: ChatMessage[];
         model?: string;
+        forwardedProps?: Record<string, unknown>;
     }): Promise<void>;
 }

package/lib/protocols/BrowserAgentAdapter.js

@@ -140,6 +140,30 @@ export class BrowserAgentAdapter extends BaseProtocolAdapter {
         }
         return createBrowserModel({ ...inference, model: requested || model });
     }
+    /**
+     * What the modes a run is sent in tell it, and the model it runs on (LOOP
+     * P-19) — the runtime's session API applies the same, for that run only.
+     *
+     * Refused, in a sentence, rather than run without them: modes sent to an
+     * agent that has none, modes that are not the application's, and a mode
+     * naming a model for an agent whose model is the host's own.
+     */
+    runModes(forwardedProps) {
+        const loop = forwardedProps?.loop;
+        const chosen = loop?.modes;
+        if (!chosen || Object.keys(chosen).length === 0) {
+            return undefined;
+        }
+        const { modeEffect, languageModel } = this.browserConfig;
+        if (!modeEffect) {
+            throw new Error('This agent has no modes: the options chosen in the composer cannot be applied to it.');
+        }
+        const effect = modeEffect(chosen);
+        if (effect.model && languageModel) {
+            throw new Error(`The mode chosen runs on ${effect.model}, and this agent's model is its host's own: it cannot run on another.`);
+        }
+        return effect;
+    }
     /**
      * Run one turn of the loop and report it as it happens.
      *
@@ -194,9 +218,18 @@ export class BrowserAgentAdapter extends BaseProtocolAdapter {
             this.emit({ type: 'message', message: assistant, timestamp: new Date() });
         };
         try {
+            // The modes the person is in, for this run only: their instructions
+            // after the agent's, and the model one names over the chat's.
+            const modes = this.runModes(options?.forwardedProps);
+            const { instructions } = this.browserConfig;
+            const system = modes?.instructions
+                ? [instructions?.trim(), modes.instructions]
+                    .filter(Boolean)
+                    .join('\n\n')
+                : instructions;
             const result = streamText({
-                model: this.resolveModel(options?.model),
-                system: this.browserConfig.instructions,
+                model: this.resolveModel(modes?.model || options?.model),
+                system,
                 messages: history,
                 tools: this.tools,
                 stopWhen: stepCountIs(this.browserConfig.maxSteps ?? DEFAULT_BROWSER_MAX_STEPS),

package/lib/runtimes/__tests__/fixtures/accounting-agent-card.json

@@ -38,6 +38,14 @@
           "pause": "/api/v1/a2a/pause",
           "steer": "/api/v1/a2a/steer"
         }
+      },
+      {
+        "uri": "https://datalayer.ai/extensions/face/v1",
+        "description": "Its face: an emoji, and an avatar when it has one.",
+        "required": false,
+        "params": {
+          "emoji": "🧾"
+        }
       }
     ]
   },

package/lib/runtimes/browser/a2aPeer.d.ts

@@ -37,7 +37,18 @@ export type A2APeer = {
     client: Client;
     card: AgentCard;
     skill: AgentSkill;
+    /** Its face, when its card carries one (`A2A_FACE_EXTENSION_URI`). */
+    face?: A2APeerFace;
 };
+/** The extension an agent card carries its face in: its name stays plain. */
+export declare const A2A_FACE_EXTENSION_URI = "https://datalayer.ai/extensions/face/v1";
+/** A peer's face: its emoji and, when it has one, its avatar's name. */
+export type A2APeerFace = {
+    emoji: string;
+    avatar?: string;
+};
+/** The face an agent card carries, if it carries one. */
+export declare function faceOfCard(card: AgentCard): A2APeerFace | undefined;
 export type ConnectA2APeerOptions = {
     /** Where the peer is served: `…/api/v1/a2a/agents/<application id>`. */
     url: string;