@datalayer/agent-runtimes 1.3.81 → 1.3.83

package/lib/loop/embed/AppEmbed.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 /*
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
@@ -33,13 +33,18 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * host may override with the face and the mode (D-11) — around the
  * conversation and inside it, where the chat sets its theme again.
  *
+ * On the host's server with the visit's embed token, its session is kept
+ * in the host's storage and picked up again after the page reloads (D-13,
+ * `useEmbedSession`): its conversation drawn again, and gone on with.
+ *
  * @module loop/embed/AppEmbed
  */
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { Text, registerPortalRoot } from '@primer/react';
 import { useIAMStore } from '@datalayer/core/lib/state/substates/IAMState';
 import { FluentEmoji } from '@datalayer/core/lib/components/emoji';
-import { DatalayerThemeProvider, loopTheme } from '@datalayer/primer-addons';
+import { DatalayerThemeProvider, getThemeConfig, } from '@datalayer/primer-addons';
+import { generateMessageId } from '../../types/messages';
 import { ChatFloating } from '../../chat/ChatFloating';
 import { AppRenderer, } from '../apps/AppRenderer';
 import { AssistantCharactersPlugin, assistantCharacterFor, assistantCharactersFrom, } from '../plugins/assistant-characters';
@@ -47,6 +52,78 @@ import { floatingViewOf } from './embedConfig';
 import { createChatExtrasPlugin } from '../plugins/chat-extras';
 import { hostFrontendTools } from './hostBridge';
 import { embedThemeOverrides, embedThemeStyles } from './embedTheme';
