@datalayer/agent-runtimes 1.3.29 → 1.3.30

package/lib/AgentNode.js

@@ -345,7 +345,8 @@ export function AgentNode() {
     ]);
     const [inferenceProvider, setInferenceProvider] = useState('datalayer');
     const [inferenceModels, setInferenceModels] = useState([]);
-    const [inferenceDefaultModel, setInferenceDefaultModel] = useState(null);
+    // The runtime's sentence about its models, or why it gave none.
+    const [inferenceModelsNote, setInferenceModelsNote] = useState(null);
     const [configurationLoaded, setConfigurationLoaded] = useState(false);
     const [isActiveAgentRunning, setIsActiveAgentRunning] = useState(false);
     // The protocol the active agent actually speaks, as reported by the node.
@@ -712,49 +713,26 @@ export function AgentNode() {
     useEffect(() => {
         if (inferenceProvider !== 'datalayer') {
             setInferenceModels([]);
-            setInferenceDefaultModel(null);
+            setInferenceModelsNote(null);
             return;
         }
+        // The runtime's answer, as it had it from ai-inference: no list of its
+        // own when that answer is empty or did not come — the sentence says why.
         const loadInferenceModels = async () => {
             try {
                 const response = await fetch(`${AGENT_RUNTIMES_BASE_URL}/api/v1/configure/inference/models`);
                 if (!response.ok) {
                     setInferenceModels([]);
-                    setInferenceDefaultModel(null);
+                    setInferenceModelsNote(`The runtime did not list its models (${response.status}).`);
                     return;
                 }
                 const payload = await response.json();
-                const fromModels = Array.isArray(payload.models)
-                    ? payload.models.filter(Boolean)
-                    : [];
-                const fromBedrock = Array.isArray(payload.bedrock_anthropic_models)
-                    ? payload.bedrock_anthropic_models.filter(Boolean)
-                    : [];
-                const fallback = [
-                    'bedrock/us.anthropic.claude-3-5-sonnet-20240620-v1:0',
-                    'bedrock/us.anthropic.claude-3-7-sonnet-20250219-v1:0',
-                    'bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0',
-                ];
-                const models = fromModels.length > 0
-                    ? fromModels
-                    : fromBedrock.length > 0
-                        ? fromBedrock
-                        : fallback;
-                setInferenceModels(models);
-                const specDefault = Array.isArray(payload.bedrock_anthropic_model_specs)
-                    ? payload.bedrock_anthropic_model_specs.find(s => s?.default)?.id
-                    : undefined;
-                const selected = (specDefault && models.includes(specDefault) ? specDefault : null) ||
-                    (payload.default_model && models.includes(payload.default_model)
-                        ? payload.default_model
-                        : null) ||
-                    models[0] ||
-                    null;
-                setInferenceDefaultModel(selected);
+                setInferenceModels(Array.isArray(payload.models) ? payload.models.filter(Boolean) : []);
+                setInferenceModelsNote(payload.note ?? null);
             }
-            catch {
+            catch (error) {
                 setInferenceModels([]);
-                setInferenceDefaultModel(null);
+                setInferenceModelsNote(`The runtime did not list its models (${String(error)}).`);
             }
         };
         loadInferenceModels();
@@ -1280,7 +1258,10 @@ export function AgentNode() {
                                                                     display: 'flex',
                                                                     flexDirection: 'column',
                                                                     gap: 1,
-                                                                }, children: [_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Bedrock Anthropic model" }), inferenceModels.length === 0 ? (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "No model list available." })) : (_jsxs(ActionMenu, { children: [_jsx(ActionMenu.Button, { children: inferenceDefaultModel || inferenceModels[0] }), _jsx(ActionMenu.Overlay, { width: "large", children: _jsx(ActionList, { selectionVariant: "single", children: inferenceModels.map(model => (_jsx(ActionList.Item, { selected: inferenceDefaultModel === model, inactiveText: "Selection is locked", children: model }, model))) }) })] }))] }))] }), iamUser ? (_jsxs(Box, { sx: {
+                                                                }, children: [_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Models ai-inference serves" }), inferenceModels.length === 0 ? (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: inferenceModelsNote ??
+                                                                            'The runtime has not said which models ai-inference serves.' })) : (_jsxs(ActionMenu, { children: [_jsx(ActionMenu.Button, { children: inferenceModels.length === 1
+                                                                                    ? inferenceModels[0]
+                                                                                    : `${inferenceModels.length} models` }), _jsx(ActionMenu.Overlay, { width: "large", children: _jsx(ActionList, { children: inferenceModels.map(model => (_jsx(ActionList.Item, { inactiveText: "Selection is locked", children: model }, model))) }) })] }))] }))] }), iamUser ? (_jsxs(Box, { sx: {
                                                             border: '1px solid',
                                                             borderColor: 'border.default',
                                                             borderRadius: 2,

package/lib/chat/base/ChatBase.js

@@ -48,7 +48,7 @@ import { InputPrompt } from '../prompt/InputPrompt';
 import { isFloatingChatViewMode } from '../viewModes';
 import { ToolApprovalBanner, ToolApprovalDialog, } from '../tools';
 import { EphemeralNotebook } from '../notebook/EphemeralNotebook';
-import { initialModelId, isOffered, usableModels } from './modelChoice';
+import { initialModelId, isOffered, offeredModels as offeredModelsFor, } from './modelChoice';
 // EphemeralDocument statically imports `@datalayer/jupyter-lexical` (which
 // initialises Lumino-backed nodes on load). Lazy-load it so notebook-only chats
 // never pull lexical into the bundle or trigger its module side effects.
@@ -1380,37 +1380,46 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         : undefined;
     const offeredModels = useMemo(() => {
         // Only what can actually be called — see `modelChoice` for the rule.
-        const fromConfig = availableModels || configQuery.data?.models;
-        if (fromConfig?.length) {
-            return usableModels(fromConfig);
-        }
-        /*
-         * The catalogue, filtered to what is worth offering.
-         *
-         * A server tells the chat which models it can reach and that answer wins.
-         * Without one — an in-page agent, or a server that has not answered yet —
-         * this used to offer the single model the protocol was built with, which
-         * is a menu with nothing to choose.
-         *
-         * `available` is the filter, not the whole catalogue: twenty-six models,
-         * most of them superseded, is a list nobody reads. The specs say which
-         * four are current.
-         */
-        const catalogued = Object.values(AI_MODEL_CATALOGUE)
-            // A typed-judgment model answers typed questions, not a chat.
-            .filter(model => model.available && isChatModel(model))
-            .map(model => ({
-            id: model.id,
-            name: model.name,
-            provider: model.provider,
-        }));
-        if (catalogued.length > 0) {
-            return usableModels(catalogued);
-        }
-        return browserModel
-            ? [{ id: browserModel, name: browserModel, provider: 'inference' }]
-            : [];
-    }, [availableModels, configQuery.data?.models, browserModel]);
+        // The runtime's answer, when it gave one, is the whole list.
+        // A runtime that was asked and did not answer offers nothing: the
+        // agentspecs catalogue below is not its answer.
+        const fromConfig = availableModels ||
+            configQuery.data?.models ||
+            (configQuery.isError ? [] : undefined);
+        return offeredModelsFor(fromConfig, () => {
+            /*
+             * The catalogue, filtered to what is worth offering.
+             *
+             * A server tells the chat which models it can reach and that answer wins.
+             * Without one — an in-page agent, or a server that has not answered yet —
+             * this used to offer the single model the protocol was built with, which
+             * is a menu with nothing to choose.
+             *
+             * `available` is the filter, not the whole catalogue: twenty-six models,
+             * most of them superseded, is a list nobody reads. The specs say which
+             * four are current.
+             */
+            const catalogued = Object.values(AI_MODEL_CATALOGUE)
+                // A typed-judgment model answers typed questions, not a chat.
+                .filter(model => model.available && isChatModel(model))
+                .map(model => ({
+                id: model.id,
+                name: model.name,
+                provider: model.provider,
+            }));
+            if (catalogued.length > 0) {
+                return catalogued;
+            }
+            return browserModel
+                ? [{ id: browserModel, name: browserModel, provider: 'inference' }]
+                : [];
+        });
+    }, [
+        availableModels,
+        configQuery.data?.models,
+        configQuery.isError,
+        browserModel,
+    ]);
     /*
      * Who `@` may address.
      *

package/lib/chat/base/modelChoice.d.ts

@@ -26,6 +26,17 @@ export declare const isUsable: (model: ModelConfig) => boolean;
  * while the rows and their reasons say which key is missing.
  */
 export declare function usableModels(models: ModelConfig[]): ModelConfig[];
+/**
+ * The models a chat offers, given what its runtime answered.
+ *
+ * The runtime's answer is the list: an agent's own models (its `model` and
+ * `model_additionals`), each flagged with whether its inference serves it.
+ * When the runtime answered, nothing else is added — not even when its list
+ * is empty, which says the agent has nothing to switch to. `fallback` is
+ * asked only when there is no runtime to answer (an in-page agent) or it
+ * has not answered yet.
+ */
+export declare function offeredModels(fromRuntime: ModelConfig[] | undefined, fallback: () => ModelConfig[]): ModelConfig[];
 /** Whether `id` is on offer and usable — the selection may stand. */
 export declare const isOffered: (offered: ModelConfig[], id?: string) => boolean;
 /**
@@ -59,4 +70,6 @@ export type ServerCatalogueModel = {
  */
 export declare function readServerCatalogue(payload: {
     models?: ServerCatalogueModel[];
+    source?: string;
+    note?: string;
 } | null | undefined): ModelConfig[];

package/lib/chat/base/modelChoice.js

@@ -14,6 +14,19 @@ export function usableModels(models) {
     const usable = models.filter(isUsable);
     return usable.length > 0 ? usable : models;
 }
+/**
+ * The models a chat offers, given what its runtime answered.
+ *
+ * The runtime's answer is the list: an agent's own models (its `model` and
+ * `model_additionals`), each flagged with whether its inference serves it.
+ * When the runtime answered, nothing else is added — not even when its list
+ * is empty, which says the agent has nothing to switch to. `fallback` is
+ * asked only when there is no runtime to answer (an in-page agent) or it
+ * has not answered yet.
+ */
+export function offeredModels(fromRuntime, fallback) {
+    return usableModels(fromRuntime ?? fallback());
+}
 /** Whether `id` is on offer and usable — the selection may stand. */
 export const isOffered = (offered, id) => Boolean(id) && offered.some(m => m.id === id && isUsable(m));
 /**

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

@@ -1,6 +1,7 @@
 import type { ReactorPlugin } from '@datalayer/reactor';
 import type { AppSpec } from '../../types/agentspecs';
 import { type LoopEmbedProps } from '../embed/LoopEmbed';
+import type { LoopPresetOptions } from '../presets';
 import type { PresenceState } from '../../chat/presence/presenceStatus';
 /** The id of an agent or a Cog, without its version. */
 export declare const agentIdOf: (app: Pick<AppSpec, "agent" | "team">) => string;
@@ -37,7 +38,38 @@ export type AppRendererProps = Omit<LoopEmbedProps, 'agentId'> & {
      * stable function, such as a state setter.
      */
     onPresence?: (state: PresenceState) => void;
+    /**
+     * Draw the application in a window (the `window-frame` plugin), its title
+     * the application's face and name. A host's own `frameTitle` wins.
+     */
+    frame?: boolean;
 };
+/** What `interface.layout` sets on the workspace. */
+export type AppLayoutOptions = Pick<LoopPresetOptions, 'editors' | 'showViewSelector' | 'defaultEditor' | 'pageLayout' | 'pageLayoutArrangement' | 'pageLayoutPrompt' | 'pageLayoutPromptAnchor' | 'pageLayoutTurnPanelFooter'>;
+/**
+ * The workspace an application's layout asks for (LOOP T-07).
+ *
+ * - `chat`: the conversation alone — no editor, no page, no strip.
+ * - `page`: the page layout — its page (or, without one, the editors) on the
+ *   sheet; the composer a card over it, starting at the bottom, whose display
+ *   modes put it in the conversation panel beside, over or in the corner of
+ *   the page; the current turn under the composer, its copy and dismiss only.
+ * - `split`: the page layout's split — the conversation on the left with its
+ *   composer, the page on the right, a hairline between them to drag.
+ *
+ * With a page, the page is the one editor, opened, without a strip to swap
+ * it; without one (a decision, whose page is the Studio's), the editors stay.
+ */
+export declare function appLayoutOptions(app: Pick<AppSpec, 'kind' | 'interface' | 'agent'>): AppLayoutOptions;
+/**
+ * What an application's agent is created with on a Datalayer runtime: under
+ * the application's id, over AG-UI, with the application's own document —
+ * so that the runtime registers it and decides every tool call by its rules
+ * (LOOP R-03, R-05), as `loop apps run --cloud` does. One payload for every
+ * place it runs: the workspace (`AppRenderer`) and the embed's floating
+ * modes (`AppEmbed`).
+ */
+export declare function appDatalayerCreatePayload(app: AppSpec, instance?: AppInstance): Record<string, unknown>;
 /**
  * An application in a LOOP workspace: its agent, its starters, its layout.
  *
@@ -47,5 +79,5 @@ export type AppRendererProps = Omit<LoopEmbedProps, 'agentId'> & {
 /** No host plugins: one array, so that it never reads as a change. */
 /** The agentspec a runtime is allocated with before an application's agent is created on it. */
 export declare const DATALAYER_BOOTSTRAP_AGENTSPEC = "example-simple";
-export declare function AppRenderer({ app, plugins, instance, onPresence, ...embed }: AppRendererProps): React.JSX.Element;
+export declare function AppRenderer({ app, plugins, instance, onPresence, frame, ...embed }: AppRendererProps): React.JSX.Element;
 export default AppRenderer;

package/lib/loop/apps/AppRenderer.js

@@ -16,13 +16,26 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
  *   created with the application in its payload — so the runtime reaches only
  *   what the application connects to and enforces its rules before every tool
  *   call — and the application's starters as the openers of the empty chat;
- * - the **layout of its kind**: a chat is the conversation alone, with the
- *   A2UI surfaces its answers draw; the other layouts keep the editors.
+ * - its **layout**, as `interface.layout` says (`appLayoutOptions`, LOOP
+ *   T-07), on the workspace's own `page-layout` plugin: `chat` is the
+ *   conversation alone, with the A2UI surfaces its answers draw; `page` is
+ *   the page on a sheet with the composer over it and the conversation in a
+ *   panel the composer's display modes open; `split` is the conversation and
+ *   the page side by side, a hairline between them to drag;
+ * - its **page**, when it has one (`hasAppPage`: a chat, a widget or a worker
+ *   with a `page` or `split` layout): its A2UI surface drawn by the
+ *   `app-page` plugin, in place of the notebook and the document, fed from
+ *   the conversation and answered through it (`APP_KIND_PATHS`). A
+ *   decision's page stays the Studio's run page (R-02); its layout keeps the
+ *   editors;
+ * - its **frame**, when the host asks (`frame`): the `window-frame` plugin's
+ *   window, its title the application's face and name.
  *
  * @module loop/apps/AppRenderer
  */
 import { useMemo } from 'react';
 import { defineAgentCapacityPlugin } from '../plugins/agent-capacity';
+import { APP_PAGE_SURFACE, defineAppPagePlugin, hasAppPage, } from '../plugins/app-page';
 import { LoopEmbed } from '../embed/LoopEmbed';
 import { dumpAppspec } from './appspec';
 /** The id of an agent or a Cog, without its version. */
@@ -64,8 +77,75 @@ export function defineAppPlugin(app) {
             text: starter.label,
             message: starter.message,
         })),
