@datalayer/agent-runtimes 1.5.65 → 1.5.70

package/lib/apps/apps/records.d.ts

@@ -1,3 +1,15 @@
+/**
+ * The record of an application (R-07), as ai-agents keeps it: what it
+ * did, session by session, written by the runtime it ran on — read here for
+ * its activity feed (R-01b, R-15): the sessions, newest first, and what each
+ * one did, step by step.
+ *
+ * Pure but for `fetch`: no React.
+ *
+ * @module apps/apps/records
+ */
+import { type SessionRow } from '../../portable/activity';
+export { sessionAgentSaid, sessionLineageSaid, sessionStateSaid, type SessionRow, } from '../../portable/activity';
 /** What a record entry is. */
 export type RecordKind = 'session' | 'tool_call' | 'decision' | 'check' | 'approval' | 'output' | 'feedback'
 /** A turn of a conversation: what was asked, what it answered. */
@@ -35,10 +47,15 @@ export declare function entrySaid(entry: RecordEntry): string;
 /** A session in a sentence: how many calls, what stopped it, how it ended. */
 export declare function sessionSentence(entries: readonly RecordEntry[]): string;
 /**
- * The sessions of an application, newest first: their opening entries. Real
- * use only — the sessions its tests ran are read apart (R-07) — unless
- * `tests` says otherwise: `true` for the tests only, `null` for both.
+ * The sessions of an application, newest first, each as the record lists
+ * it (`sessionRowOf`: state, agent, title, lineage, turns). Real use only —
+ * the sessions its tests ran are read apart (R-07) — unless `tests` says
+ * otherwise: `true` for the tests only, `null` for both. The first page;
+ * `hasMore` says whether there is a next.
  */
-export declare function listSessions(context: RecordsContext, appUid: string, limit?: number, tests?: boolean | null): Promise<RecordEntry[]>;
+export declare function listSessions(context: RecordsContext, appUid: string, limit?: number, tests?: boolean | null): Promise<{
+    sessions: SessionRow[];
+    hasMore: boolean;
+}>;
 /** What one session did, in order: a run's start is a mark, not a step (R-15). */
 export declare function readSession(context: RecordsContext, sessionUid: string): Promise<RecordEntry[]>;

package/lib/apps/apps/records.js

@@ -12,7 +12,9 @@
  *
  * @module apps/apps/records
  */
+import { sessionPageOf } from '../../portable/activity';
 import { RUN_END_WORDS } from '../../portable/records';
