@datalayer/agent-runtimes 1.3.86 → 1.3.88

package/lib/components/teams/useA2ATeam.js

@@ -22,7 +22,12 @@
  * and the way each link carries a message as its flow ({@link flowAfter}).
  * What a peer gives besides words — the formats the page accepts
  * (`accept`), such as a Jupyter notebook — is kept as its artifacts, and
- * the latest notebook kept until another one comes ({@link A2ATeam.notebook}).
+ * the latest notebook kept until another one comes ({@link A2ATeam.notebook}),
+ * and each surface of components of the catalog a peer shows
+ * (`application/json+a2ui`) kept with the peer that gave it, in the order
+ * they came ({@link A2ATeam.surfaces}, STUDIO H-02). A button pressed on
+ * one is a turn of the conversation ({@link A2ATeam.pressAction}): the
+ * person's line to that member, its answer from it, in the entry's history.
  * The tools a peer calls on its connections (its MCP servers), told over
  * A2A as it calls them, are kept as the calls running now ({@link callsAfter}).
  *
@@ -39,9 +44,10 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { stepCountIs, ToolLoopAgent } from 'ai';
 import { createBrowserModel, } from '../../runtimes/browser/model';
-import { a2aPeerTool, askA2APeer, NOTEBOOK_MEDIA_TYPE, } from '../../runtimes/browser/a2aPeer';
+import { a2aPeerTool, askA2APeer, A2UI_MEDIA_TYPE, NOTEBOOK_MEDIA_TYPE, } from '../../runtimes/browser/a2aPeer';
 import { endAgentTurn, endToolCall, startAgentTurn, startToolCall, } from '../inspector/agentSpans';
 import { callsAfter, flowAfter, toolOwnName, pruneCalls, } from './a2aTeamFlow';
+import { PERSON } from './sceneTranscript';
 import { toolLineOfStep, } from '../../chat/assistant/toolLine';
 const NO_CONNECTIONS = [];
 const NO_PEERS = [];
@@ -55,11 +61,42 @@ export const NOTEBOOK_AND_WORDS = [
     NOTEBOOK_MEDIA_TYPE,
     'text/markdown',
 ];
+/**
+ * What a page that draws an answer's components accepts besides: the
+ * catalog's surfaces, a notebook, and words in Markdown (STUDIO H-02).
+ */
+export const COMPONENTS_NOTEBOOK_AND_WORDS = [
+    A2UI_MEDIA_TYPE,
+    ...NOTEBOOK_AND_WORDS,
+];
+/**
+ * The surfaces among what a member gave, each once by its surface's id,
+ * after those already kept.
+ */
+export function surfacesAfter(kept, giver, artifacts) {
+    const found = artifacts
+        .filter(artifact => artifact.mediaType === A2UI_MEDIA_TYPE)
+        .map(artifact => {
+        const data = artifact.data;
+        return {
+            id: data && typeof data.surfaceId === 'string'
+                ? data.surfaceId
+                : `${giver}-${kept.length}`,
+            giver,
+            artifact,
+        };
+    })
+        .filter((surface, index, all) => !kept.some(one => one.id === surface.id) &&
+        all.findIndex(one => one.id === surface.id) === index);
+    return found.length ? [...kept, ...found] : kept;
+}
 /** What the peer gave, in words: its words, and each of its artifacts. */
 export function answeredLine(artifacts) {
     const besides = artifacts.map(artifact => artifact.mediaType === NOTEBOOK_MEDIA_TYPE
         ? `a notebook, ${artifact.name}`
-        : artifact.name);
+        : artifact.mediaType === A2UI_MEDIA_TYPE
+            ? `what it shows, ${artifact.name}`
+            : artifact.name);
     return besides.length ? `the report and ${besides.join(', ')}` : 'the report';
 }
 /** The latest notebook among what a peer gave, or none. */
