@datalayer/agent-runtimes 1.3.87 → 1.3.89

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;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * A thread opened from a person's history, to go on with it (LOOP P-24).
+ *
+ * A thread is a session of an application: its uid is the conversation's
+ * AG-UI thread. Opened again, its conversation is read from the runtime the
+ * chat runs on — the session's messages while the runtime holds it
+ * (`GET …/sessions/{uid}/messages`, D-13), else the session resumed from its
+ * record (`POST …/sessions/{uid}/resume` with the agent, R-04), whose
+ * stream's `MESSAGES_SNAPSHOT` says what it holds — and the chat draws it
+ * and goes on with it on the same thread.
+ *
+ * Pure: the network is the `fetch` it is handed.
+ *
+ * @module loop/apps/threads
+ */
+import type { ChatMessage } from '../../types/messages';
+/** What opening a thread says, in a person's words. */
+export declare const THREAD_WORDS: {
+    readonly opening: "Opening your conversation…";
+    readonly notOpened: (detail: string) => string;
+};
+/** The AG-UI messages a session-API stream's `MESSAGES_SNAPSHOT` carries, if one does. */
+export declare function snapshotOfStream(text: string): unknown[] | undefined;
+/**
+ * A thread's conversation, read from the runtime its application runs on:
+ * held there, or resumed from its record. Throws the runtime's sentence when
+ * neither answers.
+ */
+export declare function openThread({ agentBaseUrl, agentId, uid, token, fetcher, }: {
+    agentBaseUrl: string;
+    agentId: string;
+    uid: string;
+    token?: string | null;
+    fetcher?: typeof fetch;
+}): Promise<ChatMessage[]>;

package/lib/loop/apps/threads.js

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { messagesOfThread } from '../embed/embedSession';
+/** What opening a thread says, in a person's words. */
+export const THREAD_WORDS = {
+    opening: 'Opening your conversation…',
+    notOpened: (detail) => `Your conversation could not be opened, so this is a new one: ${detail}`,
+};
+/** The AG-UI messages a session-API stream's `MESSAGES_SNAPSHOT` carries, if one does. */
+export function snapshotOfStream(text) {
+    let found;
+    for (const block of text.split(/\r?\n\r?\n/)) {
+        const data = block
+            .split(/\r?\n/)
+            .filter(line => line.startsWith('data:'))
+            .map(line => line.slice('data:'.length).trim())
+            .join('');
+        if (!data) {
+            continue;
+        }
+        try {
+            const event = JSON.parse(data);
+            if (event.type === 'MESSAGES_SNAPSHOT' && Array.isArray(event.messages)) {
+                found = event.messages;
+            }
+        }
+        catch {
+            // Not an event: skipped.
+        }
+    }
+    return found;
+}
+async function detailOf(response) {
+    try {
+        const body = (await response.json());
+        if (typeof body.detail === 'string' && body.detail) {
+            return body.detail;
+        }
+    }
+    catch {
+        // No sentence: the status says it.
+    }
+    return `${response.status}`;
+}
+/**
+ * A thread's conversation, read from the runtime its application runs on:
+ * held there, or resumed from its record. Throws the runtime's sentence when
+ * neither answers.
+ */
+export async function openThread({ agentBaseUrl, agentId, uid, token, fetcher = fetch, }) {
+    const base = `${agentBaseUrl.replace(/\/+$/, '')}/api/v1/apps/sessions/${encodeURIComponent(uid)}`;
+    const authorization = token
+        ? { Authorization: `Bearer ${token}` }
+        : {};
+    const held = await fetcher(`${base}/messages`, { headers: authorization });
+    if (held.ok) {
+        const body = (await held.json());
+        return messagesOfThread(body.messages);
+    }
+    if (held.status !== 404) {
+        throw new Error(await detailOf(held));
+    }
+    // Not held here: resumed from its record, under the same uid.
+    const resumed = await fetcher(`${base}/resume`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...authorization },
+        body: JSON.stringify({ agent: agentId }),
+    });
+    if (!resumed.ok) {
+        throw new Error(await detailOf(resumed));
+    }
+    const snapshot = snapshotOfStream(await resumed.text());
+    if (!snapshot) {
+        throw new Error(`The runtime said nothing of session ${uid}.`);
+    }
+    return messagesOfThread(snapshot);
+}

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

@@ -18,7 +18,7 @@
  * @module loop/embed/LoopEmbed
  */
 import { type ReactNode } from 'react';