+        // In the page, the agent is told what a runtime tells it: its own
+        // spec's prompt, then the application's instructions; on the
+        // application's model when it names one (`loop/apps/agent`).
+        instructions: app.instructions,
+        model: app.model,
     });
 }
+/**
+ * The workspace an application's layout asks for (LOOP T-07).
+ *
+ * - `chat`: the conversation alone — no editor, no page, no strip.
+ * - `page`: the page layout — its page (or, without one, the editors) on the
+ *   sheet; the composer a card over it, starting at the bottom, whose display
+ *   modes put it in the conversation panel beside, over or in the corner of
+ *   the page; the current turn under the composer, its copy and dismiss only.
+ * - `split`: the page layout's split — the conversation on the left with its
+ *   composer, the page on the right, a hairline between them to drag.
+ *
+ * With a page, the page is the one editor, opened, without a strip to swap
+ * it; without one (a decision, whose page is the Studio's), the editors stay.
+ */
+export function appLayoutOptions(app) {
+    const layout = app.interface.layout;
+    if (layout === 'chat') {
+        return { editors: false, showViewSelector: false };
+    }
+    const withPage = hasAppPage(app);
+    return {
+        editors: !withPage,
+        showViewSelector: !withPage,
+        ...(withPage ? { defaultEditor: APP_PAGE_SURFACE } : {}),
+        pageLayout: true,
+        pageLayoutArrangement: layout === 'split' ? 'split' : 'page',
+        pageLayoutPrompt: 'floating',
+        pageLayoutPromptAnchor: 'bottom',
+        pageLayoutTurnPanelFooter: 'actions',
+    };
+}
+/**
+ * What an application's agent is created with on a Datalayer runtime: under
+ * the application's id, over AG-UI, with the application's own document —
+ * so that the runtime registers it and decides every tool call by its rules
+ * (LOOP R-03, R-05), as `loop apps run --cloud` does. One payload for every
+ * place it runs: the workspace (`AppRenderer`) and the embed's floating
+ * modes (`AppEmbed`).
+ */
+export function appDatalayerCreatePayload(app, instance) {
+    return {
+        // Under the application's id, over AG-UI: what the workspace's
+        // chat addresses (`AppRenderer` gives it as `agentId`).
+        name: app.id,
+        transport: 'ag-ui',
+        agent_spec_id: agentIdOf(app),
+        app_spec: dumpAppspec(app),
+        // Code Mode calls every tool through `execute_code`, which an
+        // application without a shell is refused: its tools are called
+        // one by one instead, each decided by its rules.
+        enable_codemode: Boolean(app.permissions?.computer?.shell),
+        ...(instance
+            ? {
+                app_instance: {
+                    app_uid: instance.appUid ?? '',
+                    deployment_uid: instance.deploymentUid ?? '',
+                    version: instance.version ?? 0,
+                },
+            }
+            : {}),
+    };
+}
 /**
  * An application in a LOOP workspace: its agent, its starters, its layout.
  *
@@ -76,8 +156,7 @@ export function defineAppPlugin(app) {
 /** The agentspec a runtime is allocated with before an application's agent is created on it. */
 export const DATALAYER_BOOTSTRAP_AGENTSPEC = 'example-simple';
 const NO_PLUGINS = [];
