@datalayer/agent-runtimes 1.3.29 → 1.3.32

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

@@ -0,0 +1,24 @@
+import { type ThemeStyles } from '@datalayer/primer-addons';
+import type { AppAccent } from '../../types/agentspecs';
+/**
+ * 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.
+ */
+export declare function embedThemeStyles({ accent, font, }: {
+    accent: AppAccent;
+    font?: string;
+}): ThemeStyles;
+/**
+ * The element's own stylesheet, written into its shadow root.
+ *
+ * `all: initial` on the host: nothing the host page sets — a font, a colour,
+ * a line height, a text alignment — is inherited by the application. The
+ * theme's custom properties are set again inside, on the provider's element,
+ * so a host's variable of the same name never reaches what the application
+ * draws. A floating mode takes no room in the page: what it draws is fixed to
+ * the viewport.
+ *
+ * With the theme's own stylesheet, scoped to the provider's element in this
+ * root.
+ */
+export declare function embedShadowCss(themeCss?: string): string;

package/lib/loop/embed/embedTheme.js

@@ -0,0 +1,83 @@
+/*
+ * 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';
+/** One mode's properties, with the theme's face replaced by the host's. */
+function withFace(styles, font) {
+    if (!font) {
+        return styles;
+    }
+    return Object.fromEntries(Object.entries(styles).map(([name, value]) => [
+        name,
+        typeof value === 'string'
+            ? value.split(loopFontFamily).join(font)
+            : value,
+    ]));
+}
+/**
+ * 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.
+ */
+export function embedThemeStyles({ accent, font = '', }) {
+    const mode = (which) => withFace({
+        ...loopThemeStyles[which],
+        ...loopAccentStyles(accent, which),
+    }, font);
+    return {
+        ...loopThemeStyles,
+        light: mode('light'),
+        dark: mode('dark'),
+    };
+}
+/**
+ * The element's own stylesheet, written into its shadow root.
+ *
+ * `all: initial` on the host: nothing the host page sets — a font, a colour,
+ * a line height, a text alignment — is inherited by the application. The
+ * theme's custom properties are set again inside, on the provider's element,
+ * so a host's variable of the same name never reaches what the application
+ * draws. A floating mode takes no room in the page: what it draws is fixed to
+ * the viewport.
+ *
+ * With the theme's own stylesheet, scoped to the provider's element in this
+ * root.
+ */
+export function embedShadowCss(themeCss) {
+    const own = `
+:host {
+  all: initial;
+  display: block;
+  position: relative;
+  width: 100%;
+}
+:host([hidden]) {
+  display: none;
+}
+:host(:not([data-embed-mode="inline"])) {
+  width: 0;
+  height: 0;
+}
+.datalayer-app-root,
+.datalayer-app-portal {
+  font-family: var(--fontStack-sansSerif, system-ui, sans-serif);
+}
+.datalayer-app-said {
+  font: 14px/1.5 system-ui, sans-serif;
+  padding: 12px 16px;
+  border: 1px solid #d0d7de;
+  border-radius: 12px;
+  color: #1f2328;
+  background: #ffffff;
+}
+iframe.datalayer-app-frame {
+  display: block;
+  width: 100%;
+  border: 0;
+  min-height: 240px;
+}
+`;
+    return themeCss
+        ? `${own}\n${scopeThemeCss(themeCss, [`[${THEME_SCOPE_ATTRIBUTE}]`])}`
+        : own;
+}

package/lib/loop/index.d.ts

@@ -16,7 +16,7 @@ export { ChatHeaderPlugin, CHAT_HEADER_PLUGIN_NAME, } from './plugins/chat-heade
 export { InputPromptPlugin, INPUT_PROMPT_PLUGIN_NAME, type InputPromptPluginConfig, } from './plugins/input-prompt';
 export { createChatExtrasPlugin, CHAT_EXTRAS_PLUGIN_NAME, type ChatExtrasHandle, } from './plugins/chat-extras';
 export { LoopChatExtras, LoopChatLayout, LoopChatTurn, LoopOpeningDocument, LoopOpeningNotebook, LoopPromptPanel, type ChatLayoutContribution, type ChatLayoutParts, type ChatTurnContribution, type ChatTurnSnapshot, type ChatTurnStatus, type LoopChatExtrasValue, type OpeningDocumentContribution, type OpeningNotebookContribution, type PromptPanelContribution, } from './core';
