@datalayer/agent-runtimes 1.3.86 → 1.3.88

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

package/lib/loop/index.d.ts

@@ -70,7 +70,7 @@ export { PromptPlugin, PROMPT_PLUGIN_NAME } from './plugins/prompt';
 export { LoopEmbed, type LoopEmbedProps } from './embed/LoopEmbed';
 export { AppEmbed, AppFloating, embedAssistantCharacter, type AppEmbedProps, type AppFloatingProps, type EmbedSession, useEmbedSession, useHostBridge, } from './embed/AppEmbed';
 export { EMBED_SESSION_KEY_PREFIX, embedSessionKey, visitOfToken, } from './embed/embedSession';
-export { HOST_CONTEXT_TOOL, hostFrontendTools, hostNotAllowed, hostRefused, hostTool, hostToolsOf, hostUserRunProps, signedUser, type AppEmbedHost, type HostEvent, type HostFunction, type HostQuestion, } from './embed/hostBridge';
+export { HOST_CONTEXT_TOOL, hostFrontendTools, hostNotAllowed, hostRefused, hostTool, hostToolsOf, hostUserRunProps, fetchUserToken, signedUser, type SignedUserToken, type AppEmbedHost, type HostEvent, type HostFunction, type HostQuestion, } from './embed/hostBridge';
 export { defineDatalayerAppElement, type DatalayerAppElementOptions, } from './embed/element';
 export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, languageOf, resumeOf, type EmbedLook, type EmbedSnippetOptions, } from './embed/embedConfig';
 export { SubagentActivityPlugin, SubagentPulse, SUBAGENT_ACTIVITY_PLUGIN_NAME, } from './plugins/subagent-activity';

package/lib/loop/index.js

@@ -91,7 +91,7 @@ export { LoopEmbed } from './embed/LoopEmbed';
 export { AppEmbed, AppFloating, embedAssistantCharacter, useEmbedSession, useHostBridge, } from './embed/AppEmbed';
 export { EMBED_SESSION_KEY_PREFIX, embedSessionKey, visitOfToken, } from './embed/embedSession';
 // The host page and an embedded application, talking (LOOP D-10).
-export { HOST_CONTEXT_TOOL, hostFrontendTools, hostNotAllowed, hostRefused, hostTool, hostToolsOf, hostUserRunProps, signedUser, } from './embed/hostBridge';
+export { HOST_CONTEXT_TOOL, hostFrontendTools, hostNotAllowed, hostRefused, hostTool, hostToolsOf, hostUserRunProps, fetchUserToken, signedUser, } from './embed/hostBridge';
 export { defineDatalayerAppElement, } from './embed/element';
 export { EMBED_ATTRIBUTES, EMBED_HOST_VARIABLES, EMBED_TAG, embedLookOf, embedSnippetOf, floatingViewOf, languageOf, resumeOf, } from './embed/embedConfig';
 export { SubagentActivityPlugin, SubagentPulse, SUBAGENT_ACTIVITY_PLUGIN_NAME, } from './plugins/subagent-activity';

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

@@ -40,6 +40,13 @@ export type AgentCapacityOptions = {
     model?: string;
     /** What its modes tell a run turned in the page (LOOP P-19). */
     modeEffect?: AgentBlueprintContribution['modeEffect'];
+    /**
+     * Its own name in place of `@datalayer/loop-plugin-agent-<key>`: an
+     * application's, the name its runtime's plugin has too (LOOP F-15).
+     */
+    name?: string;
+    /** The runtime plugins it cannot work without (Reactor's cross-tier declaration). */
+    requiredBackendPlugins?: 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,9 +23,10 @@
 import { contribution, definePlugin, } from '@datalayer/reactor';
 import { LoopAgentBlueprint, LoopChatSuggestion, } from '../../core';
 export function defineAgentCapacityPlugin(options) {
-    const { key, displayName, description, specId, octicon, emoji, codemode, createPayload, suggestions, instructions, model, modeEffect, } = options;
+    const { key, displayName, description, specId, octicon, emoji, codemode, createPayload, suggestions, instructions, model, modeEffect, name, requiredBackendPlugins, } = options;
     return definePlugin({
-        name: `@datalayer/loop-plugin-agent-${key}`,
+        name: name ?? `@datalayer/loop-plugin-agent-${key}`,
+        ...(requiredBackendPlugins ? { requiredBackendPlugins } : {}),
         displayName,
         description,
         octicon: octicon ?? 'dependabot',

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

@@ -7,6 +7,7 @@ import { useReactorPlatform, useSignalValue } from '@datalayer/reactor/react';
 import { useAgentRuntimes } from '../../../hooks/useAgentRuntimes';
 import { AGENTSPECS } from '../../../specs/agents/agents';
 import { IDLE_SANDBOX_TARGET_SIGNAL } from '../../core';
+import { appLaunchOf } from './appLaunch';
 import { AGENTS_PLUGIN_NAME } from './plugin';
 import { useOptionalSandboxService } from './useSandboxService';
 /**
@@ -69,9 +70,19 @@ export function DatalayerAgentBridge() {
         // An application's spec, when the workspace runs one.
         ...(createPayload ? { createPayload } : {}),
     }), [agentSpecId, agentName, protocol, createPayload]);
+    /*
+     * The application the runtime is launched for (STUDIO R-19): its Appspec
+     * and where it runs, read from the payload its agent is created with — the
+     * Studio's Preview, the hosted page signed in. Sent with the launch, so the
+     * runtime is given the secrets its connections declare before its agent is
+     * made; without it, a connection needing a secret is refused on the
+     * runtime. A bare spec launches none.
+     */
+    const appLaunch = useMemo(() => appLaunchOf(createPayload), [createPayload]);
     const { runtime, status, error } = useAgentRuntimes({
         agentSpecId,
         agentConfig,
+        ...(appLaunch ? { appLaunch } : {}),
         variant: 'cloud-pydanticai',
         autoStart: onDatalayer && !already,
         autoCreateAgent: onDatalayer && !already,

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

@@ -0,0 +1,15 @@
+/**
+ * What an application's runtime is launched with (STUDIO R-19).
+ *
+ * Pure, so it is read without the agent hook's runtime stack.
+ *
+ * @module loop/plugins/agents/appLaunch
+ */
+import type { AppLaunch } from '../../../hooks/useAgentRuntimes';
+/**
+ * The launch of the application an agent is created with, or none.
+ *
+ * `app_spec` and `app_instance` are what `appDatalayerCreatePayload` writes;
+ * the launch sends them as `RuntimesClient.create` does in Python.
+ */
+export declare function appLaunchOf(createPayload: Record<string, unknown> | undefined): AppLaunch | undefined;

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

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The launch of the application an agent is created with, or none.
+ *
+ * `app_spec` and `app_instance` are what `appDatalayerCreatePayload` writes;
+ * the launch sends them as `RuntimesClient.create` does in Python.
+ */
+export function appLaunchOf(createPayload) {
+    const appSpec = createPayload?.app_spec;
+    if (!appSpec || typeof appSpec !== 'object') {
+        return undefined;
+    }
+    const instance = (createPayload?.app_instance ?? {});
+    const appUid = typeof instance.app_uid === 'string' && instance.app_uid
+        ? instance.app_uid
+        : undefined;
+    const deploymentUid = typeof instance.deployment_uid === 'string' && instance.deployment_uid
+        ? instance.deployment_uid
+        : undefined;
+    return {
+        appSpec: appSpec,
+        ...(appUid ? { appUid } : {}),
+        ...(deploymentUid ? { deploymentUid } : {}),
+    };
+}