+export { sessionAgentSaid, sessionLineageSaid, sessionStateSaid, } from '../../portable/activity';
 /** Each kind in a word, as the feed labels it. */
 export const RECORD_KIND_WORDS = {
     session: 'Session',
@@ -88,15 +90,15 @@ async function read(context, path, failure) {
     return body;
 }
 /**
- * The sessions of an application, newest first: their opening entries. Real
- * use only — the sessions its tests ran are read apart (R-07) — unless
- * `tests` says otherwise: `true` for the tests only, `null` for both.
+ * The sessions of an application, newest first, each as the record lists
+ * it (`sessionRowOf`: state, agent, title, lineage, turns). Real use only —
+ * the sessions its tests ran are read apart (R-07) — unless `tests` says
+ * otherwise: `true` for the tests only, `null` for both. The first page;
+ * `hasMore` says whether there is a next.
  */
 export async function listSessions(context, appUid, limit = 20, tests = false) {
     const body = await read(context, `/sessions?app_uid=${encodeURIComponent(appUid)}&limit=${limit}${tests === null ? '' : `&tests=${tests}`}`, 'The sessions could not be read');
-    return Array.isArray(body.sessions)
-        ? body.sessions.map(entryOf)
-        : [];
+    return sessionPageOf(body);
 }
 /** What one session did, in order: a run's start is a mark, not a step (R-15). */
 export async function readSession(context, sessionUid) {

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

@@ -10,7 +10,9 @@
  * and goes on with it on the same thread.
  *
  * Opening it is `openThread` (`portable/thread`), as every client opens one;
- * here is what a deployment's chat decides of the thread it opens on.
+ * here is what a deployment's chat decides of the thread it opens on — and
+ * the web's deep link to a session, `?session=<uid>` on the chat's URL
+ * (`sessionOfSearch`).
  *
  * @module apps/apps/threads
  */
@@ -34,3 +36,11 @@ export declare function deploymentOfPayload(createPayload: Record<string, unknow
  * no deployment, keeps what it was given.
  */
 export declare function threadOfVisit(given: ResumedThread | undefined, deploymentUid: string, id: string): ResumedThread | undefined;
+/**
+ * The session a chat's URL names, `?session=<uid>` (the web's deep link):
+ * the chat opens that session as its thread when its host gave none. A
+ * uid is 8 to 128 letters, digits, hyphens or underscores (`SESSION_UID`);
+ * anything else is no session and refused in a sentence rather than sent
+ * to the runtime.
+ */
+export declare function sessionOfSearch(search: string): string;

package/lib/apps/apps/threads.js

@@ -33,3 +33,20 @@ export function threadOfVisit(given, deploymentUid, id) {
     }
     return { id, messages: [] };
 }
+/**
+ * The session a chat's URL names, `?session=<uid>` (the web's deep link):
+ * the chat opens that session as its thread when its host gave none. A
+ * uid is 8 to 128 letters, digits, hyphens or underscores (`SESSION_UID`);
+ * anything else is no session and refused in a sentence rather than sent
+ * to the runtime.
+ */
+export function sessionOfSearch(search) {
+    const uid = (new URLSearchParams(search).get('session') ?? '').trim();
+    if (!uid) {
+        return '';
+    }
+    if (!/^[A-Za-z0-9_-]{8,128}$/.test(uid)) {
+        throw new Error(`?session=${uid} names no session: a session uid is 8 to 128 letters, digits, hyphens or underscores.`);
+    }
+    return uid;
+}

package/lib/apps/core/index.d.ts

@@ -10,6 +10,7 @@ import type { AssistantCharacterData } from '../../chat/assistant/formats/types'
 import type { PresenceState } from '../../chat/presence/presenceStatus';
 import type { ChatWords } from '../../chat/words';
 import type { ChatViewMode } from '../../types/chat';
+import type { SessionRow } from '../../portable/activity';
 /** Lifecycle of the sandbox a workspace is attached to. */
 export type SandboxState = 'idle' | 'starting' | 'running' | 'stopping' | 'error';
 /** What the workspace knows about the sandbox behind it. */
@@ -532,6 +533,76 @@ export type ChatHeaderContribution = {
     Component: ComponentType<LoopChatHeaderProps>;
 };
 export declare const LoopChatHeader: import("@datalayer/reactor").ContributionPoint<ChatHeaderContribution>;
+/**
+ * A session of an application, as the runtime's session API describes it
+ * (`GET /api/v1/apps/sessions/{uid}`) and as the record lists it: one
+ * shape, `SessionRow` (`portable/activity`), read through `sessionRowOf` —
+ * what a thread's menu entry reads to say whether it applies, and what the
+ * thread's header says of the session (its state, where it comes from).
+ */
+export type SessionFacts = SessionRow;
+/** What a menu entry may do when run: the session API, and the page's ways. */
+export type SessionActionContext = {
+    /** The runtime's session API for this application (`appSessionsClient`). */
+    client: import('../../portable/sessions').AppSessionsClient;
+    /** Open another session as a thread, when the page can. */
+    openThread?: (uid: string) => void;
+    /** Hand the person a file to save, when the page can. */
+    download?: (name: string, text: string, mediaType: string) => void;
+    /**
+     * Ask the person to pick one of several — an agent to switch to — and
+     * say what the pick does; `undefined` when they decline. A page with no
+     * picker leaves it out, and the entry says so.
+     */
+    choose?: (question: {
+        title: string;
+        options: {
+            id: string;
+            label: string;
+            description?: string;
+        }[];
+        /** What the pick does, shown before it is sent. */
+        says?: (id: string) => Promise<string>;
+    }) => Promise<string | undefined>;
+    /**
+     * Ask the person for a file — a session file to import — and give its
+     * text; `undefined` when they decline. A page with no picker leaves it
+     * out, and the entry says so.
+     */
+    pickFile?: (accept: string) => Promise<string | undefined>;
+    /** Say a sentence to the person: a refusal, what was done. */
+    say: (sentence: string) => void;
+    /** The turn a *Clone from here* was pressed on, when it was; else the last. */
+    atTurn?: number;
+};
+/** Where an entry is offered: the thread's `⋯` menu, each turn's row, or both. */
+export type SessionActionPlacement = 'thread' | 'turn' | 'both';
+/**
+ * A menu entry on a thread (the thread's `⋯`): *Switch agent…*, *Clone from
+ * here*, *Export*, *Resume* are the chat plugin's; a host adds its own
+ * (*Open in the Studio*) by contributing here. `when` hides an entry that
+ * does not apply to the session as it stands — no *Resume* on an open
+ * thread, no *Switch agent* while a turn runs.
+ */
+export type SessionActionContribution = {
+    /** Stable id, for the registry and the graph. */
+    id: string;
+    label: string;
+    /** Whether the entry applies to this session now. */
+    when: (session: SessionFacts) => boolean;
+    run: (session: SessionFacts, context: SessionActionContext) => Promise<void> | void;
+    /** Drawn in this order, lowest first. */
+    order?: number;
+    /** Set apart from what precedes it. */
+    divider?: boolean;
+    /** Where it is offered; the thread's menu when unsaid. */
+    placement?: SessionActionPlacement;
+};
+export declare const LoopSessionAction: import("@datalayer/reactor").ContributionPoint<SessionActionContribution>;
+/** The entries that apply to a session now, for one placement, in their order. */
+export declare function sessionActionsFor(entries: readonly {
+    value: SessionActionContribution;
+}[], session: SessionFacts | undefined, placement?: 'thread' | 'turn'): SessionActionContribution[];
 /**
  * The agent a capacity plugin wants the workspace to run.
  *

package/lib/apps/core/index.js

@@ -166,6 +166,28 @@ export const LoopChatSurface = LoopEditorView;
 export const LoopFrontendTool = defineContributionPoint('loop.frontendTool');
 export const LoopChatComposer = defineContributionPoint('loop.chat.composer');
 export const LoopChatHeader = defineContributionPoint('loop.chat.header');
+export const LoopSessionAction = defineContributionPoint('loop.session.action');
+/** The entries that apply to a session now, for one placement, in their order. */
+export function sessionActionsFor(entries, session, placement = 'thread') {
+    if (!session) {
+        return [];
+    }
+    return entries
+        .map(entry => entry.value)
+        .filter(entry => {
+        const offered = entry.placement ?? 'thread';
+        return offered === 'both' || offered === placement;
+    })
+        .filter(entry => {
+        try {
+            return entry.when(session);
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+}
 export const LoopAgentBlueprint = defineContributionPoint('loop.agent.blueprint');
 export const LoopChatSuggestion = defineContributionPoint('loop.chat.suggestion');
 export const LoopAssistantCharacter = defineContributionPoint('loop.assistant.character');

package/lib/apps/plugins/app-activity/AppActivity.js

@@ -7,7 +7,7 @@ import { useContributions, useSignalValue } from '@datalayer/reactor/react';
 import { useCoreStore } from '@datalayer/core/lib/state';
 import { useIAMStore } from '@datalayer/core/lib/state/substates/IAMState';
 import { LoopChatTurn } from '../../core';
-import { RECORD_KIND_WORDS, entrySaid, listSessions, readSession, sessionSentence, } from '../../apps/records';
+import { RECORD_KIND_WORDS, entrySaid, listSessions, readSession, sessionAgentSaid, sessionLineageSaid, sessionSentence, sessionStateSaid, } from '../../apps/records';
 /** What the feed says. */
 export const APP_ACTIVITY_WORDS = {
     title: 'Activity',
@@ -39,8 +39,14 @@ function useRead(load, key, when = true) {
 }
 function Session({ context, session, }) {
     const [open, setOpen] = useState(false);
-    const entries = useRead(() => readSession(context, session.sessionUid), `${session.sessionUid}:${context.token}`, open);
-    return (_jsxs(Box, { as: "details", onToggle: (event) => setOpen(event.currentTarget.open), borderTop: "1px solid", borderColor: "border.muted", py: 2, children: [_jsxs(Box, { as: "summary", cursor: "pointer", fontSize: 1, children: [session.createdAt ? (_jsx(RelativeTime, { datetime: session.createdAt })) : ('A session'), session.version ? ` · version ${session.version}` : '', entries.value ? ` · ${sessionSentence(entries.value)}` : ''] }), !open ? null : entries.loading ? (_jsx(Spinner, { size: "small" })) : entries.error ? (_jsx(Text, { role: "alert", sx: { fontSize: 1 }, children: entries.error })) : (_jsx(Box, { as: "ol", pl: 3, mt: 2, mb: 0, fontSize: 1, children: (entries.value ?? []).map(entry => (_jsxs(Box, { as: "li", mb: 1, children: [_jsx(Label, { sx: { mr: 2 }, children: RECORD_KIND_WORDS[entry.kind] ?? entry.kind }), entrySaid(entry)] }, entry.uid))) }))] }));
+    const entries = useRead(() => readSession(context, session.uid), `${session.uid}:${context.token}`, open);
+    // The session as the record lists it: its state, its agent, where it comes from.
+    const facts = [
+        sessionStateSaid(session),
+        sessionAgentSaid(session),
+        sessionLineageSaid(session),
+    ].filter(Boolean);
+    return (_jsxs(Box, { as: "details", onToggle: (event) => setOpen(event.currentTarget.open), borderTop: "1px solid", borderColor: "border.muted", py: 2, children: [_jsxs(Box, { as: "summary", cursor: "pointer", fontSize: 1, children: [session.startedAt ? (_jsx(RelativeTime, { datetime: session.startedAt })) : ('A session'), session.title ? ` · ${session.title}` : '', session.version ? ` · version ${session.version}` : '', facts.length ? ` · ${facts.join(' · ')}` : '', entries.value ? ` · ${sessionSentence(entries.value)}` : ''] }), !open ? null : entries.loading ? (_jsx(Spinner, { size: "small" })) : entries.error ? (_jsx(Text, { role: "alert", sx: { fontSize: 1 }, children: entries.error })) : (_jsx(Box, { as: "ol", pl: 3, mt: 2, mb: 0, fontSize: 1, children: (entries.value ?? []).map(entry => (_jsxs(Box, { as: "li", mb: 1, children: [_jsx(Label, { sx: { mr: 2 }, children: RECORD_KIND_WORDS[entry.kind] ?? entry.kind }), entrySaid(entry)] }, entry.uid))) }))] }));
 }
 export function AppActivity({ appUid }) {
     const token = useIAMStore(state => state.token) ?? '';
@@ -58,6 +64,6 @@ export function AppActivity({ appUid }) {
     const context = { aiAgentsUrl, token };
     const readable = Boolean(appUid && token);
     const sessions = useRead(() => listSessions(context, appUid ?? ''), `${appUid}:${token}:${aiAgentsUrl}:${ended}`, readable);
-    return (_jsxs(Box, { "data-testid": "app-activity", children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: APP_ACTIVITY_WORDS.title }), !appUid ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: APP_ACTIVITY_WORDS.unsaved })) : !token ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: APP_ACTIVITY_WORDS.signedOut })) : sessions.loading && !sessions.value ? (_jsx(Spinner, { size: "small" })) : sessions.error ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: sessions.error })) : (sessions.value ?? []).length === 0 ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: APP_ACTIVITY_WORDS.none })) : ((sessions.value ?? []).map(session => (_jsx(Session, { context: context, session: session }, session.uid))))] }));
+    return (_jsxs(Box, { "data-testid": "app-activity", children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: APP_ACTIVITY_WORDS.title }), !appUid ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: APP_ACTIVITY_WORDS.unsaved })) : !token ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: APP_ACTIVITY_WORDS.signedOut })) : sessions.loading && !sessions.value ? (_jsx(Spinner, { size: "small" })) : sessions.error ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: sessions.error })) : (sessions.value?.sessions ?? []).length === 0 ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: APP_ACTIVITY_WORDS.none })) : ((sessions.value?.sessions ?? []).map(session => (_jsx(Session, { context: context, session: session }, session.uid))))] }));
 }
 export default AppActivity;