-export { LoopPageLayoutPlugin, LOOP_PAGE_LAYOUT_PLUGIN_NAME, openConversationPanel, pageLayoutSheet, pageLayoutPanelOpen, setPageLayoutChatMode, type LoopPageLayoutConfig, } from './plugins/page-layout';
+export { LoopPageLayoutPlugin, LOOP_PAGE_LAYOUT_PLUGIN_NAME, openConversationPanel, pageLayoutSheet, pageLayoutPanelOpen, setPageLayoutChatMode, SplitLayout, type LoopPageLayoutConfig, } from './plugins/page-layout';
 export { useOptionalTeamSelection } from './plugins/agents/useTeamSelection';
 export type { TeamMember, TeamSelection } from './plugins/agents/team';
 export { ChatViewPlugin, CHAT_VIEW_PLUGIN_NAME } from './plugins/chat-view';
@@ -50,6 +50,7 @@ export { SANDBOX_CAPACITIES, SandboxCapacityPlugins, } from './plugins/agent-cod
 export { AgentA2uiPlugin, AGENT_A2UI_PLUGIN_NAME } from './plugins/agent-a2ui';
 export { AgentA2uiJupyterOutputPlugin, AGENT_A2UI_JUPYTER_OUTPUT_PLUGIN_NAME, } from './plugins/agent-a2ui-jupyter-output';
 export { defineA2uiScenePlugin, type A2uiSceneOptions, } from './plugins/a2ui-scene';
+export { APP_KIND_PATHS, APP_PAGE_PLUGIN_NAME, APP_PAGE_SURFACE, AppPage, appKindPaths, appPageAction, appPageData, defineAppPagePlugin, hasAppPage, surfaceUnshown, type AppKindPaths, type AppPageAction, type AppPageKind, type AppPagePath, } from './plugins/app-page';
 export { GraphViewPlugin, GRAPH_PLUGIN_NAME, GRAPH_VIEW_TYPE, } from './plugins/graph';
 export { PluginsPanelPlugin, PLUGINS_PANEL_PLUGIN_NAME, PluginsPanel, } from './plugins/plugins-panel';
 export { AGENTS_PLUGIN_NAME, AgentsPlugin, SandboxSelector, browserSource, createBrowserSandboxService, createServerSandboxService, createSwitchableSandboxService, suppliedSource, useOptionalSandboxService, useSandboxService, type AgentsConfig, type AgentsOutput, type SandboxExecution, type SandboxService, type SandboxTarget, type ServiceManagerSource, type SwitchableSandboxService, } from './plugins/agents';
@@ -63,7 +64,10 @@ 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, type AppEmbedProps } from './embed/AppEmbed';
+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 { SubagentActivityPlugin, SubagentPulse, SUBAGENT_ACTIVITY_PLUGIN_NAME, } from './plugins/subagent-activity';
 export { loopPlugins, type LoopPresetOptions } from './presets';
 export { DocumentExtension, NotebookExtension } from './extensions';
-export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, type BehaviourOptions, type ToolArguments, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, type AppCheck, defineAppPlugin, type AppRendererProps, type AppInstance, readAppspecYaml, writeAppspecYaml, type ParsedAppspec, } from './apps';
+export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, type BehaviourOptions, type ToolArguments, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, type AppCheck, type CheckContext, defineAppPlugin, type AppRendererProps, type AppInstance, appLayoutOptions, readAppspecYaml, writeAppspecYaml, type ParsedAppspec, } from './apps';

package/lib/loop/index.js