-import type { PluginRef } from '@datalayer/reactor';
+import type { PlatformInput } from '@datalayer/reactor';
 import { type LoopPresetOptions } from '../presets';
 export type LoopEmbedProps = LoopPresetOptions & {
     /** Which agent the conversation is with. */
@@ -59,9 +59,10 @@ export type LoopEmbedProps = LoopPresetOptions & {
      * How a page adds something to Loop rather than around it — a button in the
      * window's title bar, a panel of its own, a command. Without this a host
      * would have to rebuild the plugin list to add one thing to it, which is the
-     * assembly this component exists to save.
+     * assembly this component exists to save. An extension groups some of
+     * them, as an application's own plugins are (`AppRenderer`, LOOP F-15).
      */
-    plugins?: PluginRef[];
+    plugins?: PlatformInput[];
 };
 export declare function LoopEmbed({ agentId, showHeader, chatHeaderActions, headerActions, headerContainer, frameTitle, frameHeight, sidebarRail, plugins, ...preset }: LoopEmbedProps): React.JSX.Element;
 export default LoopEmbed;

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

@@ -124,3 +124,30 @@ export declare function hostFrontendTools(app: Pick<AppSpec, 'connections' | 'ru
  * the page says.
  */
 export declare function hostUserRunProps(app: Pick<AppSpec, 'deployment'>, host: () => AppEmbedHost): RunPropsContribution | undefined;
+/** A user token ai-agents signed, and when it ends (seconds since the epoch). */
+export type SignedUserToken = {
+    token: string;
+    exp: number;
+};
+/**
+ * Asks ai-agents to sign the person signed in to Datalayer as a deployment's
+ * user (LOOP D-21; STUDIO A-18 to A-20), with their own token: what a
+ * surface that has no host server holding the deployment's secret — the
+ * VS Code extension, Jupyter AI Agents, Datalayer Desktop — sends as
+ * `forwardedProps.loop.user_token` with the runs of an application that
+ * says `user: signed`. HS256 with the deployment's secret, `sub` the
+ * person's uid, `name` theirs, fifteen minutes; refused (`403`) for an
+ * application's principal or a narrowed token, and for a person the
+ * deployment does not let in. Those surfaces share no code, so they copy
+ * it.
+ *
+ * @param aiAgentsUrl - The ai-agents service's base URL.
+ * @param deploymentUid - The deployment talked to.
+ * @param token - The person's Datalayer token.
+ * @param fetcher - What asks; `fetch` unless given.
+ *
+ * @returns The user token and when it ends.
+ *
+ * @throws With ai-agents' sentence when it refuses.
+ */
+export declare function fetchUserToken(aiAgentsUrl: string, deploymentUid: string, token: string, fetcher?: (url: string, init: RequestInit) => Promise<Response>): Promise<SignedUserToken>;

package/lib/loop/embed/hostBridge.js

@@ -122,3 +122,50 @@ export function hostUserRunProps(app, host) {
         },
     };
 }
+/**
+ * Asks ai-agents to sign the person signed in to Datalayer as a deployment's
+ * user (LOOP D-21; STUDIO A-18 to A-20), with their own token: what a
+ * surface that has no host server holding the deployment's secret — the
+ * VS Code extension, Jupyter AI Agents, Datalayer Desktop — sends as
+ * `forwardedProps.loop.user_token` with the runs of an application that
+ * says `user: signed`. HS256 with the deployment's secret, `sub` the
+ * person's uid, `name` theirs, fifteen minutes; refused (`403`) for an
+ * application's principal or a narrowed token, and for a person the
+ * deployment does not let in. Those surfaces share no code, so they copy
+ * it.
+ *
+ * @param aiAgentsUrl - The ai-agents service's base URL.
+ * @param deploymentUid - The deployment talked to.
+ * @param token - The person's Datalayer token.
+ * @param fetcher - What asks; `fetch` unless given.
+ *
+ * @returns The user token and when it ends.
+ *
+ * @throws With ai-agents' sentence when it refuses.
+ */
+export async function fetchUserToken(aiAgentsUrl, deploymentUid, token, fetcher = fetch) {
+    const url = `${aiAgentsUrl.replace(/\/+$/, '')}/api/ai-agents/v1/apps/deployments/${encodeURIComponent(deploymentUid)}/user-token`;
+    const response = await fetcher(url, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    let body = {};
+    try {
+        const read = await response.json();
+        body =
+            read && typeof read === 'object' ? read : {};
+    }
+    catch {
+        // The status says it.
+    }
+    if (!response.ok) {
+        const detail = typeof body.detail === 'string' ? body.detail : '';
+        throw new Error(detail || `ai-agents refused to sign you (${response.status}).`);
+    }
+    const signed = typeof body.user_token === 'string' ? body.user_token : '';
+    const exp = Number(body.exp);
+    if (!signed || !Number.isFinite(exp)) {
+        throw new Error('ai-agents answered no user token.');
+    }
+    return { token: signed, exp };
+}