+import { embedSessionKey, reattachSession, sessionGoneSentence, sessionKeeper, visitOfToken, } from './embedSession';
+/**
+ * The visit's session, kept and picked up again (LOOP D-13): on the host's
+ * server with an embed token that names its visit, the session the chat
+ * opens is kept under the application and the visit — in the host's
+ * storage unless `resume` is off, in memory always — and, when the
+ * application is drawn again (the page reloaded, or a token renewed for the
+ * visit), its conversation is asked for and drawn again. One that is gone
+ * or refused is forgotten, said once, and a new one starts. Elsewhere —
+ * on a Datalayer runtime, without a token — nothing is kept.
+ */
+export function useEmbedSession({ app, serverUrl, embedToken, resume = true, }) {
+    const visit = serverUrl && embedToken ? visitOfToken(embedToken) : undefined;
+    const key = visit ? embedSessionKey(app.id, visit) : undefined;
+    const keeper = useMemo(() => sessionKeeper({ persist: resume }), [resume]);
+    // What was found, for the token it was found with: a renewed token asks again.
+    const [found, setFound] = useState();
+    useEffect(() => {
+        if (!key || !serverUrl || !embedToken) {
+            return undefined;
+        }
+        let cancelled = false;
+        const onStarted = (uid) => {
+            keeper.keep(key, uid);
+            setFound(before => before?.said ? { ...before, said: undefined } : before);
+        };
+        const fresh = (said) => setFound({
+            token: embedToken,
+            thread: { id: generateMessageId(), messages: [], onStarted },
+            ...(said ? { said } : {}),
+        });
+        const kept = keeper.read(key);
+        if (!kept) {
+            fresh();
+            return undefined;
+        }
+        void reattachSession({ serverUrl, uid: kept, token: embedToken }).then(reattached => {
+            if (cancelled) {
+                return;
+            }
+            if (reattached.kind === 'resumed') {
+                setFound({
+                    token: embedToken,
+                    thread: { id: kept, messages: reattached.messages, onStarted },
+                });
+                return;
+            }
+            keeper.forget(key);
+            fresh(sessionGoneSentence(app.name));
+        });
+        return () => {
+            cancelled = true;
+        };
+        // The application's name is only said.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key, serverUrl, embedToken, keeper]);
+    if (!key) {
+        return { ready: true };
+    }
+    if (!found || found.token !== embedToken) {
+        return { ready: false };
+    }
+    return {
+        ready: true,
+        thread: found.thread,
+        ...(found.said ? { said: found.said } : {}),
+    };
+}
+/** What the embed says once of its session, above the conversation. */
+function SessionSaid({ said }) {
+    return said ? (_jsx(Text, { as: "p", role: "status", sx: { px: 3, py: 2, m: 0, fontSize: 1 }, children: said })) : null;
+}
 /** No plugins for the renderer: one array, so that it never reads as a change. */
 const NO_HOST_PLUGINS = [];
 /**
@@ -122,7 +199,7 @@ function Face({ emoji }) {
  * The workspace tells the chrome what the application is doing and what it
  * last said (`onPresence`, `onSaying`).
  */
-export function AppFloating({ app, view, colorMode, themeOverrides, character, serverUrl, instance, embedToken, renderer, host, }) {
+export function AppFloating({ app, view, colorMode, themeVariant, themeOverrides, character, serverUrl, instance, embedToken, renderer, host, session, }) {
     const [presence, setPresence] = useState('idle');
     const [said, setSaid] = useState({ answering: false });
     const bridge = useHostBridge(app, host);
@@ -143,14 +220,14 @@ export function AppFloating({ app, view, colorMode, themeOverrides, character, s
     return (_jsx(ChatFloating, { defaultViewMode: view, ...(character ? { assistantCharacter: character } : {}), ...(app.interface.balloon
             ? { balloonDisplay: app.interface.balloon }
             : {}), title: app.name, description: welcome, brandIcon: _jsx(Face, { emoji: app.emoji }), buttonIcon: _jsx(Face, { emoji: app.emoji }), buttonTooltip: `Talk to ${app.name}`, colorMode: colorMode, useStore: false, conversation: {
-            body: signedOut ? (_jsx(Text, { as: "p", role: "status", sx: { p: 3, m: 0, fontSize: 1 }, children: signedOutSentence(app) })) : (_jsx(AppRenderer, { app: app, target: serverUrl ? 'local' : 'datalayer', ...(serverUrl ? { serverUrl } : {}), ...(serverUrl && embedToken ? { embedToken } : {}), instance: instance, 
-                // The host's accent and face over the application's own, inside
-                // its conversation too, in the embed's mode.
-                themeOverrides: themeOverrides, colorMode: colorMode, 
-                // The window draws its face, its name and close.
-                hideChatHeader: true, 
-                // Mounted closed: the caret goes in when the window opens.
-                autoFocusPrompt: false, onPresence: onPresence, onSaying: onSaying, plugins: bridge.plugins, ...renderer })),
+            body: signedOut ? (_jsx(Text, { as: "p", role: "status", sx: { p: 3, m: 0, fontSize: 1 }, children: signedOutSentence(app) })) : session && !session.ready ? null : (_jsxs(_Fragment, { children: [_jsx(SessionSaid, { said: session?.said }), _jsx(AppRenderer, { app: app, target: serverUrl ? 'local' : 'datalayer', ...(serverUrl ? { serverUrl } : {}), ...(serverUrl && embedToken ? { embedToken } : {}), instance: instance, 
+                        // The host's accent and face over the application's own, inside
+                        // its conversation too, in the embed's mode.
+                        themeOverrides: themeOverrides, colorMode: colorMode, ...(themeVariant ? { themeVariant } : {}), 
+                        // The window draws its face, its name and close.
+                        hideChatHeader: true, 
+                        // Mounted closed: the caret goes in when the window opens.
+                        autoFocusPrompt: false, onPresence: onPresence, onSaying: onSaying, plugins: bridge.plugins, ...(session?.thread ? { thread: session.thread } : {}), ...renderer })] })),
             presence,
             saying: said.saying,
             answering: said.answering,
@@ -187,9 +264,9 @@ function useSystemMode() {
     }, [query]);
     return dark ? 'dark' : 'light';
 }
-/** The `loop` theme, with the application's (or the host's) accent and face. */
-export function EmbedThemed({ accent, colorMode, font, children, style, }) {
-    const themeStyles = useMemo(() => embedThemeStyles({ accent, font }), [accent, font]);
+/** The application's theme (`loop` unless it names one), with its (or the host's) accent and face. */
+export function EmbedThemed({ accent, colorMode, font, variant, children, style, }) {
+    const themeStyles = useMemo(() => embedThemeStyles({ accent, font, variant }), [accent, font, variant]);
     return (
     /*
      * Marked as themed above the provider, so that the provider counts
@@ -197,16 +274,21 @@ export function EmbedThemed({ accent, colorMode, font, children, style, }) {
      * alone: it would otherwise write the theme's tokens, colour and face on
      * the host's page (T-13). A wrapper of no box.
      */
-    _jsx("div", { "data-color-mode": colorMode, style: { display: 'contents' }, children: _jsx(DatalayerThemeProvider, { colorMode: colorMode, theme: loopTheme, themeStyles: themeStyles, baseStyles: style, children: children }) }));
+    _jsx("div", { "data-color-mode": colorMode, style: { display: 'contents' }, children: _jsx(DatalayerThemeProvider, { colorMode: colorMode, theme: getThemeConfig(variant).primerTheme, themeStyles: themeStyles, baseStyles: style, children: children }) }));
 }
-export function AppEmbed({ app, mode, accent, colorMode = 'auto', font, serverUrl, instance, embedToken, height = 640, ownPortal = false, plugins = NO_PLUGINS, host, }) {
+export function AppEmbed({ app, mode, accent, colorMode, font, serverUrl, instance, embedToken, height = 640, ownPortal = false, plugins = NO_PLUGINS, host, resume = true, }) {
     const bridge = useHostBridge(app, host);
+    const session = useEmbedSession({ app, serverUrl, embedToken, resume });
     const system = useSystemMode();
-    const resolvedMode = colorMode === 'auto' ? system : colorMode;
+    // The theme the application names (T-30), `loop` when none; its mode
+    // the host's, else the application's, else the visitor's system's.
+    const variant = app.interface.theme?.variant ?? 'loop';
+    const asked = colorMode ?? app.interface.theme?.mode ?? 'auto';
+    const resolvedMode = asked === 'auto' ? system : asked;
     const shownAs = mode ?? app.deployment.embedded?.mode ?? 'inline';
     const view = floatingViewOf(shownAs);
     const worn = accent ?? app.interface.accent;
-    const themeOverrides = useMemo(() => embedThemeOverrides({ accent: worn, font }), [worn, font]);
+    const themeOverrides = useMemo(() => embedThemeOverrides({ accent: worn, font, variant }), [worn, font, variant]);
     const named = app.interface.assistant;
     const assistant = useMemo(() => view === 'assistant' ? embedAssistantCharacter(app, plugins) : undefined, 
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -215,15 +297,15 @@ export function AppEmbed({ app, mode, accent, colorMode = 'auto', font, serverUr
         return (_jsx("p", { role: "status", className: "datalayer-app-said", children: assistant.problem }));
     }
     const character = assistant?.character;
-    return (_jsxs(EmbedThemed, { accent: worn, colorMode: resolvedMode, font: font, style: view
+    return (_jsxs(EmbedThemed, { accent: worn, colorMode: resolvedMode, font: font, variant: variant, style: view
             ? // Floating: nothing in the page's flow, nothing painted behind.
                 { backgroundColor: 'transparent' }
-            : { height, display: 'flex', flexDirection: 'column' }, children: [ownPortal ? _jsx(OwnPortalRoot, {}) : null, view ? (_jsx(AppFloating, { app: app, view: view, serverUrl: serverUrl, instance: instance, embedToken: embedToken, colorMode: resolvedMode, themeOverrides: themeOverrides, character: character, host: host })) : (_jsx(AppRenderer, { app: app, target: serverUrl ? 'local' : 'datalayer', ...(serverUrl ? { serverUrl } : {}), ...(serverUrl && embedToken ? { embedToken } : {}), instance: instance, 
-                // The host's accent and face over the application's own, inside
-                // its conversation too, in the embed's mode: the host's or its
-                // visitor's system's, not a Datalayer setting.
-                themeOverrides: themeOverrides, colorMode: resolvedMode, 
-                // What the page gives it, and what it tells the page (D-10).
-                plugins: bridge.plugins, onPresence: bridge.onPresence, onSaying: bridge.onSaying }))] }));
+            : { height, display: 'flex', flexDirection: 'column' }, children: [ownPortal ? _jsx(OwnPortalRoot, {}) : null, view ? (_jsx(AppFloating, { app: app, view: view, serverUrl: serverUrl, instance: instance, embedToken: embedToken, colorMode: resolvedMode, themeVariant: variant, themeOverrides: themeOverrides, character: character, host: host, session: session })) : !session.ready ? null : (_jsxs(_Fragment, { children: [_jsx(SessionSaid, { said: session.said }), _jsx(AppRenderer, { app: app, target: serverUrl ? 'local' : 'datalayer', ...(serverUrl ? { serverUrl } : {}), ...(serverUrl && embedToken ? { embedToken } : {}), instance: instance, 
+                        // The host's accent and face over the application's own, inside
+                        // its conversation too, in the embed's mode: the host's or its
+                        // visitor's system's, not a Datalayer setting.
+                        themeOverrides: themeOverrides, colorMode: resolvedMode, themeVariant: variant, 
+                        // What the page gives it, and what it tells the page (D-10).
+                        plugins: bridge.plugins, onPresence: bridge.onPresence, onSaying: bridge.onSaying, ...(session.thread ? { thread: session.thread } : {}) })] }))] }));
 }
 export default AppEmbed;

package/lib/loop/embed/LoopEmbed.js

@@ -74,6 +74,8 @@ export function LoopEmbed({ agentId = '', showHeader = false, chatHeaderActions,
         preset.presence?.welcome,
         preset.presence?.paused,
         preset.showTokenUsage,
+        // The thread a reloaded embed goes on with, by its id (D-13).
+        preset.thread?.id,
         // By its content: an application's spec written inline is a new object each render.
         JSON.stringify(preset.datalayerCreatePayload ?? null),
         JSON.stringify(preset.datalayerVisitors ?? null),

package/lib/loop/embed/element.js

@@ -38,16 +38,23 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * when it called a function of the page, beside `decision` and
  * `token-expired`.
  *
+ * On the host's server (`server`) with the visit's embed token, the
+ * session the application opens is kept in the page's `localStorage`, under
+ * the application and the visit its token names, and picked up again after
+ * the page reloads — its conversation drawn again (LOOP D-13); a token
+ * renewed for the visit redraws the application on the same session.
+ * `resume="false"` keeps nothing in the page's storage.
+ *
  * @module loop/embed/element
  */
 import { createRoot } from 'react-dom/client';
 import { StyleSheetManager } from 'styled-components';
-import { loopThemeStyles } from '@datalayer/primer-addons';
+import { getThemeConfig } from '@datalayer/primer-addons';
 import { coreStore } from '@datalayer/core/lib/state/substates/CoreState';
 import { parseAppspec } from '../apps/appspec';
 import { readAppspecYaml } from '../apps/yaml';
 import { AppEmbed, embedAssistantCharacter } from './AppEmbed';
-import { EMBED_HOST_VARIABLES, EMBED_OBSERVED_ATTRIBUTES, EMBED_TAG, EmbedAttributeError, embedLookOf, inlineHeightOf, } from './embedConfig';
+import { EMBED_HOST_VARIABLES, EMBED_OBSERVED_ATTRIBUTES, EMBED_TAG, EmbedAttributeError, embedLookOf, inlineHeightOf, resumeOf, } from './embedConfig';
 import { embedShadowCss } from './embedTheme';
 /** What the framed run page and the element say to each other. */
 export const EMBED_MESSAGES = {
@@ -249,7 +256,7 @@ export function defineDatalayerAppElement(options = {}) {
                 return;
             }
             // How it looks is drawn again; what it is, read again.
-            if (['mode', 'accent', 'theme', 'font', 'height'].includes(name)) {
+            if (['mode', 'accent', 'theme', 'font', 'height', 'resume'].includes(name)) {
                 this.draw();
                 return;
             }
@@ -394,8 +401,10 @@ export function defineDatalayerAppElement(options = {}) {
                 return;
             }
             let look;
+            let resume;
             try {
                 look = embedLookOf(this.inputs(), source.app);
+                resume = resumeOf(this.getAttribute('resume'));
             }
             catch (error) {
                 this.say(error.message);
@@ -411,13 +420,18 @@ export function defineDatalayerAppElement(options = {}) {
                 }
             }
             this.setAttribute('data-embed-mode', look.mode);
-            const shadow = this.skeleton(loopThemeStyles.css);
+            // The theme's own stylesheet: `loop`'s, or the one the application
+            // names (T-30).
+            const shadow = this.skeleton(getThemeConfig(look.variant).themeStyles.css);
             const mount = document.createElement('div');
             mount.className = 'datalayer-app-root';
             shadow.appendChild(mount);
             this.root = createRoot(mount);
             const server = this.getAttribute('server') || undefined;
-            this.root.render(_jsx(StyleSheetManager, { target: shadow, children: _jsx(AppEmbed, { app: source.app, mode: look.mode, accent: look.accent, colorMode: look.colorMode, font: look.font, serverUrl: server, ...(server && this.token ? { embedToken: this.token } : {}), height: inlineHeightOf(this.getAttribute('height')), ownPortal: true, host: this.host }) }));
+            this.root.render(_jsx(StyleSheetManager, { target: shadow, children: _jsx(AppEmbed, { app: source.app, mode: look.mode, accent: look.accent, colorMode: look.colorMode, font: look.font, serverUrl: server, ...(server && this.token ? { embedToken: this.token } : {}), height: inlineHeightOf(this.getAttribute('height')), ownPortal: true, host: this.host, 
+                    // The visit's session kept in the page's storage, and picked
+                    // up again after a reload, unless the host says not (D-13).
+                    resume: resume }) }));
         }
         onMessage(event) {
             if (!this.frame || event.source !== this.frame.contentWindow) {

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

@@ -11,7 +11,7 @@
  *
  * @module loop/embed/embedConfig
  */
-import type { AppAccent, AppEmbedMode, AppSpec } from '../../types/agentspecs';
+import type { AppAccent, AppEmbedMode, AppSpec, AppThemeVariant } from '../../types/agentspecs';
 /** The element's name: the one a host writes. */
 export declare const EMBED_TAG = "datalayer-app";
 /** Where the script is served on a Datalayer origin; the stylesheet beside it. */
@@ -33,6 +33,7 @@ export declare const EMBED_ATTRIBUTES: {
     readonly server: "An agent-runtimes server the application’s agent runs on; a Datalayer runtime by default.";
     readonly api: "Datalayer’s API, where an application is read with its token; the platform’s by default.";
     readonly height: "The height of an inline application, in pixels; 640 by default.";
+    readonly resume: "true or false: whether a visit’s conversation is picked up again after the page reloads, kept in the page’s storage; true by default.";
 };
 export type EmbedAttribute = keyof typeof EMBED_ATTRIBUTES;
 /** Every attribute the element watches. */
@@ -86,6 +87,8 @@ export type EmbedLook = {
     colorMode: EmbedColorMode;
     /** The host's face; empty for the theme's own. */
     font: string;
+    /** The theme the application names (T-30); `loop` when it names none. */
+    variant: AppThemeVariant;
 };
 /**
  * What the element shows and how, from what the host wrote and what the
@@ -94,6 +97,12 @@ export type EmbedLook = {
  * sentence (`EmbedAttributeError`), never quietly replaced.
  */
 export declare function embedLookOf(inputs: EmbedInputs, app?: Pick<AppSpec, 'interface' | 'deployment'>): EmbedLook;
+/**
+ * Whether a visit's conversation is picked up again after a reload (LOOP
+ * D-13): on unless the host writes `resume="false"`. Anything else is
+ * refused in a sentence.
+ */
+export declare function resumeOf(value: string | null | undefined): boolean;
 /** The height of an inline application, in pixels. */
 export declare function inlineHeightOf(value: string | null | undefined): number;
 /** What a snippet says beside the application's id. */

package/lib/loop/embed/embedConfig.js

@@ -24,6 +24,7 @@ export const EMBED_ATTRIBUTES = {
     server: 'An agent-runtimes server the application’s agent runs on; a Datalayer runtime by default.',
     api: 'Datalayer’s API, where an application is read with its token; the platform’s by default.',
     height: 'The height of an inline application, in pixels; 640 by default.',
+    resume: 'true or false: whether a visit’s conversation is picked up again after the page reloads, kept in the page’s storage; true by default.',
 };
 /** Every attribute the element watches. */
 export const EMBED_OBSERVED_ATTRIBUTES = Object.keys(EMBED_ATTRIBUTES);
@@ -105,9 +106,19 @@ export function embedLookOf(inputs, app) {
         'green';
     const colorMode = oneOf(attributes.theme, EMBED_COLOR_MODES, 'a theme') ??
         oneOf(variables.theme, EMBED_COLOR_MODES, 'a theme') ??
+        app?.interface?.theme?.mode ??
         'auto';
     const font = checkedFont(attributes.font) || checkedFont(variables.font);
-    return { mode, accent, colorMode, font };
+    const variant = app?.interface?.theme?.variant ?? 'loop';
+    return { mode, accent, colorMode, font, variant };
+}
+/**
+ * Whether a visit's conversation is picked up again after a reload (LOOP
+ * D-13): on unless the host writes `resume="false"`. Anything else is
+ * refused in a sentence.
+ */
+export function resumeOf(value) {
+    return (oneOf(value, ['true', 'false'], 'a value of resume') !== 'false');
 }
 /** The height of an inline application, in pixels. */
 export function inlineHeightOf(value) {

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

@@ -0,0 +1,79 @@
+/**
+ * An embedded application's conversation, picked up again after the host's
+ * page reloads (LOOP D-13).
+ *
+ * The session an embed opened is kept by its uid in the host page's own
+ * storage, under the application and the visit its embed token names —
+ * the host's server issues the reloaded page a token for the same visit.
+ * After the reload, the session is asked for its conversation on the
+ * agent-runtimes server that holds it, with that token, and the chat draws
+ * it again and goes on with it. A session that is gone, or refused, is
+ * forgotten and said once; a new one starts.
+ *
+ * Kept in memory as well, for as long as the page lives: a token renewed
+ * for the visit redraws the application, which goes on with its session
+ * even when the host keeps nothing (`resume="false"`).
+ *
+ * Pure but for the storage and the request, each given or guarded: the page
+ * works without storage.
+ *
+ * @module loop/embed/embedSession
+ */
+import type { ChatMessage } from '../../types/messages';
+/** Where a visit's session is kept in the host's storage: `<prefix>:<app>:<visit>`. */
+export declare const EMBED_SESSION_KEY_PREFIX = "datalayer-app:session";
+/**
+ * The visit an embed token was issued for: its `visit` claim, read without
+ * checking the signature — the runtime checks the token; the page only
+ * needs the name to keep the session under.
+ */
+export declare function visitOfToken(token: string | undefined): string | undefined;
+/** The key a visit's session is kept under. */
+export declare function embedSessionKey(app: string, visit: string): string;
+/** What keeps a visit's session uid. */
+export type SessionKeeper = {
+    read: (key: string) => string | undefined;
+    keep: (key: string, uid: string) => void;
+    forget: (key: string) => void;
+};
+/**
+ * The keeper of a visit's session: in memory, and — unless the host opted
+ * out — in its storage too, read first. Every access to the storage is
+ * guarded: a page whose storage is blocked, full or absent keeps the
+ * session in memory and resumes nothing after a reload.
+ */
+export declare function sessionKeeper({ persist, storage, }: {
+    persist: boolean;
+    storage?: () => Storage | undefined;
+}): SessionKeeper;
+/** Forget what this page holds in memory (a test). */
+export declare function forgetSessionsInMemory(): void;
+/**
+ * A session's conversation as the chat draws it, from the AG-UI messages
+ * the runtime says (`GET …/sessions/{uid}/messages`): what was said and
+ * answered, in words. A page an answer drew is not drawn again here.
+ */
+export declare function messagesOfThread(messages: unknown): ChatMessage[];
+/** What asking for a kept session found. */
+export type Reattached = {
+    kind: 'resumed';
+    uid: string;
+    messages: ChatMessage[];
+} | {
+    kind: 'gone';
+    uid: string;
+};
+/**
+ * Ask the server that runs the application for a session's conversation,
+ * with the visit's token. Anything but an answer — a session the runtime
+ * let go, another visit's, a token refused, a server out of reach — is
+ * `gone`: a new session starts.
+ */
+export declare function reattachSession({ serverUrl, uid, token, fetcher, }: {
+    serverUrl: string;
+    uid: string;
+    token: string;
+    fetcher?: typeof fetch;
+}): Promise<Reattached>;
+/** What the page says, once, when the conversation it kept is gone. */
+export declare const sessionGoneSentence: (name: string) => string;

package/lib/loop/embed/embedSession.js

@@ -0,0 +1,136 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Where a visit's session is kept in the host's storage: `<prefix>:<app>:<visit>`. */
+export const EMBED_SESSION_KEY_PREFIX = 'datalayer-app:session';
+/**
+ * The visit an embed token was issued for: its `visit` claim, read without
+ * checking the signature — the runtime checks the token; the page only
+ * needs the name to keep the session under.
+ */
+export function visitOfToken(token) {
+    const payload = token?.split('.')[1];
+    if (!payload) {
+        return undefined;
+    }
+    try {
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+        const claims = JSON.parse(atob(padded));
+        return typeof claims.visit === 'string' && claims.visit
+            ? claims.visit
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The key a visit's session is kept under. */
+export function embedSessionKey(app, visit) {
+    return `${EMBED_SESSION_KEY_PREFIX}:${app}:${visit}`;
+}
+/** The sessions of this page, while it lives. */
+const IN_MEMORY = new Map();
+/** The host's `localStorage`, when there is one the page may use. */
+function hostStorage() {
+    try {
+        return typeof window !== 'undefined' ? window.localStorage : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The keeper of a visit's session: in memory, and — unless the host opted
+ * out — in its storage too, read first. Every access to the storage is
+ * guarded: a page whose storage is blocked, full or absent keeps the
+ * session in memory and resumes nothing after a reload.
+ */
+export function sessionKeeper({ persist, storage = hostStorage, }) {
+    return {
+        read: key => {
+            if (persist) {
+                try {
+                    const kept = storage()?.getItem(key);
+                    if (kept) {
+                        return kept;
+                    }
+                }
+                catch {
+                    // No storage: what the page holds in memory.
+                }
+            }
+            return IN_MEMORY.get(key);
+        },
+        keep: (key, uid) => {
+            IN_MEMORY.set(key, uid);
+            if (persist) {
+                try {
+                    storage()?.setItem(key, uid);
+                }
+                catch {
+                    // Kept in memory only.
+                }
+            }
+        },
+        forget: key => {
+            IN_MEMORY.delete(key);
+            try {
+                storage()?.removeItem(key);
+            }
+            catch {
+                // Nothing kept there to forget.
+            }
+        },
+    };
+}
+/** Forget what this page holds in memory (a test). */
+export function forgetSessionsInMemory() {
+    IN_MEMORY.clear();
+}
+/**
+ * A session's conversation as the chat draws it, from the AG-UI messages
+ * the runtime says (`GET …/sessions/{uid}/messages`): what was said and
+ * answered, in words. A page an answer drew is not drawn again here.
+ */
+export function messagesOfThread(messages) {
+    if (!Array.isArray(messages)) {
+        return [];
+    }
+    const drawn = [];
+    for (const message of messages) {
+        if (!message || typeof message !== 'object') {
+            continue;
+        }
+        const { id, role, content } = message;
+        if ((role === 'user' || role === 'assistant') &&
+            typeof id === 'string' &&
+            typeof content === 'string' &&
+            content.trim()) {
+            drawn.push({ id, role, content, createdAt: new Date() });
+        }
+    }
+    return drawn;
+}
+/**
+ * Ask the server that runs the application for a session's conversation,
+ * with the visit's token. Anything but an answer — a session the runtime
+ * let go, another visit's, a token refused, a server out of reach — is
+ * `gone`: a new session starts.
+ */
+export async function reattachSession({ serverUrl, uid, token, fetcher = fetch, }) {
+    try {
+        const response = await fetcher(`${serverUrl.replace(/\/+$/, '')}/api/v1/apps/sessions/${encodeURIComponent(uid)}/messages`, { headers: { Authorization: `Bearer ${token}` } });
+        if (!response.ok) {
+            return { kind: 'gone', uid };
+        }
+        const body = (await response.json());
+        return { kind: 'resumed', uid, messages: messagesOfThread(body.messages) };
+    }
+    catch {
+        return { kind: 'gone', uid };
+    }
+}
+/** What the page says, once, when the conversation it kept is gone. */
+export const sessionGoneSentence = (name) => `Your earlier conversation with ${name} has ended, so this is a new one.`;

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

@@ -1,24 +1,27 @@
 import { type ThemeStyles } from '@datalayer/primer-addons';
-import type { AppAccent } from '../../types/agentspecs';
+import type { AppAccent, AppThemeVariant } from '../../types/agentspecs';
 import type { ThemeOverrides } from '../../types/chat';
 /**
- * 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.
+ * The theme as the embed wears it — `loop`, or the one the application
+ * names (T-30) — with the application's accent over `loop` in both modes
+ * (T-05), and the host's face when it named one.
  */
-export declare function embedThemeStyles({ accent, font, }: {
+export declare function embedThemeStyles({ accent, font, variant, }: {
     accent: AppAccent;
     font?: string;
+    variant?: AppThemeVariant;
 }): ThemeStyles;
 /**
  * The same accent and face laid over the conversation's own theme (T-05,
- * D-11): the chat sets the `loop` theme again inside it, which would put the
- * theme's mint and face back over what the embed set around it. The
- * accent's properties in each mode, and, when the host named a face, every
- * property of the theme that names its own.
+ * D-11): the chat sets its theme again inside it, which would put the
+ * theme's colours and face back over what the embed set around it. The
+ * accent's properties in each mode (over `loop` only), and, when the host
+ * named a face, every property of the theme that names its own.
  */
-export declare function embedThemeOverrides({ accent, font, }: {
+export declare function embedThemeOverrides({ accent, font, variant, }: {
     accent: AppAccent;
     font?: string;
+    variant?: AppThemeVariant;
 }): ThemeOverrides;
 /**
  * The element's own stylesheet, written into its shadow root.