@@ -29,7 +29,7 @@ export { LoopChatExtras, LoopChatLayout, LoopChatTurn, LoopOpeningDocument, Loop
 export { LoopPageLayoutPlugin, LOOP_PAGE_LAYOUT_PLUGIN_NAME, openConversationPanel, pageLayoutSheet, pageLayoutPanelOpen, 
 // How a host moves the composer: `sidebar` stands it in the conversation
 // panel, under what was said, and opens the panel to show it.
-setPageLayoutChatMode, } from './plugins/page-layout';
+setPageLayoutChatMode, SplitLayout, } from './plugins/page-layout';
 export { useOptionalTeamSelection } from './plugins/agents/useTeamSelection';
 export { ChatViewPlugin, CHAT_VIEW_PLUGIN_NAME } from './plugins/chat-view';
 export { NotebookViewPlugin, NOTEBOOK_VIEW_PLUGIN_NAME, } from './plugins/notebook-view';
@@ -63,6 +63,7 @@ export { SANDBOX_CAPACITIES, SandboxCapacityPlugins, } from './plugins/agent-cod
 export { AgentA2uiPlugin, AGENT_A2UI_PLUGIN_NAME } from './plugins/agent-a2ui';
 export { AgentA2uiJupyterOutputPlugin, AGENT_A2UI_JUPYTER_OUTPUT_PLUGIN_NAME, } from './plugins/agent-a2ui-jupyter-output';
 export { defineA2uiScenePlugin, } from './plugins/a2ui-scene';
+export { APP_KIND_PATHS, APP_PAGE_PLUGIN_NAME, APP_PAGE_SURFACE, AppPage, appKindPaths, appPageAction, appPageData, defineAppPagePlugin, hasAppPage, surfaceUnshown, } from './plugins/app-page';
 export { GraphViewPlugin, GRAPH_PLUGIN_NAME, GRAPH_VIEW_TYPE, } from './plugins/graph';
 export { PluginsPanelPlugin, PLUGINS_PANEL_PLUGIN_NAME, PluginsPanel, } from './plugins/plugins-panel';
 export { AGENTS_PLUGIN_NAME, AgentsPlugin, SandboxSelector, browserSource, createBrowserSandboxService, createServerSandboxService, createSwitchableSandboxService, suppliedSource, useOptionalSandboxService, useSandboxService, } from './plugins/agents';
@@ -81,6 +82,11 @@ export { LoopCommandsPlugin, COMMANDS_PLUGIN_NAME } from './plugins/commands';
 export { PromptPlugin, PROMPT_PLUGIN_NAME } from './plugins/prompt';
 // Loop, ready to drop into somebody else's page.
 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 } from './embed/AppEmbed';
+export { defineDatalayerAppElement, } from './embed/element';
+export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, } 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.
@@ -90,4 +96,4 @@ export { loopPlugins } from './presets';
 export { DocumentExtension, NotebookExtension } from './extensions';
 // Applications: what one does when its agent calls a tool — the rules a
 // person wrote, decided on what the tool does.
-export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, defineAppPlugin, readAppspecYaml, writeAppspecYaml, } from './apps';
+export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, defineAppPlugin, appLayoutOptions, readAppspecYaml, writeAppspecYaml, } from './apps';

package/lib/loop/plugins/a2ui/A2uiView.js

@@ -1,10 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Box, Text } from '@primer/react';
-import { basicCatalog, } from '@a2ui/react/v0_9';
 import { MessageProcessor, } from '@a2ui/web_core/v0_9';
 import { useSignalValue } from '@datalayer/reactor/react';