@@ -221,6 +258,7 @@ export function useA2ATeam(options) {
     const [artifacts, setArtifacts] = useState([]);
     const [givens, setGivens] = useState({});
     const [notebook, setNotebook] = useState(null);
+    const [surfaces, setSurfaces] = useState([]);
     const [flows, setFlows] = useState({});
     const [calls, setCalls] = useState([]);
     const callsNow = useRef([]);
@@ -291,6 +329,7 @@ export function useA2ATeam(options) {
             setReports(prev => ({ ...prev, [id]: event.answer }));
             setArtifacts(event.artifacts);
             setGivens(prev => ({ ...prev, [id]: event.artifacts }));
+            setSurfaces(prev => surfacesAfter(prev, id, event.artifacts));
             const given = notebookAmong(event.artifacts);
             if (given) {
                 setNotebook(given);
@@ -575,6 +614,72 @@ export function useA2ATeam(options) {
         setPersona,
         peersAtRest,
     ]);
+    const pressAction = useCallback(async (memberId, pressed) => {
+        const words = pressed.message.trim();
+        const isEntry = memberId === entry.id;
+        const one = isEntry ? undefined : peerOf(memberId);
+        const name = isEntry ? entry.name : (one?.app.name ?? memberId);
+        const to = isEntry ? entryPeer : (one?.peer ?? null);
+        if (!to) {
+            throw new Error(`${name} is not reached: it cannot be asked.`);
+        }
+        if (busy) {
+            throw new Error('Wait for the answer under way, then choose.');
+        }
+        if (!words) {
+            throw new Error('This button says nothing to send.');
+        }
+        // The entry's own button is a turn with it; another member's is
+        // addressed to that member, and answered by it.
+        const member = isEntry ? undefined : { id: memberId, name };
+        const withMember = member ? { member } : {};
+        setBusy(true);
+        setTurns(prev => [...prev, { role: 'user', text: words, ...withMember }]);
+        abort.current = new AbortController();
+        try {
+            const { answer } = await askA2APeer(to, words, {
+                signal: abort.current.signal,
+                action: pressed.action,
+                accept,
+                onEvent: event => onMemberEvent(memberId, event),
+            });
+            setTurns(prev => [
+                ...prev,
+                { role: 'assistant', text: answer, ...withMember },
+            ]);
+            if (!entryPeer) {
+                // The entry's model reads it at its next turn: what was chosen,
+                // and what the member answered.
+                history.current = [
+                    ...history.current,
+                    { role: 'user', content: words },
+                    {
+                        role: 'assistant',
+                        content: `${name} answered the person directly: ${answer}`,
+                    },
+                ];
+            }
+            // Answered: back at rest, its words still in its balloon.
+            setPersona(memberId, prev => ({ ...prev, state: 'idle' }));
+            return answer;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            setTurns(prev => [
+                ...prev,
+                {
+                    role: 'assistant',
+                    text: `Could not answer: ${message}`,
+                    ...withMember,
+                },
+            ]);
+            throw error;
+        }
+        finally {
+            abort.current = null;
+            setBusy(false);
+        }
+    }, [entry, entryPeer, peerOf, busy, accept, onMemberEvent, setPersona]);
     const stop = useCallback(() => abort.current?.abort(), []);
     useEffect(() => () => {
         abort.current?.abort();
@@ -594,6 +699,18 @@ export function useA2ATeam(options) {
         role: turn.role,
         content: turn.text,
         createdAt: new Date(0),
+        // A button pressed on another member's surface: the person's line
+        // to it, and its answer, said by it.
+        ...(turn.member
+            ? turn.role === 'user'
+                ? {
+                    speaker: { id: 'person', name: PERSON },
+                    directedTo: { id: turn.member.id, name: turn.member.name },
+                }
+                : {
+                    speaker: { id: turn.member.id, name: turn.member.name },
+                }
+            : {}),
     })), [turns]);
     const NONE = useMemo(() => [], []);
     const teamPeers = useMemo(() => peerList.map(one => ({
@@ -623,11 +740,13 @@ export function useA2ATeam(options) {
         report,
         artifacts,
         notebook,
+        surfaces,
         flow: first?.flow ?? 'still',
         calls,
         busy,
         ready: entryPeer ? true : agent !== null,
         send,
+        pressAction,
         stop,
     };
 }

package/lib/hooks/useAgentRuntimes.d.ts

@@ -49,7 +49,20 @@ export interface UseAgentOptions {
      * connection bootstrap as well as agent creation.
      */
     runtimeConnection?: AgentRuntimeConnectionOptions;
+    /**
+     * The application the runtime is launched for (STUDIO R-19): its Appspec,
+     * and the saved application and deployment it runs for. Sent with the
+     * launch, as `RuntimesClient.create` sends it in Python, so the runtime is
+     * given the secrets its connections declare before its agent is made.
+     *
+     * An application's runtime is always its own: a running runtime is never
+     * looked up and reused for it, since one not launched for the application
+     * was not given its secrets.
+     */
+    appLaunch?: AppLaunch;
 }
+/** What an application's launch carries besides its environment (R-19). */
+export type AppLaunch = Required<Pick<IRuntimeOptions, 'appSpec'>> & Pick<IRuntimeOptions, 'appUid' | 'deploymentUid'>;
 /**
  * Return type for the useAgents hook.
  */

package/lib/hooks/useAgentRuntimes.js

@@ -362,7 +362,7 @@ function toAgentRuntimeData(raw) {
  * ```
  */
 export function useAgentRuntimes(options = {}) {
-    const { agentSpecId, agentConfig, autoCreateAgent = true, autoStart = false, agentSpec, variant: variantOption, runtimeCreationTarget, runtimeCreationBaseUrl, runtimeConnection, } = options;
+    const { agentSpecId, agentConfig, autoCreateAgent = true, autoStart = false, agentSpec, variant: variantOption, runtimeCreationTarget, runtimeCreationBaseUrl, runtimeConnection, appLaunch, } = options;
     // Both vocabularies funnel into one value here, so no branch below has to
     // remember that the old names exist.
     const variant = toAgentRuntimeVariant(variantOption ?? runtimeCreationTarget);
@@ -484,12 +484,14 @@ export function useAgentRuntimes(options = {}) {
                 const conn = await storeLaunchAgent(runtimeOptions
                     ? {
                         ...runtimeOptions,
+                        ...appLaunch,
                         runtimesUrl: resolvedRuntimeCreationBaseUrl,
                     }
                     : {
                         environmentName: 'ai-agents-env',
                         creditsLimit: 10,
                         givenName: safeName,
+                        ...appLaunch,
                         runtimesUrl: resolvedRuntimeCreationBaseUrl,
                     });
                 setLifecycleStatus('ready');
@@ -515,6 +517,7 @@ export function useAgentRuntimes(options = {}) {
         agentConfig?.name,
         agentSpec?.name,
         agentSpecId,
+        appLaunch,
         hasSpec,
         resolvedRuntimeCreationBaseUrl,
         storeLaunchAgent,
@@ -654,6 +657,12 @@ export function useAgentRuntimes(options = {}) {
         if (!hasSpec || runtime || lifecycleStatus !== 'idle') {
             return;
         }
+        if (appLaunch) {
+            // An application's runtime is launched for it (R-19): a running one
+            // was not given its connections' secrets, so none is looked for.
+            setLookedForExisting(true);
+            return;
+        }
         let cancelled = false;
         const bootstrap = async () => {
             try {
@@ -736,6 +745,7 @@ export function useAgentRuntimes(options = {}) {
         lifecycleStatus,
         getAuthHeaders,
         agentSpecId,
+        appLaunch,
         storeConnectAgent,
     ]);
     // Reset agent creation tracking on disconnect

package/lib/loop/apps/AppFeedback.js

@@ -6,13 +6,17 @@ import { contribution, definePlugin, signal } from '@datalayer/reactor';
 import { useContributions, useSignalValue } from '@datalayer/reactor/react';
 import { useIAMStore } from '../../state';
 import { LoopChatTurn, LoopPromptPanel, } from '../core';
-import { FEEDBACK_WORDS, sendFeedback } from './feedback';
+import { answerIdOf, FEEDBACK_WORDS, sendFeedback } from './feedback';
 export const APP_FEEDBACK_PLUGIN_NAME = '@datalayer/loop-plugin-app-feedback';
 /* A signal to read when no chat contributed a turn: the hook needs one. */
 const NO_TURN = signal({ id: 0, status: 'idle' });
+const NO_CONVERSATION = signal([]);
 export function AppFeedback({ app, workspace, }) {
     const turns = useContributions(LoopChatTurn);
     const turn = useSignalValue(turns[0]?.value.turn ?? NO_TURN);
+    // Which answer it is about (P-24): its place among the conversation's answers.
+    const conversation = useSignalValue(turns[0]?.value.conversation ?? NO_CONVERSATION);
+    const answers = conversation.filter(entry => entry.role === 'assistant').length;
     const token = useIAMStore(state => state.token);
     const [liked, setLiked] = useState(null);
     const [comment, setComment] = useState('');
@@ -31,7 +35,12 @@ export function AppFeedback({ app, workspace, }) {
         }
         setSaid({ turn: turn.id, state: 'sending', says: '' });
         try {
-            await sendFeedback({ session: thread, liked: choice, comment }, { agentBaseUrl, token });
+            await sendFeedback({
+                session: thread,
+                liked: choice,
+                comment,
+                message: answerIdOf(answers),
+            }, { agentBaseUrl, token });
             setSaid({
                 turn: turn.id,
                 state: 'kept',

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

@@ -45,7 +45,7 @@
  * @module loop/apps/AppRenderer
  */
 import { type ComponentType } from 'react';
-import type { PluginRef, ReactorPlugin } from '@datalayer/reactor';
+import { type PluginRef, type ReactorExtension, type ReactorPlugin } from '@datalayer/reactor';
 import type { AppSpec } from '../../types/agentspecs';
 import type { ThemeOverrides } from '../../types/chat';
 import { type AppHostPageProps } from '../plugins/app-page';
@@ -58,6 +58,11 @@ export declare const agentIdOf: (app: Pick<AppSpec, "agent" | "team">) => string
 /**
  * The plugin that makes a LOOP workspace run an application.
  *
+ * Its page plugin of the pair (LOOP F-15): named `loop-app-<id>`, as its
+ * runtime's plugin is, and requiring it — so that it stands down while its
+ * runtime does not hold the application, and comes back when it does
+ * (`AppRuntimePlugins` follows the runtime).
+ *
  * The agent is created with the application's own document (`app_spec`) in
  * its payload; a runtime that knows applications configures the agent from
  * it, and one that does not creates the agent alone — the application is
@@ -68,6 +73,13 @@ export declare const agentIdOf: (app: Pick<AppSpec, "agent" | "team">) => string
  * is not an agent spec, and is refused here rather than launched as one.
  */
 export declare function defineAppPlugin(app: AppSpec, shown?: AppSpec): ReactorPlugin<Record<string, never>, unknown, unknown>;
+/**
+ * The application on the page: its plugins delivered as one extension named
+ * as its plugin pair is, `loop-app-<id>` — the extension its runtime's plugin
+ * says too, so that Reactor's manager ("Delivered by") and graph show the
+ * page's plugins and the runtime's as one application (LOOP F-15).
+ */
+export declare function appExtension(app: AppSpec, shown: AppSpec, plugins: PluginRef[]): ReactorExtension;
 /** Which instance of an application runs, as the platform knows it (LOOP R-07). */
 export type AppInstance = {
     /** Its `app` item. */

package/lib/loop/apps/AppRenderer.js

@@ -50,6 +50,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * @module loop/apps/AppRenderer
  */
 import { useMemo } from 'react';
+import { defineExtension, } from '@datalayer/reactor';
 import { loopAccentStyles, useSystemColorMode, useThemeStore, } from '@datalayer/primer-addons';
 import { defineAgentCapacityPlugin } from '../plugins/agent-capacity';
 import { APP_PAGE_SURFACE, defineAppHostPagePlugin, defineAppPagePlugin, hasAppPage, } from '../plugins/app-page';
@@ -69,6 +70,8 @@ import { defineAppKeptPlugin } from './AppKept';
 import { keepsFeedback } from './feedback';
 import { keptBeforeFirstMessage } from './kept';
 import { ChatLanguage } from '../../chat/ChatLanguage';
+import { defineAppRuntimePlugin } from './AppRuntimePlugins';
+import { appPluginPair } from './pluginPair';
 /** The id of an agent or a Cog, without its version. */
 export const agentIdOf = (app) => {
     const reference = app.agent || app.team;
@@ -80,6 +83,11 @@ export const agentIdOf = (app) => {
 /**
  * The plugin that makes a LOOP workspace run an application.
  *
+ * Its page plugin of the pair (LOOP F-15): named `loop-app-<id>`, as its
+ * runtime's plugin is, and requiring it — so that it stands down while its
+ * runtime does not hold the application, and comes back when it does
+ * (`AppRuntimePlugins` follows the runtime).
+ *
  * The agent is created with the application's own document (`app_spec`) in
  * its payload; a runtime that knows applications configures the agent from
  * it, and one that does not creates the agent alone — the application is
@@ -93,8 +101,11 @@ export function defineAppPlugin(app, shown = app) {
     if (!app.agent) {
         throw new Error(`“${app.name}” is run by a team, which the workspace does not run as an application yet.`);
     }
+    const pair = appPluginPair(app.id);
     return defineAgentCapacityPlugin({
         key: `app-${app.id}`,
+        name: pair.page.name,
+        requiredBackendPlugins: pair.page.requiredBackendPlugins,
         // What a person reads is in their language (P-26); what it is created
         // with is its own Appspec.
         displayName: shown.name,
@@ -128,6 +139,22 @@ export function defineAppPlugin(app, shown = app) {
             : {}),
     });
 }
+/**
+ * The application on the page: its plugins delivered as one extension named
+ * as its plugin pair is, `loop-app-<id>` — the extension its runtime's plugin
+ * says too, so that Reactor's manager ("Delivered by") and graph show the
+ * page's plugins and the runtime's as one application (LOOP F-15).
+ */
+export function appExtension(app, shown, plugins) {
+    return defineExtension({
+        name: appPluginPair(app.id).extension,
+        displayName: shown.name,
+        description: shown.description || `The ${shown.name} application`,
+        emoji: app.emoji,
+        version: app.version,
+        plugins,
+    });
+}
 /**
  * The workspace an application's layout asks for (LOOP T-07).
  *
@@ -205,6 +232,8 @@ export function appPreset(app, options = {}) {
     return {
         plugins: [
             defineAppPlugin(app, shown),
+            // What its runtime holds, told to the page (F-15).
+            defineAppRuntimePlugin(app.id),
             ...(withPage ? [defineAppPagePlugin(shown), ...blocks] : []),
             // The components its developer wrote (LOOP P-17): blocks of its page
             // and renderers of its page, its elements and its answers — its own.
@@ -353,7 +382,11 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, o
         deployed,
         visitor,
     ]);
-    const allPlugins = useMemo(() => ('problem' in preset ? plugins : [...preset.plugins, ...plugins]), [preset, plugins]);
+    const allPlugins = useMemo(() => 'problem' in preset
+        ? plugins
+        : [appExtension(app, shown, preset.plugins), ...plugins], 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [preset, 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

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

@@ -0,0 +1,8 @@
+import { type ReactorPlugin } from '@datalayer/reactor';
+export declare const APP_RUNTIME_PLUGIN_NAME = "@datalayer/loop-plugin-app-runtime";
+/** Follows the application's runtime, and tells the page what it holds. */
+export declare function AppRuntimePlugins({ appId }: {
+    appId: string;
+}): null;
+/** The plugin that follows an application's runtime for its page. */
+export declare function defineAppRuntimePlugin(appId: string): ReactorPlugin<Record<string, never>, unknown, unknown>;

package/lib/loop/apps/AppRuntimePlugins.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The page told which of an application's plugins its runtime holds (LOOP
+ * F-15).
+ *
+ * The application's page plugin requires the runtime's plugin of the same
+ * name (`requiredBackendPlugins`). Reactor stands such a plugin down while
+ * the plugin it requires is not running, and brings it back when it is — but
+ * only a host that says what runs can make that true. Every place an
+ * application appears draws it with `AppRenderer`, so this is said once, for
+ * all of them — the Studio's Preview, its address, an embed, the browser
+ * alone:
+ *
+ * - on a runtime, Reactor's `useBackendPluginStream` follows the runtime's
+ *   `/api/v1/apps/<id>/plugins/state` (and its stream): the page's plugin
+ *   stands down when the runtime no longer holds the application, and comes
+ *   back when it does;
+ * - with no runtime — the browser alone, or one still starting — the page is
+ *   its own runtime, and the pair is whole: nothing stands down, nothing is
+ *   blank.
+ *
+ * A plugin of its own, with no backend requirement, so that it keeps
+ * listening while the application's plugin is stood down. It renders nothing.
+ *
+ * @module loop/apps/AppRuntimePlugins
+ */
+import { useCallback, useEffect } from 'react';
+import { definePlugin } from '@datalayer/reactor';
+import { registerReactor, useBackendPluginStream, useReactorPlatform, useSignalValue, } from '@datalayer/reactor/react';
+import { IDLE_SANDBOX_SNAPSHOT_SIGNAL, IDLE_SANDBOX_TARGET_SIGNAL, LoopSlots, } from '../core';
+import { useOptionalSandboxService } from '../plugins/agents/useSandboxService';
+import { appPluginName, appPluginsBase, appRuntimeOf } from './pluginPair';
+export const APP_RUNTIME_PLUGIN_NAME = '@datalayer/loop-plugin-app-runtime';
+/** A host's answer to "is this runtime plugin running?", from a list. */
+const runningOf = (names) => (name) => names.includes(name);
+/** Follows the application's runtime, and tells the page what it holds. */
+export function AppRuntimePlugins({ appId }) {
+    const reactor = useReactorPlatform();
+    const service = useOptionalSandboxService();
+    const target = useSignalValue(service?.target ?? IDLE_SANDBOX_TARGET_SIGNAL);
+    const snapshot = useSignalValue(service?.snapshot ?? IDLE_SANDBOX_SNAPSHOT_SIGNAL);
+    const runtime = appRuntimeOf({
+        target,
+        snapshot,
+        serverUrl: service?.serverUrl,
+    });
+    const name = appPluginName(appId);
+    // No runtime: the page is its own, and the pair is whole.
+    useEffect(() => {
+        if (runtime) {
+            return;
+        }
+        registerReactor(reactor, runningOf([name]));
+        void reactor.setBackendPlugins([name]);
+    }, [reactor, runtime, name]);
+    // On one: what it says, for the slots gated on it too.
+    const onState = useCallback((state) => registerReactor(reactor, runningOf(state.plugins
+        .filter(plugin => plugin.enabled)
+        .map(plugin => plugin.name))), [reactor]);
+    useBackendPluginStream(runtime ? appPluginsBase(runtime, appId) : undefined, {
+        onState,
+    });
+    return null;
+}
+/** The plugin that follows an application's runtime for its page. */
+export function defineAppRuntimePlugin(appId) {
+    const Follow = () => _jsx(AppRuntimePlugins, { appId: appId });
+    return definePlugin({
+        name: APP_RUNTIME_PLUGIN_NAME,
+        displayName: 'Its runtime',
+        description: 'Tells the application’s page which of its plugins its runtime holds.',
+        octicon: 'server',
+        build: () => ({
+            components: [
+                {
+                    slot: LoopSlots.status,
+                    id: 'app-runtime-plugins',
+                    Component: Follow,
+                },
+            ],
+        }),
+    });
+}

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

@@ -21,7 +21,14 @@ export type Feedback = {
     session: string;
     liked: boolean;
     comment: string;
+    /**
+     * The answer it is about (LOOP P-24): `answer-<n>`, its place among the
+     * conversation's answers; none for the conversation as a whole.
+     */
+    message?: string;
 };
+/** How an answer is named in feedback: its place among the conversation's answers, from 1. */
+export declare const answerIdOf: (answers: number) => string | undefined;
 /** What the feedback strip says, in a person's words. */
 export declare const FEEDBACK_WORDS: {
     readonly ask: "Was this answer useful?";

package/lib/loop/apps/feedback.js

@@ -4,6 +4,8 @@
  */
 /** The longest comment kept, as the runtime holds it (`COMMENT_LIMIT`). */
 export const FEEDBACK_COMMENT_LIMIT = 2000;
+/** How an answer is named in feedback: its place among the conversation's answers, from 1. */
+export const answerIdOf = (answers) => answers > 0 ? `answer-${answers}` : undefined;
 /** What the feedback strip says, in a person's words. */
 export const FEEDBACK_WORDS = {
     ask: 'Was this answer useful?',
@@ -50,6 +52,7 @@ export async function sendFeedback(feedback, { agentBaseUrl, token, fetcher = fe
             session: feedback.session,
             liked: feedback.liked,
             comment: feedback.comment.trim(),
+            ...(feedback.message ? { message: feedback.message } : {}),
         }),
     });
     const body = (await response.json().catch(() => ({})));

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

@@ -0,0 +1,60 @@
+/**
+ * An application's two Reactor plugins, named once (LOOP F-15).
+ *
+ * Whichever editor wrote it — a spec, the Canvas, an `app.py` — an
+ * application is a pair of plugins of one name, `loop-app-<id>`: the page's
+ * (`defineAppPlugin`) and the runtime's (`manifest_of` in
+ * `agent_runtimes.loop.apps.plugins`, which says the same name). Each
+ * declares the other: the page's `requiredBackendPlugins`, the runtime's
+ * `frontend_dependencies`; and both are delivered as one extension of that
+ * name, which is how Reactor's manager and graph show them as one
+ * application.
+ *
+ * The page follows what its runtime holds with Reactor's
+ * `useBackendPluginStream`, on `appPluginsBase` (`AppRuntimePlugins`).
+ *
+ * @module loop/apps/pluginPair
+ */
+import type { SandboxSnapshot } from '../core';
+import type { SandboxTarget } from '../plugins/agents/switchable';
+/** The one name of an application's two plugins, the page's and the runtime's. */
+export declare const appPluginName: (appId: string) => string;
+/** What each tier of an application's pair says. */
+export type AppPluginPair = {
+    /** The page's plugin, and the runtime plugin it cannot work without. */
+    page: {
+        name: string;
+        requiredBackendPlugins: string[];
+    };
+    /** The runtime's plugin, and the page plugin it cannot be used without. */
+    server: {
+        name: string;
+        frontendDependencies: string[];
+    };
+    /** The extension that delivers both: the application. */
+    extension: string;
+};
+/** The pair an application of this id is, on both tiers. */
+export declare function appPluginPair(appId: string): AppPluginPair;
+/**
+ * Where Reactor's `useBackendPluginStream` reads an application's plugins on
+ * its runtime: `<base>/plugins/state`, `<base>/events/stream` — about that
+ * application only, so that a runtime several share says nothing of the
+ * others.
+ */
+export declare const appPluginsBase: (runtimeUrl: string, appId: string) => string;
+/**
+ * The runtime an application's page follows, or `undefined` when it runs on
+ * none yet.
+ *
+ * - **In the browser alone**: none — the page is its own runtime.
+ * - **On Datalayer**: the runtime its agent was made on, once reported
+ *   (`agent_base_url`) — at its address, embedded, on the visitors' runtime.
+ * - **Here** (`local`, `jupyter`): the workspace's server, once it runs —
+ *   after the agent was made there with the application, never before.
+ */
+export declare function appRuntimeOf({ target, snapshot, serverUrl, }: {
+    target: SandboxTarget | undefined;
+    snapshot: Pick<SandboxSnapshot, 'state' | 'agentBaseUrl'>;
+    serverUrl: string | undefined;
+}): string | undefined;

package/lib/loop/apps/pluginPair.js

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The one name of an application's two plugins, the page's and the runtime's. */
+export const appPluginName = (appId) => `loop-app-${appId}`;
+/** The pair an application of this id is, on both tiers. */
+export function appPluginPair(appId) {
+    const name = appPluginName(appId);
+    return {
+        page: { name, requiredBackendPlugins: [name] },
+        server: { name, frontendDependencies: [name] },
+        extension: name,
+    };
+}
+/**
+ * Where Reactor's `useBackendPluginStream` reads an application's plugins on
+ * its runtime: `<base>/plugins/state`, `<base>/events/stream` — about that
+ * application only, so that a runtime several share says nothing of the
+ * others.
+ */
+export const appPluginsBase = (runtimeUrl, appId) => `${runtimeUrl.replace(/\/+$/, '')}/api/v1/apps/${encodeURIComponent(appId)}`;
+/**
+ * The runtime an application's page follows, or `undefined` when it runs on
+ * none yet.
+ *
+ * - **In the browser alone**: none — the page is its own runtime.
+ * - **On Datalayer**: the runtime its agent was made on, once reported
+ *   (`agent_base_url`) — at its address, embedded, on the visitors' runtime.
+ * - **Here** (`local`, `jupyter`): the workspace's server, once it runs —
+ *   after the agent was made there with the application, never before.
+ */
+export function appRuntimeOf({ target, snapshot, serverUrl, }) {
+    if (!target || target === 'browser') {
+        return undefined;
+    }
+    if (snapshot.agentBaseUrl) {
+        return snapshot.agentBaseUrl;
+    }
+    if (target === 'datalayer') {
+        return undefined;
+    }
+    return snapshot.state === 'running' && serverUrl ? serverUrl : undefined;
+}