-export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, ...embed }) {
-    const chatOnly = app.interface.layout === 'chat';
+export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, frame = false, ...embed }) {
     /*
      * The application plugin, made once per application. `LoopEmbed` rebuilds
      * its whole reactor when its plugins change, so a new plugin on every
@@ -88,36 +167,20 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, .
     const appPlugin = useMemo(() => (app.agent ? defineAppPlugin(app) : null), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [source]);
-    const allPlugins = useMemo(() => (appPlugin ? [appPlugin, ...plugins] : plugins), [appPlugin, plugins]);
+    const withPage = hasAppPage(app);
+    const pagePlugin = useMemo(() => (withPage ? defineAppPagePlugin(app) : null), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [source, withPage]);
+    const allPlugins = useMemo(() => appPlugin
+        ? [appPlugin, ...(pagePlugin ? [pagePlugin] : []), ...plugins]
+        : plugins, [appPlugin, pagePlugin, plugins]);
     /*
      * On Datalayer, the application runs on a runtime: allocated with a plain
      * agentspec, its agent created there with the application's spec — so that
      * the runtime registers it and decides every tool call by its rules (LOOP
      * R-03, R-05), as `loop apps run --cloud` does.
      */
-    const datalayerCreatePayload = useMemo(() => app.agent
-        ? {
-            // Under the application's id, over AG-UI: what the workspace's
-            // chat addresses (`agentId` below).
-            name: app.id,
-            transport: 'ag-ui',
-            agent_spec_id: agentIdOf(app),
-            app_spec: dumpAppspec(app),
-            // Code Mode calls every tool through `execute_code`, which an
-            // application without a shell is refused: its tools are called
-            // one by one instead, each decided by its rules.
-            enable_codemode: Boolean(app.permissions?.computer?.shell),
-            ...(instance
-                ? {
-                    app_instance: {
-                        app_uid: instance.appUid ?? '',
-                        deployment_uid: instance.deploymentUid ?? '',
-                        version: instance.version ?? 0,
-                    },
-                }
-                : {}),
-        }
-        : undefined, 
+    const datalayerCreatePayload = useMemo(() => (app.agent ? appDatalayerCreatePayload(app, instance) : undefined), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [source, instance?.appUid, instance?.deploymentUid, instance?.version]);
     if (!appPlugin) {
@@ -129,7 +192,11 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, .
     , { 
         // The application's own agent: created under its id, so that its
         // spec is applied to an agent of its own, never to the one it extends.
-        agentId: app.id, editors: !chatOnly, showViewSelector: !chatOnly, teamPicker: false, showAgentVariants: false, graph: false, pluginsPanel: false, datalayerAgentSpecId: DATALAYER_BOOTSTRAP_AGENTSPEC, 
+        agentId: app.id, ...appLayoutOptions(app), ...(frame
+            ? {
+                frameTitle: [app.emoji, app.name].filter(Boolean).join(' '),
+            }
+            : {}), teamPicker: false, showAgentVariants: false, graph: false, pluginsPanel: false, datalayerAgentSpecId: DATALAYER_BOOTSTRAP_AGENTSPEC, 
         // Where an application runs is decided by its host — the Studio's
         // Preview, the hosted page — not offered to its user.
         targetFixed: true, 

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

@@ -0,0 +1,15 @@
+import type { Agentspec } from '../../types/agentspecs';
+/** An agent of the catalogue, or a Cog's agent, by `id` or `id:version`. */
+export declare function resolveAgentspec(reference: string): Agentspec | undefined;
+/**
+ * What the agent is told: its spec's system prompt, then what the
+ * application tells it on top — as the runtime joins them.
+ */
+export declare function agentInstructions(spec: Pick<Agentspec, 'systemPrompt'> | undefined, extra?: string): string | undefined;
+/**
+ * Why an agent turned in the page cannot run, or undefined when it can.
+ *
+ * An agent named by a reference that resolves to nothing would answer with
+ * no instructions — bare — which is not the agent that was asked for.
+ */
+export declare function inPageAgentRefusal(reference: string | undefined, spec: Agentspec | undefined): string | undefined;

package/lib/loop/apps/agent.js

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The agent an application runs, as the page turns it (LOOP H-01, E-11).
+ *
+ * On a runtime, an application's agent is its agent's spec — an agent of the
+ * catalogue, or a Cog's, which is an agent equipped with Frames, their
+ * context already in its system prompt — and the application's own
+ * instructions on top of it (`get_library_agent_spec` and the create route
+ * in `agent_runtimes/routes/agents.py`). The page turns the same agent in the
+ * browser, so it resolves it the same way: an application on a Cog that the
+ * page looked up among the agentspecs alone ran with no instructions at all.
+ *
+ * @module loop/apps/agent
+ */
+import { getAgentspecs } from '../../specs/agents';
+import { getCog } from '../../specs/cogs';
+/** An agent of the catalogue, or a Cog's agent, by `id` or `id:version`. */
+export function resolveAgentspec(reference) {
+    return getAgentspecs(reference) ?? getCog(reference)?.spec;
+}
+/**
+ * What the agent is told: its spec's system prompt, then what the
+ * application tells it on top — as the runtime joins them.
+ */
+export function agentInstructions(spec, extra) {
+    const parts = [spec?.systemPrompt?.trim(), extra?.trim()].filter((part) => Boolean(part));
+    return parts.length > 0 ? parts.join('\n\n') : undefined;
+}
+/**
+ * Why an agent turned in the page cannot run, or undefined when it can.
+ *
+ * An agent named by a reference that resolves to nothing would answer with
+ * no instructions — bare — which is not the agent that was asked for.
+ */
+export function inPageAgentRefusal(reference, spec) {
+    return reference && !spec
+        ? `There is no agent or Cog named “${reference}” in this page, so it cannot answer here.`
+        : undefined;
+}

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

@@ -3,6 +3,7 @@
  *
  * @module loop/apps
  */
+export * from './agent';
 export * from './AppRenderer';
 export * from './appspec';
 export * from './checks';

package/lib/loop/apps/index.js

@@ -7,6 +7,7 @@
  *
  * @module loop/apps
  */
+export * from './agent';
 export * from './AppRenderer';
 export * from './appspec';
 export * from './checks';

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

@@ -483,6 +483,14 @@ export type AgentBlueprintContribution = {
     specId?: string;
     /** Extra fields merged into the server's create-agent payload. */
     createPayload?: Record<string, unknown>;
+    /**
+     * What the agent is told on top of its spec's system prompt — an
+     * application's instructions — when the page turns it, as a runtime
+     * appends them.
+     */
+    instructions?: string;
+    /** The model it runs on in the page, in place of its spec's. */
+    model?: string;
 };
 export declare const LoopAgentBlueprint: import("@datalayer/reactor").ContributionPoint<AgentBlueprintContribution>;
 /** One conversation opener a plugin offers on the empty chat. */

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

@@ -0,0 +1,42 @@
+import type { CSSProperties, JSX, ReactNode } from 'react';
+import type { AppAccent, AppEmbedMode, AppSpec } from '../../types/agentspecs';
+import { type AppInstance } from '../apps/AppRenderer';
+import { type EmbedColorMode } from './embedConfig';
+export type AppEmbedProps = {
+    /** The application. */
+    app: AppSpec;
+    /** How it sits in the page; the Appspec's `deployment.embedded.mode` by default. */
+    mode?: AppEmbedMode;
+    /** The host's accent; the application's own by default. */
+    accent?: AppAccent;
+    /** Light, dark, or the visitor's system. */
+    colorMode?: EmbedColorMode;
+    /** The host's face, a CSS font family; the theme's by default. */
+    font?: string;
+    /**
+     * An agent-runtimes server the application's agent runs on. Without one,
+     * it runs on a Datalayer runtime, launched with the visitor's Datalayer
+     * credentials.
+     */
+    serverUrl?: string;
+    /** What its record is kept under, on Datalayer. */
+    instance?: AppInstance;
+    /** Height of an inline application. */
+    height?: number | string;
+    /**
+     * Draw overlays — menus, dialogs — inside the embed's own root rather than
+     * in Primer's, in the host's `<body>`: what the element asks for, since a
+     * shadow root's styles stop at its edge. A React host leaves it off.
+     */
+    ownPortal?: boolean;
+};
+/** The `loop` theme, with the application's (or the host's) accent and face. */
+export declare function EmbedThemed({ accent, colorMode, font, children, style, }: {
+    accent: AppAccent;
+    colorMode: 'light' | 'dark';
+    font?: string;
+    children: ReactNode;
+    style?: CSSProperties;
+}): JSX.Element;
+export declare function AppEmbed({ app, mode, accent, colorMode, font, serverUrl, instance, height, ownPortal, }: AppEmbedProps): JSX.Element;
+export default AppEmbed;