-import { A2uiSurfaceComposed } from '../../../components/a2ui';
+import { A2uiSurfaceComposed, datalayerCatalog, } from '../../../components/a2ui';
 import { useSandboxService } from '../agents';
 /**
  * A2UI's basic catalog draws from inherited `--a2ui-*` custom properties, so a
@@ -27,7 +26,7 @@ export default function A2uiView({ workspace }) {
     // rather than whatever the sandbox happened to execute last.
     const sourceRef = useRef('');
     const renderRef = useRef(null);
-    const processor = useMemo(() => new MessageProcessor([basicCatalog], action => {
+    const processor = useMemo(() => new MessageProcessor([datalayerCatalog], action => {
         // The round-trip: what the reader did goes back to the code that drew
         // the surface, and the surface it returns replaces this one. Without
         // this a surface is a screenshot with buttons on it.

package/lib/loop/plugins/a2ui-surface/InlineSurface.d.ts

@@ -8,15 +8,35 @@
  * follows, and what keeps a generated form from being the one light card in
  * a dark workspace.
  *
+ * The same renderer draws an application's page (`loop/plugins/app-page`):
+ * there the surface is fed live `data` by path as the conversation moves, and
+ * an action is handed the surface it came from, so that what a block wrote
+ * into its data model can be read when a button is pressed. It draws from
+ * Datalayer's catalog: the basic one, any block shown only while its
+ * `visible_when` holds.
+ *
  * @module loop/plugins/a2ui-surface/InlineSurface
  */
 import type { JSX } from 'react';
-import { type A2uiClientAction, type A2uiMessage } from '@a2ui/web_core/v0_9';
+import type { ReactComponentImplementation } from '@a2ui/react/v0_9';
+import { type A2uiClientAction, type A2uiMessage, type SurfaceModel } from '@a2ui/web_core/v0_9';
+/** A surface as the renderer holds it: its data model is `dataModel`. */
+export type InlineSurfaceModel = SurfaceModel<ReactComponentImplementation>;
+type Surface = InlineSurfaceModel;
 /** The catalogue a surface is rewritten to before it is drawn. */
 export declare const SURFACE_CATALOG_ID: string;