package/lib/apps/plugins/chat/ChatView.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { IconButton, SegmentedControl, Text, Truncate } from '@primer/react';
+import { Button, IconButton, SegmentedControl, Text, Truncate, } from '@primer/react';
 import { Box, loopShapeVars, useColorPalette } from '@datalayer/primer-addons';
 import { ScreenFullIcon, ScreenNormalIcon } from '@primer/octicons-react';
 import { computed, signal } from '@datalayer/reactor';
@@ -49,8 +49,11 @@ import { isInactiveSurfaceContribution, orderToolContributions, toolsForChatView
 import { agentBundleToolDefinitions, useAgentCommandTools, } from '../../../tools/adapters/commands';
 import { NONE_EDITOR, seedEditorChoice, setEditorOptions, } from '../shell/editorChoice';
 import { generateMessageId } from '../../../types/messages';
-import { deploymentOfPayload, threadOfVisit } from '../../apps/threads';
+import { deploymentOfPayload, sessionOfSearch, threadOfVisit, } from '../../apps/threads';
 import { openThread, THREAD_WORDS } from '../../../portable/thread';
+import { appSessionsClient } from '../../../portable/sessions';
+import { SessionActionsMenu, SessionStateLine, TurnActions, } from './SessionActionsMenu';
+import { SessionChooseDialog } from './SessionChooseDialog';
 import { FaceDrawing, PresenceFace, PresenceLine, } from '../../../chat/presence/Presence';
 import { presenceState, presenceToolOf, } from '../../../chat/presence/presenceStatus';
 import { latestSaying, newestIsAnswer, } from '../../../chat/assistant/state';
@@ -79,6 +82,8 @@ export default function ChatView({ workspace }) {
        default palette instead of throwing. */
     const palette = useColorPalette();
     const controlsRef = useRef(null);
+    /** The token the thread's menu calls the session API with (MH-F08). */
+    const iamTokenRef = useRef(undefined);
     const { setViewControls } = workspace;
     /*
      * Say the thread a message goes on to the workspace: an application's
@@ -1062,6 +1067,11 @@ export default function ChatView({ workspace }) {
      * sending to the host's server — on a hosted page, the page's own origin.
      */
     const agentServerUrl = agentServerOf(workspace.sandbox, workspace.serverUrl);
+    const sessionsClient = useMemo(() => appSessionsClient({
+        baseUrl: agentServerUrl ?? '',
+        getAccessToken: () => iamTokenRef.current,
+        fetch: (input, init) => fetch(input, init),
+    }), [agentServerUrl]);
     /*
      * Who a single request may be addressed to.
      *
@@ -1333,6 +1343,7 @@ export default function ChatView({ workspace }) {
     // not know (R-20): it runs a session of its deployment, and no more.
     const embedToken = reactor.getConfig(AGENTS_PLUGIN_NAME)?.embedToken;
     const iamToken = visitors ? visitor.token : embedToken || memberToken;
+    iamTokenRef.current = iamToken || undefined;
     /*
      * Its voice asked of the speech service as this chat speaks to its runtime
      * (VO-37, VO-19): the host's token, else this one — a visitor's,
@@ -1360,7 +1371,36 @@ export default function ChatView({ workspace }) {
      * agent holds every visitor's turns, never drawn as this person's.
      */
     const [visitThreadId] = useState(generateMessageId);
-    const givenThread = useMemo(() => threadOfVisit(config?.thread, deploymentUid, visitThreadId), [config?.thread, deploymentUid, visitThreadId]);
+    /*
+     * The web's deep link (MH-27): `?session=<uid>` on the chat's URL opens
+     * that session as the thread when the host gave none — a malformed one is
+     * said, not sent. And the thread an action opened (MH-10, MH-27): a
+     * clone's, an import's, a resumed one's — drawn in place of the given.
+     */
+    const [deepLinked, deepLinkRefused] = useMemo(() => {
+        try {
+            return [
+                sessionOfSearch(typeof window === 'undefined' ? '' : window.location.search),
+                '',
+            ];
+        }
+        catch (error) {
+            return ['', error instanceof Error ? error.message : String(error)];
+        }
+    }, []);
+    const [actionThread, setActionThread] = useState(undefined);
+    const givenThread = useMemo(() => actionThread ??
+        threadOfVisit(config?.thread ??
+            (deepLinked && runsApp
+                ? { id: deepLinked, messages: [], fromRuntime: true }
+                : undefined), deploymentUid, visitThreadId), [
+        actionThread,
+        config?.thread,
+        deepLinked,
+        runsApp,
+        deploymentUid,
+        visitThreadId,
+    ]);
     const [openedThread, setOpenedThread] = useState(null);
     const opening = Boolean(givenThread?.fromRuntime && openedThread?.given !== givenThread.id);
     useEffect(() => {
@@ -1422,6 +1462,68 @@ export default function ChatView({ workspace }) {
             ? openedThread.thread
             : undefined
         : givenThread;
+    /*
+     * The session the thread is, as the runtime describes it (MH-27): read
+     * once the thread is known and again after each turn and each action, so
+     * that the header's state words, the lineage line and the menu's entries
+     * say the session as it stands. A thread the runtime holds no session of
+     * yet — a visit before its first message — says nothing.
+     */
+    const threadUid = workspace.thread || chatThread?.id || '';
+    const [facts, setFacts] = useState(undefined);
+    const [factsTick, setFactsTick] = useState(0);
+    useEffect(() => {
+        if (!runsApp || !agentServerUrl || !threadUid || busy) {
+            return undefined;
+        }
+        let current = true;
+        sessionsClient.described(threadUid).then(row => current && setFacts(row), () => current && setFacts(undefined));
+        return () => {
+            current = false;
+        };
+    }, [runsApp, agentServerUrl, threadUid, busy, factsTick, sessionsClient]);
+    /* What an action said — a swap's sentence, a refusal as the runtime said
+       it — shown above the conversation until dismissed; and the picker and
+       the file an action asks with (`choose`, `pickFile`). */
+    const [actionSaid, setActionSaid] = useState(deepLinkRefused);
+    const [choice, setChoice] = useState(null);
+    const chooseResolver = useRef(null);
+    const fileResolver = useRef(null);
+    const fileInput = useRef(null);
+    const sessionContext = useMemo(() => ({
+        client: sessionsClient,
+        say: sentence => {
+            setActionSaid(sentence);
+            setFactsTick(tick => tick + 1);
+        },
+        openThread: uid => {
+            setActionThread({ id: uid, messages: [], fromRuntime: true });
+            setFactsTick(tick => tick + 1);
+        },
+        download: (name, text, mediaType) => {
+            const url = URL.createObjectURL(new Blob([text], { type: mediaType }));
+            const link = document.createElement('a');
+            link.href = url;
+            link.download = name;
+            link.click();
+            URL.revokeObjectURL(url);
+        },
+        choose: question => new Promise(resolve => {
+            chooseResolver.current = resolve;
+            setChoice(question);
+        }),
+        pickFile: accept => new Promise(resolve => {
+            const input = fileInput.current;
+            if (!input) {
+                resolve(undefined);
+                return;
+            }
+            fileResolver.current = resolve;
+            input.accept = accept;
+            input.value = '';
+            input.click();
+        }),
+    }), [sessionsClient]);
     /*
      * None without a server (`noRuntime`): the chat is off and connects to
      * nothing — no address is made up for it.
@@ -1847,7 +1949,16 @@ export default function ChatView({ workspace }) {
                         ? 'attention.fg'
                         : 'danger.fg', borderColor: chatExtras.errorBanner.variant === 'warning'
                         ? 'attention.muted'
-                        : 'danger.muted', children: chatExtras.errorBanner.message })) : null, openedThread?.said && openedThread.given === givenThread?.id ? (_jsx(Text, { as: "p", role: "status", sx: { m: 0, px: 3, py: 2, fontSize: 1, color: 'fg.muted' }, children: openedThread.said })) : null, _jsx(Box, { flex: "1 1 auto", minHeight: 0, display: "flex", children: opening ? (_jsx(Text, { as: "p", role: "status", sx: { m: 0, p: 3, fontSize: 1, color: 'fg.muted' }, children: THREAD_WORDS.opening })) : (_jsx(ChatBase
+                        : 'danger.muted', children: chatExtras.errorBanner.message })) : null, openedThread?.said && openedThread.given === givenThread?.id ? (_jsx(Text, { as: "p", role: "status", sx: { m: 0, px: 3, py: 2, fontSize: 1, color: 'fg.muted' }, children: openedThread.said })) : null, actionSaid ? (_jsxs(Box, { display: "flex", alignItems: "baseline", gap: 2, px: 3, py: 2, fontSize: 1, color: "fg.muted", role: "status", "data-session-said": "", children: [_jsx(Text, { sx: { flex: 1 }, children: actionSaid }), _jsx(Button, { size: "small", variant: "invisible", onClick: () => setActionSaid(''), children: "Dismiss" })] })) : null, choice ? (_jsx(SessionChooseDialog, { question: choice, onPick: id => {
+                        setChoice(null);
+                        chooseResolver.current?.(id);
+                        chooseResolver.current = null;
+                    } })) : null, _jsx("input", { ref: fileInput, type: "file", hidden: true, "data-session-file": "", onChange: async (event) => {
+                        const file = event.target.files?.[0];
+                        const text = file ? await file.text() : undefined;
+                        fileResolver.current?.(text);
+                        fileResolver.current = null;
+                    } }), _jsx(Box, { flex: "1 1 auto", minHeight: 0, display: "flex", children: opening ? (_jsx(Text, { as: "p", role: "status", sx: { m: 0, p: 3, fontSize: 1, color: 'fg.muted' }, children: THREAD_WORDS.opening })) : (_jsx(ChatBase
                     // The theme it wears, when the host names one (an application's).
                     , { 
                         // The theme it wears, when the host names one (an application's).
@@ -1992,7 +2103,7 @@ export default function ChatView({ workspace }) {
                           See `toggleFullScreen` for why it is the browser's API rather
                           than a big box.
                         */
-                        headerActions: _jsxs(Box, { display: "inline-flex", alignItems: "center", gap: 2, children: [workspace.chatHeaderActions, chatHeaderItems.length > 0 ? (_jsx(ReactorSlot, { slot: LoopSlots.chatHeader, props: { workspace } })) : null, _jsx(IconButton, { icon: fullScreen ? ScreenNormalIcon : ScreenFullIcon, "aria-label": fullScreen ? 'Exit full screen' : 'Enter full screen', variant: "invisible", size: "small", onClick: () => {
+                        headerActions: _jsxs(Box, { display: "inline-flex", alignItems: "center", gap: 2, children: [workspace.chatHeaderActions, runsApp && agentServerUrl ? (_jsxs(_Fragment, { children: [_jsx(SessionStateLine, { facts: facts }), _jsx(SessionActionsMenu, { uid: threadUid || undefined, describe: uid => sessionsClient.described(uid), context: sessionContext })] })) : null, chatHeaderItems.length > 0 ? (_jsx(ReactorSlot, { slot: LoopSlots.chatHeader, props: { workspace } })) : null, _jsx(IconButton, { icon: fullScreen ? ScreenNormalIcon : ScreenFullIcon, "aria-label": fullScreen ? 'Exit full screen' : 'Enter full screen', variant: "invisible", size: "small", onClick: () => {
                                         // Whether or not it takes, the hint has been answered:
                                         // they found the control, which is all it was for.
                                         setHintFullScreen(false);
@@ -2080,7 +2191,13 @@ export default function ChatView({ workspace }) {
                           tool did. With an editor open the change is visible where it
                           happened, and the default tool row is enough.
                         */
-                        notebookToolSurfacesId: active ? undefined : workspace.surfaceId, showTurnFooter: chatExtras.showTokenUsage ?? config?.showTokenUsage ?? true, onContextSnapshot: handleContextSnapshot, onLoadingChange: handleLoadingChange, onSpeakingChange: setSpeaking, onItemsChange: handleMessagesChange, onDisplayItemsChange: handleDisplayItemsChange, enableStreaming: true }, chatThread?.id)) }), !headerShown && chatHeaderItems.length > 0 ? (_jsx(Box, { hidden: true, children: _jsx(ReactorSlot, { slot: LoopSlots.chatHeader, props: { workspace } }) })) : null, besideChat && !promptHidden ? prompt : null] }) }));
+                        notebookToolSurfacesId: active ? undefined : workspace.surfaceId, showTurnFooter: chatExtras.showTokenUsage ?? config?.showTokenUsage ?? true, onContextSnapshot: handleContextSnapshot, onLoadingChange: handleLoadingChange, 
+                        /* Each turn's row offers what the registry places on a turn
+                           (MH-10): *Clone from here*, naming the turn — under the
+                           person's message, for an application's session only. */
+                        renderMessageFooter: runsApp && agentServerUrl
+                            ? (message, at) => message.role === 'user' ? (_jsx(TurnActions, { facts: facts, turn: at.turn, context: sessionContext })) : null
+                            : undefined, onSpeakingChange: setSpeaking, onItemsChange: handleMessagesChange, onDisplayItemsChange: handleDisplayItemsChange, enableStreaming: true }, chatThread?.id)) }), !headerShown && chatHeaderItems.length > 0 ? (_jsx(Box, { hidden: true, children: _jsx(ReactorSlot, { slot: LoopSlots.chatHeader, props: { workspace } }) })) : null, besideChat && !promptHidden ? prompt : null] }) }));
     // Off when the host asked for the menu alone: the composer's suggestions
     // control carries the same openers (`suggestions` above).
     const chipsEl = config?.suggestionLabels !== false && chatSuggestions.length > 0 ? (_jsx(Box, { "aria-label": chatText.suggestedPrompts, display: "flex", flexWrap: "wrap", gap: 2, px: 2, pb: "6px", children: chatSuggestions.map(item => (_jsx(Box, { as: "button", type: "button", 

package/lib/apps/plugins/chat/SessionActionsMenu.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The thread's `⋯` menu, drawn from the `loop.session.action` registry
+ * (MH-F08): the entries that apply to the session as it stands, read when
+ * the menu opens; an entry's `when` hides what does not apply.
+ *
+ * @module apps/plugins/chat/SessionActionsMenu
+ */
+import type { JSX } from 'react';
+import { type SessionActionContext, type SessionFacts } from '../../core';
+/**
+ * What the thread's header says of its session (MH-27, MH-10): its state
+ * with the turn phase — *Open · answering*, *Paused*, *Ended* — and where it
+ * comes from — *Cloned from e67a52b2 at turn 2*, *Imported from a file…* —
+ * as the record says them. Nothing while the session is not read.
+ */
+export declare function SessionStateLine({ facts, }: {
+    facts: SessionFacts | undefined;
+}): JSX.Element | null;
+/**
+ * The entries offered on a turn's row (MH-10): *Clone from here*, naming
+ * the turn. Drawn under the person's message of that turn; nothing while
+ * the session is not read or nothing applies.
+ */
+export declare function TurnActions({ facts, turn, context, }: {
+    facts: SessionFacts | undefined;
+    /** The person's turn the row belongs to. */
+    turn: number;
+    context: SessionActionContext;
+}): JSX.Element | null;
+export type SessionActionsMenuProps = {
+    /** The session the thread is, when it is one. */
+    uid: string | undefined;
+    /** How the menu reads the session's facts when it opens. */
+    describe: (uid: string) => Promise<SessionFacts>;
+    /** What an entry may do. */
+    context: SessionActionContext;
+};
+/** The entries that apply, as a menu; nothing when the thread is no session. */
+export declare function SessionActionsMenu({ uid, describe, context, }: SessionActionsMenuProps): JSX.Element | null;
+export default SessionActionsMenu;

package/lib/apps/plugins/chat/SessionActionsMenu.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useState } from 'react';
+import { ActionList, ActionMenu, Button, IconButton, Label, Text, } from '@primer/react';
+import { KebabHorizontalIcon } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+import { useContributions } from '@datalayer/reactor/react';
+import { LoopSessionAction, sessionActionsFor, } from '../../core';
+import { sessionLineageSaid, sessionStateSaid, } from '../../../portable/activity';
+/**
+ * What the thread's header says of its session (MH-27, MH-10): its state
+ * with the turn phase — *Open · answering*, *Paused*, *Ended* — and where it
+ * comes from — *Cloned from e67a52b2 at turn 2*, *Imported from a file…* —
+ * as the record says them. Nothing while the session is not read.
+ */
+export function SessionStateLine({ facts, }) {
+    if (!facts) {
+        return null;
+    }
+    const lineage = sessionLineageSaid(facts);
+    return (_jsxs(Box, { display: "inline-flex", alignItems: "center", gap: 2, "data-session-state": facts.state, children: [_jsx(Label, { size: "small", variant: facts.state === 'open'
+                    ? 'accent'
+                    : facts.state === 'paused'
+                        ? 'attention'
+                        : 'secondary', children: sessionStateSaid(facts) }), lineage ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, "data-session-lineage": "", children: lineage })) : null] }));
+}
+/**
+ * The entries offered on a turn's row (MH-10): *Clone from here*, naming
+ * the turn. Drawn under the person's message of that turn; nothing while
+ * the session is not read or nothing applies.
+ */
+export function TurnActions({ facts, turn, context, }) {
+    const entries = useContributions(LoopSessionAction);
+    const applicable = sessionActionsFor(entries, facts, 'turn');
+    if (!facts || applicable.length === 0 || turn < 1) {
+        return null;
+    }
+    return (_jsx(Box, { display: "inline-flex", gap: 1, "data-turn-actions": turn, children: applicable.map(entry => (_jsx(Button, { size: "small", variant: "invisible", "data-turn-action": entry.id, onClick: () => {
+                Promise.resolve(entry.run(facts, { ...context, atTurn: turn })).catch(error => context.say(String(error.message ?? error)));
+            }, children: entry.label }, entry.id))) }));
+}
+/** The entries that apply, as a menu; nothing when the thread is no session. */
+export function SessionActionsMenu({ uid, describe, context, }) {
+    const entries = useContributions(LoopSessionAction);
+    const [facts, setFacts] = useState(undefined);
+    const [open, setOpen] = useState(false);
+    const [said, setSaid] = useState('');
+    const saying = {
+        ...context,
+        say: sentence => {
+            setSaid(sentence);
+            context.say(sentence);
+        },
+    };
+    const onOpenChange = useCallback((opened) => {
+        setOpen(opened);
+        if (opened && uid) {
+            describe(uid).then(setFacts, () => setFacts(undefined));
+        }
+    }, [describe, uid]);
+    if (!uid || entries.length === 0) {
+        return null;
+    }
+    const applicable = sessionActionsFor(entries, facts);
+    return (_jsxs(ActionMenu, { open: open, onOpenChange: onOpenChange, children: [_jsx(ActionMenu.Anchor, { children: _jsx(IconButton, { icon: KebabHorizontalIcon, "aria-label": "Session actions", variant: "invisible", size: "small", "data-testid": "session-actions" }) }), _jsx(ActionMenu.Overlay, { width: "small", children: _jsxs(ActionList, { children: [applicable.length === 0 ? (_jsx(ActionList.Item, { disabled: true, children: facts
+                                ? 'Nothing applies to this session now.'
+                                : 'Reading the session…' })) : (applicable.map(entry => (_jsx(ActionList.Item, { "data-session-action": entry.id, onSelect: () => {
+                                if (!facts) {
+                                    return;
+                                }
+                                Promise.resolve(entry.run(facts, saying)).catch(error => saying.say(String(error.message ?? error)));
+                            }, children: entry.label }, entry.id)))), said ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsx(ActionList.Item, { disabled: true, "data-testid": "session-actions-said", children: said })] })) : null] }) })] }));
+}
+export default SessionActionsMenu;

package/lib/apps/plugins/chat/SessionChooseDialog.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The picker a session action asks with (`SessionActionContext.choose`):
+ * one of several — the agent a session is switched to — and, under the
+ * pick, what it does: the sentence the new agent will be told, shown
+ * before it is sent (MH-27). Declined, nothing is sent.
+ *
+ * @module apps/plugins/chat/SessionChooseDialog
+ */
+import type { JSX } from 'react';
+import type { SessionActionContext } from '../../core';
+/** What a `choose` asks, as the context hands it over. */
+export type SessionChoice = Parameters<NonNullable<SessionActionContext['choose']>>[0];
+export declare const CHOOSE_WORDS: {
+    readonly confirm: "Switch";
+    readonly cancel: "Keep it";
+};
+export declare function SessionChooseDialog({ question, onPick, }: {
+    question: SessionChoice;
+    /** The pick, or `undefined` when declined. */
+    onPick: (id: string | undefined) => void;
+}): JSX.Element;
+export default SessionChooseDialog;