-export declare function InlineSurface({ messages, onAction, validationError, }: {
+/** Values to publish into a surface, by path. */
+export type InlineSurfaceData = Record<string, unknown>;
+export declare function InlineSurface({ messages, onAction, validationError, data, }: {
     messages: A2uiMessage[];
-    onAction: (action: A2uiClientAction) => void;
+    /** Told of an action, with the surface it came from. */
+    onAction: (action: A2uiClientAction, surface?: Surface) => void;
     validationError?: string | null;
+    /**
+     * Values published into every surface's data model, by path, after the
+     * messages are processed and whenever one changes. Only a path whose value
+     * changed is written: what a person typed elsewhere in the model stays.
+     */
+    data?: InlineSurfaceData;
 }): JSX.Element | null;
 export default InlineSurface;

package/lib/loop/plugins/a2ui-surface/InlineSurface.js

@@ -1,23 +1,24 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { Box } from '@datalayer/primer-addons';
-import { basicCatalog, } from '@a2ui/react/v0_9';
 import { MessageProcessor, } from '@a2ui/web_core/v0_9';
-import { A2UI_RENDER_SCOPE_SX, A2uiMarkdownProvider, A2uiSurfaceComposed, } from '../../../components/a2ui';
+import { A2UI_RENDER_SCOPE_SX, A2uiMarkdownProvider, A2uiSurfaceComposed, datalayerCatalog, } from '../../../components/a2ui';
 /** The catalogue a surface is rewritten to before it is drawn. */
-export const SURFACE_CATALOG_ID = basicCatalog.id;
+export const SURFACE_CATALOG_ID = datalayerCatalog.id;
 const INHERIT_THEME = {
     ['--a2ui-color-surface']: 'var(--bgColor-muted)',
     ['--a2ui-color-on-surface']: 'var(--fgColor-default)',
     ['--a2ui-color-primary']: 'var(--fgColor-accent)',
     ['--a2ui-color-outline']: 'var(--borderColor-default)',
 };
-export function InlineSurface({ messages, onAction, validationError, }) {
+export function InlineSurface({ messages, onAction, validationError, data, }) {
     // Reached through a ref: the processor is built once, and the handler it
     // was built with must not go stale when the host's does not.
     const onActionRef = useRef(onAction);
     onActionRef.current = onAction;
-    const processor = useMemo(() => new MessageProcessor([basicCatalog], action => onActionRef.current(action)), []);
+    const processor = useMemo(() => new MessageProcessor([datalayerCatalog], action => onActionRef.current(action, processorRef.current?.model.getSurface(action.surfaceId))), []);
+    const processorRef = useRef(undefined);
+    processorRef.current = processor;
     const [surfaces, setSurfaces] = useState([]);
     useEffect(() => {
         const created = processor.onSurfaceCreated(surface => setSurfaces(previous => [...previous, surface]));
@@ -28,15 +29,41 @@ export function InlineSurface({ messages, onAction, validationError, }) {
         };
     }, [processor]);
     // Once: the messages are one tool result, processed when it arrives.
+    // A tree the catalog refuses is said, where it would have been drawn,
+    // rather than thrown out of an effect and taking the page down with it.
     const processedRef = useRef(false);
+    const [processError, setProcessError] = useState(null);
     useEffect(() => {
         if (processedRef.current) {
             return;
         }
         processedRef.current = true;
-        processor.processMessages(messages);
+        try {
+            processor.processMessages(messages);
+        }
+        catch (error) {
+            setProcessError(`This surface could not be drawn: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }, [messages, processor]);
-    if (surfaces.length === 0) {
+    // After the messages: the surfaces exist by then, created synchronously.
+    const publishedRef = useRef({});
+    useEffect(() => {
+        if (!data) {
+            return;
+        }
+        const published = publishedRef.current;
+        for (const [path, value] of Object.entries(data)) {
+            if (Object.is(published[path], value)) {
+                continue;
+            }
+            published[path] = value;
+            for (const surface of processor.model.surfacesMap.values()) {
+                surface.dataModel.set(path, value);
+            }
+        }
+    }, [data, processor]);
+    const notice = validationError || processError;
+    if (surfaces.length === 0 && !notice) {
         return null;
     }
     return (_jsx(A2uiMarkdownProvider, { children: _jsxs(Box, { style: INHERIT_THEME, sx: {
@@ -44,7 +71,7 @@ export function InlineSurface({ messages, onAction, validationError, }) {
                 display: 'flex',
                 flexDirection: 'column',
                 gap: 2,
-            }, children: [validationError ? (_jsx(Box, { role: "alert", sx: {
+            }, children: [notice ? (_jsx(Box, { role: "alert", sx: {
                         px: 3,
                         py: 2,
                         borderRadius: 2,
@@ -53,7 +80,7 @@ export function InlineSurface({ messages, onAction, validationError, }) {
                         borderColor: 'danger.muted',
                         color: 'danger.fg',
                         fontSize: 1,
-                    }, children: validationError })) : null, surfaces.map(surface => (_jsx(Box, { sx: {
+                    }, children: notice })) : null, surfaces.map(surface => (_jsx(Box, { sx: {
                         border: '1px solid',
                         borderColor: 'border.default',
                         borderRadius: 2,

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

@@ -34,6 +34,10 @@ export type AgentCapacityOptions = {
     createPayload?: Record<string, unknown>;
     /** The openers the empty chat offers for this capacity. */
     suggestions?: ChatSuggestionItem[];
+    /** What the agent is told on top of its spec's prompt when the page turns it. */
+    instructions?: string;
+    /** The model it runs on in the page, in place of its spec's. */
+    model?: string;
 };
 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, } = options;
+    const { key, displayName, description, specId, octicon, emoji, codemode, createPayload, suggestions, instructions, model, } = options;
     return definePlugin({
         name: `@datalayer/loop-plugin-agent-${key}`,
         displayName,
@@ -40,6 +40,8 @@ export function defineAgentCapacityPlugin(options) {
                     enable_codemode: codemode ?? false,
                     ...createPayload,
                 },
+                ...(instructions ? { instructions } : {}),
+                ...(model ? { model } : {}),
             }, { id: key }),
             ...(suggestions && suggestions.length > 0
                 ? [

package/lib/loop/plugins/agents/switchable.d.ts

@@ -105,3 +105,10 @@ export type SwitchableConfig = {
     kernelSource?: ServiceManagerSource;
 };
 export declare function createSwitchableSandboxService({ serverUrl, initialTarget, kernelSource, localAgent, blueprint, }: SwitchableConfig): SwitchableSandboxService;
+/**
+ * Create the agent whose per-agent Jupyter sandbox backs Local, on the
+ * agent-runtimes server at `serverUrl`, unless it is there already — then
+ * only its sandbox is asked for. Exported for a host that addresses the
+ * agent without a workspace: the embed's floating modes (`AppEmbed`).
+ */
+export declare function ensureServerAgent(serverUrl: string, agentId: string | undefined, createPayload: Record<string, unknown>): Promise<void>;

package/lib/loop/plugins/agents/switchable.js

@@ -197,94 +197,9 @@ export function createSwitchableSandboxService({ serverUrl, initialTarget = 'loc
                 (await detail(restart)));
         }
     }
-    /**
-     * Create the agent whose per-agent Jupyter sandbox backs Local.
-     *
-     * The payload is passed rather than read from the closure: the caller has
-     * already established that it exists, and TypeScript cannot carry that
-     * narrowing across a function boundary.
-     */
-    async function ensureLocalAgent(createPayload) {
-        const id = agentId?.trim();
-        if (!id) {
-            throw new Error('Local needs an agent id before its runtime can start.');
-        }
-        let existing;
-        try {
-            existing = await fetch(`${serverUrl}/api/v1/agents/${encodeURIComponent(id)}`);
-        }
-        catch (reason) {
-            throw new Error(`Local needs an agent-runtimes server at ${serverUrl}, and nothing answered there. ` +
-                `Start one and try again. (${reason instanceof Error ? reason.message : String(reason)})`, { cause: reason });
-        }
-        if (existing.ok) {
-            // The agent is there, which does not mean its sandbox is. Reconfiguring
-            // or restarting the manager stops the per-agent sandboxes, because they
-            // were built under the previous settings — so coming back to Local after
-            // a spell on Jupyter finds the agent alive and nothing behind it. Asking
-            // for the sandbox is idempotent, so it costs a round trip and nothing
-            // else when one is already running.
-            await ensureLocalSandbox(id);
-            return;
-        }
-        if (existing.status !== 404) {
-            throw new Error(`The server could not inspect local agent ${id} (${existing.status} ${existing.statusText}). ` +
-                (await detail(existing)));
-        }
-        const created = await fetch(`${serverUrl}/api/v1/agents`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-                // Defaults first, so a blueprint that names its own transport or
-                // sandbox variant — the sandbox capacity plugins do — wins over
-                // them; the name last, because Local's agent id is not negotiable.
-                transport: 'ag-ui',
-                sandbox_variant: 'jupyter-server',
-                ...createPayload,
-                name: id,
-            }),
-        });
-        if (!created.ok && created.status !== 409) {
-            throw new Error(`The server could not launch local agent ${id} (${created.status} ${created.statusText}). ` +
-                (await detail(created)));
-        }
-        // A 409 means somebody else created it between the two calls above, and
-        // that agent is as unlikely to have a sandbox as one found by the GET.
-        if (created.status === 409) {
-            await ensureLocalSandbox(id);
-        }
-    }
-    /**
-     * Make sure the agent has somewhere to run.
-     *
-     * Creating an agent starts its sandbox, so this is only ever needed for one
-     * that already existed. Selecting a target is an operation, not a
-     * preference: when the promise resolves the sandbox is meant to be up, and
-     * without this the kernel indicator sits empty and the notebook binds to
-     * nothing.
-     */
-    async function ensureLocalSandbox(id) {
-        const response = await fetch(`${serverUrl}/api/v1/agents/${encodeURIComponent(id)}/sandbox/ensure`, { method: 'POST' });
-        if (!response.ok) {
-            throw new Error(`The server could not start a sandbox for local agent ${id} ` +
-                `(${response.status} ${response.statusText}). ` +
-                (await detail(response)));
-        }
-    }
-    /**
-     * What the server said went wrong, when it said anything.
-     *
-     * FastAPI puts the reason in `detail`, and a status code on its own sends a
-     * reader to the network tab for something the response already contained.
-     */
-    async function detail(response) {
-        try {
-            const body = (await response.json());
-            return typeof body.detail === 'string' ? body.detail : '';
-        }
-        catch {
-            return '';
-        }
+    /** The agent backing Local, on this workspace's server. */
+    function ensureLocalAgent(createPayload) {
+        return ensureServerAgent(serverUrl, agentId, createPayload);
     }
     function connectActive() {
         disconnect?.();
@@ -403,3 +318,91 @@ export function createSwitchableSandboxService({ serverUrl, initialTarget = 'loc
         },
     };
 }
+/**
+ * Create the agent whose per-agent Jupyter sandbox backs Local, on the
+ * agent-runtimes server at `serverUrl`, unless it is there already — then
+ * only its sandbox is asked for. Exported for a host that addresses the
+ * agent without a workspace: the embed's floating modes (`AppEmbed`).
+ */
+export async function ensureServerAgent(serverUrl, agentId, createPayload) {
+    const id = agentId?.trim();
+    if (!id) {
+        throw new Error('Local needs an agent id before its runtime can start.');
+    }
+    let existing;
+    try {
+        existing = await fetch(`${serverUrl}/api/v1/agents/${encodeURIComponent(id)}`);
+    }
+    catch (reason) {
+        throw new Error(`Local needs an agent-runtimes server at ${serverUrl}, and nothing answered there. ` +
+            `Start one and try again. (${reason instanceof Error ? reason.message : String(reason)})`, { cause: reason });
+    }
+    if (existing.ok) {
+        // The agent is there, which does not mean its sandbox is. Reconfiguring
+        // or restarting the manager stops the per-agent sandboxes, because they
+        // were built under the previous settings — so coming back to Local after
+        // a spell on Jupyter finds the agent alive and nothing behind it. Asking
+        // for the sandbox is idempotent, so it costs a round trip and nothing
+        // else when one is already running.
+        await ensureServerSandbox(serverUrl, id);
+        return;
+    }
+    if (existing.status !== 404) {
+        throw new Error(`The server could not inspect local agent ${id} (${existing.status} ${existing.statusText}). ` +
+            (await detail(existing)));
+    }
+    const created = await fetch(`${serverUrl}/api/v1/agents`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            // Defaults first, so a blueprint that names its own transport or
+            // sandbox variant — the sandbox capacity plugins do — wins over
+            // them; the name last, because Local's agent id is not negotiable.
+            transport: 'ag-ui',
+            sandbox_variant: 'jupyter-server',
+            ...createPayload,
+            name: id,
+        }),
+    });
+    if (!created.ok && created.status !== 409) {
+        throw new Error(`The server could not launch local agent ${id} (${created.status} ${created.statusText}). ` +
+            (await detail(created)));
+    }
+    // A 409 means somebody else created it between the two calls above, and
+    // that agent is as unlikely to have a sandbox as one found by the GET.
+    if (created.status === 409) {
+        await ensureServerSandbox(serverUrl, id);
+    }
+}
+/**
+ * Make sure the agent has somewhere to run.
+ *
+ * Creating an agent starts its sandbox, so this is only ever needed for one
+ * that already existed. Selecting a target is an operation, not a
+ * preference: when the promise resolves the sandbox is meant to be up, and
+ * without this the kernel indicator sits empty and the notebook binds to
+ * nothing.
+ */
+async function ensureServerSandbox(serverUrl, id) {
+    const response = await fetch(`${serverUrl}/api/v1/agents/${encodeURIComponent(id)}/sandbox/ensure`, { method: 'POST' });
+    if (!response.ok) {
+        throw new Error(`The server could not start a sandbox for local agent ${id} ` +
+            `(${response.status} ${response.statusText}). ` +
+            (await detail(response)));
+    }
+}
+/**
+ * What the server said went wrong, when it said anything.
+ *
+ * FastAPI puts the reason in `detail`, and a status code on its own sends a
+ * reader to the network tab for something the response already contained.
+ */
+async function detail(response) {
+    try {
+        const body = (await response.json());
+        return typeof body.detail === 'string' ? body.detail : '';
+    }
+    catch {
+        return '';
+    }
+}

package/lib/loop/plugins/app-page/AppPage.d.ts

@@ -0,0 +1,16 @@
+/**
+ * An application's page, drawn beside its conversation: its A2UI surface on
+ * the workspace's own renderer (`InlineSurface`), fed by the chat's current
+ * turn, its buttons answered through the chat's controls.
+ *
+ * @module loop/plugins/app-page/AppPage
+ */
+import type { JSX } from 'react';
+import type { AppSpec } from '../../../types/agentspecs';
+import { type LoopWorkspaceContext } from '../../core';
+export type AppPageProps = {
+    app: AppSpec;
+    workspace: LoopWorkspaceContext;
+};
+export declare function AppPage({ app, workspace }: AppPageProps): JSX.Element;
+export default AppPage;

package/lib/loop/plugins/app-page/AppPage.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { Box } from '@datalayer/primer-addons';
+import { signal } from '@datalayer/reactor';
+import { useContributions, useSignalValue } from '@datalayer/reactor/react';
+import { LoopChatTurn, } from '../../core';
+import { InlineSurface, SURFACE_CATALOG_ID, } from '../a2ui-surface/InlineSurface';
+import { appPageAction, appPageData, appPageMessages } from './appPageModel';
+/** No chat in the workspace: the page reads a turn that never starts. */
+const NO_TURN = signal({ id: 0, status: 'idle' });
+export function AppPage({ app, workspace }) {
+    const entries = useContributions(LoopChatTurn);
+    const turn = useSignalValue(entries[0]?.value.turn ?? NO_TURN);
+    const messages = useMemo(() => appPageMessages(app, SURFACE_CATALOG_ID), [app]);
+    const data = useMemo(() => appPageData(app, turn), [app, turn]);
+    const [refusal, setRefusal] = useState(null);
+    // The workspace changes as the chat reports itself; the handler reads the latest.
+    const workspaceRef = useRef(workspace);
+    workspaceRef.current = workspace;
+    // The inputs in words as last sent: a chat's message carries them when they change.
+    const lastInputs = useRef('');
+    const onAction = useCallback((action, surface) => {
+        const outcome = appPageAction(app, { name: action.name, context: action.context ?? {} }, path => surface?.dataModel.get(path), lastInputs.current);
+        const controls = workspaceRef.current.viewControls;
+        if ('refused' in outcome) {
+            setRefusal(outcome.refused);
+            return;
+        }
+        setRefusal(null);
+        if ('stop' in outcome) {
+            controls.stop?.();
+        }
+        else if ('newChat' in outcome) {
+            controls.newChat?.();
+        }
+        else {
+            // The chat's own send, as a surface in the transcript submits; the
+            // prompt channel when the chat has not reported itself yet.
+            if (controls.send) {
+                controls.send(outcome.send);
+            }
+            else {
+                workspaceRef.current.prompts.submit(outcome.send);
+            }
+            lastInputs.current = outcome.inputs;
+            for (const path of outcome.clear) {
+                surface?.dataModel.set(path, '');
+            }
+        }
+    }, [app]);
+    return (_jsx(Box, { "data-testid": "app-page", sx: { height: '100%', minHeight: 0, overflow: 'auto', p: 3 }, children: _jsx(InlineSurface, { messages: messages, data: data, onAction: onAction, validationError: refusal }) }));
+}
+export default AppPage;