@datalayer/agent-runtimes 1.5.65 → 1.5.70

package/lib/chat/index.d.ts

@@ -65,7 +65,7 @@ export { ToolCallDisplay, type ToolCallDisplayProps } from './tools';
 export { ICON_PACKAGES, SpecMark, hasMark, marksOfFrontendTool, marksOfMcpServer, marksOfRuntimeTool, marksOfSkill, marksOfToolCall, parseIconRef, useMarkIcon, type IconPackage, type IconRef, type MarkIcon, type MarkedMcpServer, type Marks, type SpecMarkProps, type ToolKind, type ToolMarks, } from './marks';
 export { ToolApprovalDialog, useToolApprovalDialog, type ToolApprovalDialogProps, } from './tools/ToolApprovalDialog';
 export { ToolApprovalBanner, type ToolApprovalBannerProps, type PendingApproval, } from './tools/ToolApprovalBanner';
-export { Chat, type ChatProps } from './Chat';
+export { Chat, type ChatProps, type ChatSessionActions } from './Chat';
 export { ChatFloating, type ChatFloatingProps } from './ChatFloating';
 export { ChatInline, type ChatInlineProps, type ChatInlineProtocolConfig, } from './ChatInline';
 export { AgentRuntimeChat, type AgentRuntimeChatProps, } from '../agents/AgentRuntimeChat';

package/lib/chat/messages/ChatMessageList.d.ts

@@ -76,7 +76,9 @@ export interface ChatMessageListProps {
      * that this list has no opinion on. Not called for tool calls or for a
      * `note`, which has no footer of its own.
      */
-    renderMessageFooter?: (message: ChatMessage) => ReactNode;
+    renderMessageFooter?: (message: ChatMessage, at: {
+        turn: number;
+    }) => ReactNode;
     /**
      * The answer a sentence is being said from (VO-65): its row is
      * marked `aria-current` and `data-voice-saying`, with a bar beside it —

package/lib/chat/messages/ChatMessageList.js

@@ -443,6 +443,22 @@ export function ChatMessageList({ displayItems, actOn, upload, isLoading, isStre
         const running = isLoading || isStreaming;
         return (_jsx(TurnFooter, { usage: agentUsage, live: isLastTurn && running, latest: isLastTurn && !running, padding: padding, onCopy: () => copyTurn(start, index), onRemove: () => onRemoveItems?.(displayItems.slice(start, index + 1).map(entry => entry.id)) }));
     };
+    /**
+     * The person's turn an item belongs to: how many of their messages come
+     * up to and including it. A footer's action on a turn names it by this.
+     */
+    const turnOfItem = (item) => {
+        let turn = 0;
+        for (const each of displayItems) {
+            if (!isToolCallMessage(each) && each.role === 'user') {
+                turn += 1;
+            }
+            if (each.id === item.id) {
+                break;
+            }
+        }
+        return turn;
+    };
     const renderItem = (item, index) => {
         // ---- Tool call item ----
         if (isToolCallMessage(item)) {
@@ -539,8 +555,11 @@ export function ChatMessageList({ displayItems, actOn, upload, isLoading, isStre
                 }
             }
         }
-        // The host's footer, asked once: a row only when it draws something.
-        const messageFooter = renderMessageFooter?.(message);
+        // The host's footer, asked once: a row only when it draws something —
+        // told the person's turn the message belongs to.
+        const messageFooter = renderMessageFooter?.(message, {
+            turn: turnOfItem(message),
+        });
         // The answer being said (VO-65): marked by a bar and for assistive tech.
         const said = saidMessageId !== undefined && message.id === saidMessageId;
         return (_jsx(Box, { "data-chat-message": message.role, "data-voice-saying": said ? '' : undefined, "aria-current": said ? 'true' : undefined, sx: said

package/lib/portable/activity.d.ts

@@ -41,6 +41,95 @@ export type ScheduledRun = {
     /** When it runs next; empty when the scheduler does not say. */
     nextAt: string;
 };
+/** The states of a session: open (held by a runtime), paused, ended. */
+export declare const SESSION_STATES: readonly ["open", "paused", "ended"];
+export type SessionState = (typeof SESSION_STATES)[number];
+/** The phase of an open session's turn, as the runtime that holds it says it. */
+export declare const SESSION_TURNS: readonly ["idle", "running", "waiting"];
+export type SessionTurn = (typeof SESSION_TURNS)[number];
+/** Where an open session runs: a runtime, or a seat of a team run; nothing while paused or ended. */
+export type SessionRunsOn = {
+    kind: 'runtime';
+    uid: string;
+} | {
+    kind: 'team_run';
+    executionId: string;
+    seat: string;
+} | null;
+/** Where a session comes from: cloned from another at a turn, or imported from a file. */
+export type SessionLineage = {
+    forkedFrom: {
+        uid: string;
+        atTurn: number;
+    } | null;
+    importedFrom: {
+        digest: string;
+        exportedAt: string;
+        /** The exporter's uid. */
+        exportedBy: string;
+    } | null;
+};
+/**
+ * One session, as `GET /api/ai-agents/v1/apps/sessions` lists it and as a
+ * runtime describes one it holds (`GET /api/v1/apps/sessions/{uid}`): the
+ * same shape on the Studio, the chat and the phone. `turn` and `held` are
+ * the runtime's and empty from the record.
+ */
+export type SessionRow = {
+    uid: string;
+    appUid: string;
+    deploymentUid: string;
+    version: number;
+    /** `test` for a session its tests ran; empty for real use. */
+    purpose: string;
+    launchUid: string;
+    ownerUid: string;
+    openedBy: string;
+    wokenBy: string;
+    state: SessionState;
+    /** The runtime's turn phase of an open session; `''` from the record. */
+    turn: SessionTurn | '';
+    /** Whether the runtime asked holds it; `null` from the record. */
+    held: boolean | null;
+    /** The agentspec bound to it now. */
+    agent: string;
+    /** The harness that agent runs on; empty for a model agent. */
+    harness: string;
+    title: string;
+    archived: boolean;
+    runsOn: SessionRunsOn;
+    lineage: SessionLineage;
+    /** The person's turns so far. */
+    turns: number;
+    startedAt: string;
+    keptUntil: string;
+};
+/**
+ * A session row as the record or a runtime answers it. A row without a uid,
+ * or whose state is not one of the three, is refused in a sentence: the
+ * reader never guesses a state (an older opening is re-indexed, not read).
+ */
+export declare function sessionRowOf(raw: Record<string, unknown>): SessionRow;
+/** A page of sessions, as the record lists them: `{sessions, has_more}`. */
+export declare function sessionPageOf(body: Record<string, unknown>): {
+    sessions: SessionRow[];
+    hasMore: boolean;
+};
+/** The state words, on every client. */
+export declare const SESSION_STATE_WORDS: Record<SessionState, string>;
+/** The turn phase, beside an open session's state. */
+export declare const SESSION_TURN_WORDS: Record<SessionTurn, string>;
+/** A session's state in words: *Open · answering*, *Paused*, *Ended*. */
+export declare function sessionStateSaid(session: Pick<SessionRow, 'state' | 'turn'>): string;
+/** The words of a session's lineage. */
+export declare const SESSION_LINEAGE_WORDS: {
+    readonly cloned: (uid: string, atTurn: number) => string;
+    readonly imported: (exportedAt: string) => string;
+};
+/** Where a session comes from, in a sentence; `''` for one opened here. */
+export declare function sessionLineageSaid(session: Pick<SessionRow, 'lineage'>): string;
+/** The agent a session is bound to, with its harness when it runs on one: *shield-mvp-codex (codex)*. */
+export declare function sessionAgentSaid(session: Pick<SessionRow, 'agent' | 'harness'>): string;
 /** What an application, or all of a person's, is doing (R-15): real use only, its tests read apart. */
 export type AppActivity = {
     /** Sessions whose latest run has not answered yet, newest first: their run's start. */
@@ -49,8 +138,8 @@ export type AppActivity = {
     scheduled: ScheduledRun[];
     /** Why its schedules could not be read; empty when they were. */
     scheduledProblem: string;
-    /** Its other sessions, newest first: their opening entries. */
-    completed: RecordEntry[];
+    /** Its other sessions, newest first, each as the record lists it. */
+    completed: SessionRow[];
     /** The offset of the next page of completed sessions; `null` after the last. */
     nextOffset: number | null;
 };

package/lib/portable/activity.js

@@ -4,8 +4,10 @@
  */
 /**
  * What an application is doing (R-15), as ai-agents answers
- * `/api/ai-agents/v1/apps/activity`, and its record's entries
- * (`/apps/sessions`, `/apps/records`): read and said the same by the Studio
+ * `/api/ai-agents/v1/apps/activity`, its record's entries (`/apps/records`)
+ * and its sessions as the record lists them (`/apps/sessions`: state,
+ * agent, title, lineage, where each runs — the row a runtime describes a
+ * held session with too): read and said the same by the Studio, the chat
  * and Datalayer Mobile (M-015b). Pure: each client fetches with its own
  * authentication and hands the body here.
  *
@@ -63,6 +65,143 @@ export function sessionSentence(entries) {
     }
     return `${parts.join(', ')}.`;
 }
+// --- a session, as the record lists it ------------------------------------
+/** The states of a session: open (held by a runtime), paused, ended. */
+export const SESSION_STATES = ['open', 'paused', 'ended'];
+/** The phase of an open session's turn, as the runtime that holds it says it. */
+export const SESSION_TURNS = ['idle', 'running', 'waiting'];
+const runsOnOf = (raw) => {
+    if (!isRecord(raw)) {
+        return null;
+    }
+    if (raw.kind === 'runtime') {
+        return { kind: 'runtime', uid: said(raw.uid) };
+    }
+    if (raw.kind === 'team_run') {
+        return {
+            kind: 'team_run',
+            executionId: said(raw.execution_id),
+            seat: said(raw.seat),
+        };
+    }
+    throw new Error(`A session runs on a runtime or a team run, not on ${JSON.stringify(raw.kind)}.`);
+};
+const lineageOf = (raw) => {
+    const lineage = isRecord(raw) ? raw : {};
+    const forked = isRecord(lineage.forked_from) ? lineage.forked_from : null;
+    const imported = isRecord(lineage.imported_from)
+        ? lineage.imported_from
+        : null;
+    return {
+        forkedFrom: forked
+            ? { uid: said(forked.uid), atTurn: Number(forked.at_turn) || 0 }
+            : null,
+        importedFrom: imported
+            ? {
+                digest: said(imported.digest),
+                exportedAt: said(imported.exported_at),
+                exportedBy: said(imported.exported_by),
+            }
+            : null,
+    };
+};
+/**
+ * A session row as the record or a runtime answers it. A row without a uid,
+ * or whose state is not one of the three, is refused in a sentence: the
+ * reader never guesses a state (an older opening is re-indexed, not read).
+ */
+export function sessionRowOf(raw) {
+    const uid = said(raw.uid);
+    if (!uid) {
+        throw new Error('A session row names its uid; this one does not.');
+    }
+    const state = said(raw.state);
+    if (!SESSION_STATES.includes(state)) {
+        throw new Error(`There is no session state ${JSON.stringify(state)} (session ${uid}): one of ${SESSION_STATES.join(', ')}.`);
+    }
+    const turn = said(raw.turn);
+    if (turn && !SESSION_TURNS.includes(turn)) {
+        throw new Error(`There is no turn phase ${JSON.stringify(turn)} (session ${uid}): one of ${SESSION_TURNS.join(', ')}.`);
+    }
+    return {
+        uid,
+        appUid: said(raw.app_uid),
+        deploymentUid: said(raw.deployment_uid),
+        version: Number(raw.version) || 0,
+        purpose: said(raw.purpose),
+        launchUid: said(raw.launch_uid),
+        ownerUid: said(raw.owner_uid),
+        openedBy: said(raw.opened_by),
+        wokenBy: said(raw.woken_by),
+        state: state,
+        turn: turn,
+        held: typeof raw.held === 'boolean' ? raw.held : null,
+        agent: said(raw.agent),
+        harness: said(raw.harness),
+        title: said(raw.title),
+        archived: raw.archived === true,
+        runsOn: runsOnOf(raw.runs_on),
+        lineage: lineageOf(raw.lineage),
+        turns: Number(raw.turns) || 0,
+        startedAt: said(raw.started_at),
+        keptUntil: said(raw.kept_until),
+    };
+}
+/** A page of sessions, as the record lists them: `{sessions, has_more}`. */
+export function sessionPageOf(body) {
+    return {
+        sessions: records(body.sessions).map(sessionRowOf),
+        hasMore: body.has_more === true,
+    };
+}
+/** The state words, on every client. */
+export const SESSION_STATE_WORDS = {
+    open: 'Open',
+    paused: 'Paused',
+    ended: 'Ended',
+};
+/** The turn phase, beside an open session's state. */
+export const SESSION_TURN_WORDS = {
+    idle: '',
+    running: 'answering',
+    waiting: 'waiting for you',
+};
+/** A session's state in words: *Open · answering*, *Paused*, *Ended*. */
+export function sessionStateSaid(session) {
+    const phase = session.state === 'open' && session.turn
+        ? SESSION_TURN_WORDS[session.turn]
+        : '';
+    return phase
+        ? `${SESSION_STATE_WORDS[session.state]} · ${phase}`
+        : SESSION_STATE_WORDS[session.state];
+}
+/** The words of a session's lineage. */
+export const SESSION_LINEAGE_WORDS = {
+    cloned: (uid, atTurn) => `Cloned from ${uid} at turn ${atTurn}`,
+    imported: (exportedAt) => exportedAt
+        ? `Imported from a file exported ${exportedAt}`
+        : 'Imported from a file',
+};
+/** Where a session comes from, in a sentence; `''` for one opened here. */
+export function sessionLineageSaid(session) {
+    const { forkedFrom, importedFrom } = session.lineage;
+    if (forkedFrom) {
+        return SESSION_LINEAGE_WORDS.cloned(forkedFrom.uid, forkedFrom.atTurn);
+    }
+    if (importedFrom) {
+        return SESSION_LINEAGE_WORDS.imported(importedFrom.exportedAt);
+    }
+    return '';
+}
+/** The agent a session is bound to, with its harness when it runs on one: *shield-mvp-codex (codex)*. */
+export function sessionAgentSaid(session) {
+    if (!session.agent) {
+        return '';
+    }
+    return session.harness && session.harness !== session.agent
+        ? `${session.agent} (${session.harness})`
+        : session.agent;
+}
 /** `/apps/activity`'s answer, read. */
 export function activityOf(body) {
     return {
@@ -77,7 +216,7 @@ export function activityOf(body) {
             nextAt: said(raw.next_at),
         })),
         scheduledProblem: said(body.scheduled_problem),
-        completed: records(body.completed).map(entryOf),
+        completed: records(body.completed).map(sessionRowOf),
         nextOffset: typeof body.next_offset === 'number' ? body.next_offset : null,
     };
 }
@@ -97,7 +236,7 @@ export function mergeActivityPages(pages) {
     const completed = pages
         .flatMap(page => page.completed)
         .filter(entry => {
-        const key = entry.uid || entry.sessionUid;
+        const key = entry.uid;
         if (seen.has(key)) {
             return false;
         }

package/lib/portable/fixtures.d.ts

@@ -20,7 +20,7 @@ export declare function shieldDisplayFixtures(): {
 export declare function conversationFixture(): ConversationState;
 /**
  * `GET /api/ai-agents/v1/apps/activity`'s answer for one application: a
- * session in progress, a scheduled run, a completed one ended by Stop, and a
+ * session in progress, a scheduled run, a completed one (ended), and a
  * next page — what the Studio's Activity and the phone's read alike (M-015b).
  */
 export declare function activityFixture(): Record<string, unknown>;

package/lib/portable/fixtures.js

@@ -120,7 +120,7 @@ export function conversationFixture() {
 }
 /**
  * `GET /api/ai-agents/v1/apps/activity`'s answer for one application: a
- * session in progress, a scheduled run, a completed one ended by Stop, and a
+ * session in progress, a scheduled run, a completed one (ended), and a
  * next page — what the Studio's Activity and the phone's read alike (M-015b).
  */
 export function activityFixture() {
@@ -153,15 +153,25 @@ export function activityFixture() {
         scheduled_problem: '',
         completed: [
             {
-                uid: 'e-out',
+                uid: 's-1',
                 app_uid: 'app-1',
-                session_uid: 's-1',
                 deployment_uid: 'd-1',
                 version: 3,
-                kind: 'output',
-                summary: '',
-                payload: { status: 'stopped' },
-                created_at: '2026-10-15T08:00:00Z',
+                purpose: '',
+                launch_uid: '',
+                owner_uid: 'o-1',
+                opened_by: 'o-1',
+                woken_by: '',
+                state: 'ended',
+                agent: 'inbox-triage',
+                harness: '',
+                title: 'The inbox, Thursday',
+                archived: false,
+                runs_on: null,
+                lineage: { forked_from: null, imported_from: null },
+                turns: 2,
+                started_at: '2026-10-15T08:00:00Z',
+                kept_until: '2026-11-14T08:00:00Z',
             },
         ],
         next_offset: 20,

package/lib/portable/index.d.ts

@@ -26,7 +26,7 @@ export { DIRECT_MAX, DIRECT_WORDS, directAnswerOf, directAuthor, directClient, o
 export { SIGN_IN_POLL_MS, SIGN_IN_STATUS_PATH, signInStandsOf, signInStatusClient, type SignInStands, } from './signInStatus';
 export { emptyFields, fieldProblems, MAX_VALUE_LENGTH, PROTECTED_INPUT_WORDS, protectedInputClient, protectedRequestOf, ProtectedRequestGone, sentWords, submitBody, submitWords, ticketComplete, ticketOfPage, type ProtectedField, type ProtectedRequest, } from './protectedInput';
 export { failureOf, otlpMetricsOf, RunMeter, type RunMeasure, type StreamFailure, } from './runMeasures';
-export { ACTIVITY_WORDS, activityOf, entryOf, entrySaid, mergeActivityPages, runEndOf, scheduledSays, sessionSentence, wakesOn, type AppActivity, type RecordEntry, type RecordKind, type ScheduledRun, } from './activity';
+export { ACTIVITY_WORDS, activityOf, entryOf, entrySaid, mergeActivityPages, runEndOf, scheduledSays, SESSION_LINEAGE_WORDS, SESSION_STATE_WORDS, SESSION_STATES, SESSION_TURN_WORDS, SESSION_TURNS, sessionAgentSaid, sessionLineageSaid, sessionPageOf, sessionRowOf, sessionSentence, sessionStateSaid, wakesOn, type AppActivity, type RecordEntry, type RecordKind, type ScheduledRun, type SessionLineage, type SessionRow, type SessionRunsOn, type SessionState, type SessionTurn, } from './activity';
 export { deploymentEventLine, deploymentEventOf, notDeletedOf, resetBody, resetCountsOf, resetLines, stateChangeBody, stoppedWorkLine, stoppedWorkOf, type DeploymentEvent, type DeploymentEventKind, type DeploymentState, type ResetCounts, type StoppedWork, } from './lifecycle';
 export { agentRuntimesOf, agentSummaryOfRuntime, CREATING_STATUSES, isAgentRuntime, isCreatingAgent, runtimeOf, type AgentRuntime, type AgentSummaryData, } from './runtimes';
 export { agentRunClient, agentRuntimesUrlOf, appSessionsClient, RuntimeRefusal, type AgentRunClient, type AgentTurn, type AppSessionsClient, type RuntimeClientOptions, type SessionStart, type StreamOptions, } from './sessions';

package/lib/portable/index.js

@@ -45,8 +45,9 @@ export { SIGN_IN_POLL_MS, SIGN_IN_STATUS_PATH, signInStandsOf, signInStatusClien
 export { emptyFields, fieldProblems, MAX_VALUE_LENGTH, PROTECTED_INPUT_WORDS, protectedInputClient, protectedRequestOf, ProtectedRequestGone, sentWords, submitBody, submitWords, ticketComplete, ticketOfPage, } from './protectedInput';
 // How a streamed turn went, measured without its words (M-036).
 export { failureOf, otlpMetricsOf, RunMeter, } from './runMeasures';
-// What an application is doing, and its record's entries (R-15, M-015b).
-export { ACTIVITY_WORDS, activityOf, entryOf, entrySaid, mergeActivityPages, runEndOf, scheduledSays, sessionSentence, wakesOn, } from './activity';
+// What an application is doing, its record's entries, and its sessions as
+// the record lists them (R-15, M-015b).
+export { ACTIVITY_WORDS, activityOf, entryOf, entrySaid, mergeActivityPages, runEndOf, scheduledSays, SESSION_LINEAGE_WORDS, SESSION_STATE_WORDS, SESSION_STATES, SESSION_TURN_WORDS, SESSION_TURNS, sessionAgentSaid, sessionLineageSaid, sessionPageOf, sessionRowOf, sessionSentence, sessionStateSaid, wakesOn, } from './activity';
 // A deployment's pause, resume and reset, and its recorded events (R-17, M-041b).
 export { deploymentEventLine, deploymentEventOf, notDeletedOf, resetBody, resetCountsOf, resetLines, stateChangeBody, stoppedWorkLine, stoppedWorkOf, } from './lifecycle';
 // A person's agent runtimes, and an agent's summary (M-014b).

package/lib/portable/sessions.d.ts

@@ -12,6 +12,7 @@
  */
 import type { ChatMessage } from '../types/messages';
 import { type AgUiEvent } from './agui';
+import { type SessionRow } from './activity';
 /** Where a runtime is, and as whom it is asked. */
 export type RuntimeClientOptions = {
     /** The runtime's agent-runtimes address (`…/agent-runtimes/<runtime>`). */
@@ -59,8 +60,31 @@ export declare function appSessionsClient(options: RuntimeClientOptions): {
     stop: (uid: string) => Promise<Record<string, unknown>>;
     /** End the conversation for good; its record stays. */
     end: (uid: string) => Promise<Record<string, unknown>>;
-    /** What the session is: its state (`open`, `running`, `waiting`, `stopped`) and what it asks. */
+    /** What the session is: its state (`open`, `paused`, `ended`), its turn phase, what it asks. */
     describe: (uid: string) => Promise<Record<string, unknown>>;
+    /** The session as a row (`sessionRowOf`): its state refused when it is none of the three. */
+    described: (uid: string) => Promise<SessionRow>;
+    /** The caller's sessions, held and recorded, paged and filtered (`?app=`, `?agent=`, `?state=`, `?q=`, `?archived=true` includes the archived, `?after=`, `?limit=`). */
+    list: (params?: Record<string, string | number | boolean>) => Promise<Record<string, unknown>>;
+    /** Swap the session's agent in place: the new agent is told in a sentence, said back. */
+    swap: (uid: string, agent: string) => Promise<Record<string, unknown>>;
+    /** Clone from a turn: a new session, paused, the same or another agent. */
+    clone: (uid: string, options?: {
+        upToTurn?: number;
+        agent?: string;
+        title?: string;
+    }) => Promise<Record<string, unknown>>;
+    /** The session as a `datalayer-session/1` file (JSONL text). */
+    exportFile: (uid: string, format?: string) => Promise<string>;
+    /** Import a session file: a new session, paused, the importer its author. */
+    importFile: (text: string, options?: {
+        agent?: string;
+        format?: string;
+    }) => Promise<Record<string, unknown>>;
+    /** Rename the session (at most 200 characters). */
+    rename: (uid: string, title: string) => Promise<Record<string, unknown>>;
+    /** Archive it (hidden from the list unless asked for), or bring it back. */
+    archive: (uid: string, archived: boolean) => Promise<Record<string, unknown>>;
     /** Its conversation as a person reads it (`messagesOfThread`). */
     messages: (uid: string) => Promise<ChatMessage[]>;
 };

package/lib/portable/sessions.js

@@ -5,6 +5,7 @@
 import { readRunStream } from './agui';
 import { agUiRefusal, refusalBody } from './agUiRefusal';
 import { messagesOfThread } from './thread';
+import { sessionRowOf } from './activity';
 /** A route that refused: its status and the runtime's sentence. */
 export class RuntimeRefusal extends Error {
     status;
@@ -26,10 +27,14 @@ function clientOf({ baseUrl, getAccessToken, fetch: fetcher, }) {
     const refused = async (response) => {
         throw new RuntimeRefusal(response.status, agUiRefusal(response.status, response.statusText, await refusalBody(response)));
     };
-    const json = async (path, method = 'GET') => {
+    const json = async (path, method = 'GET', body) => {
         const response = await fetcher(`${root}${path}`, {
             method,
-            headers: headers({ Accept: 'application/json' }),
+            headers: headers({
+                Accept: 'application/json',
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+            }),
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
         });
         if (!response.ok) {
             return refused(response);
@@ -59,7 +64,7 @@ const at = (uid) => `/api/v1/apps/sessions/${encodeURIComponent(uid)}`;
  * settings, resume (streamed), and stop, end, read (JSON).
  */
 export function appSessionsClient(options) {
-    const { json, stream } = clientOf(options);
+    const { json, stream, fetcher, headers, refused, root } = clientOf(options);
     return {
         /** Start a session with its first message. */
         start: (start, streaming) => stream('/api/v1/apps/sessions', {
@@ -82,8 +87,61 @@ export function appSessionsClient(options) {
         stop: (uid) => json(`${at(uid)}/stop`, 'POST'),
         /** End the conversation for good; its record stays. */
         end: (uid) => json(`${at(uid)}/end`, 'POST'),
-        /** What the session is: its state (`open`, `running`, `waiting`, `stopped`) and what it asks. */
+        /** What the session is: its state (`open`, `paused`, `ended`), its turn phase, what it asks. */
         describe: (uid) => json(at(uid)),
+        /** The session as a row (`sessionRowOf`): its state refused when it is none of the three. */
+        described: async (uid) => sessionRowOf(await json(at(uid))),
+        /** The caller's sessions, held and recorded, paged and filtered (`?app=`, `?agent=`, `?state=`, `?q=`, `?archived=true` includes the archived, `?after=`, `?limit=`). */
+        list: (params = {}) => {
+            const query = new URLSearchParams();
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== '' && value !== undefined && value !== false) {
+                    query.set(key, String(value));
+                }
+            }
+            const search = query.toString();
+            return json(`/api/v1/apps/sessions${search ? `?${search}` : ''}`);
+        },
+        /** Swap the session's agent in place: the new agent is told in a sentence, said back. */
+        swap: (uid, agent) => json(`${at(uid)}/agent`, 'POST', { agent }),
+        /** Clone from a turn: a new session, paused, the same or another agent. */
+        clone: (uid, options = {}) => json(`${at(uid)}/clone`, 'POST', {
+            up_to_turn: options.upToTurn ?? null,
+            agent: options.agent ?? null,
+            title: options.title ?? '',
+        }),
+        /** The session as a `datalayer-session/1` file (JSONL text). */
+        exportFile: async (uid, format = '') => {
+            const response = await fetcher(`${root}${at(uid)}/export${format ? `?format=${encodeURIComponent(format)}` : ''}`, { method: 'GET', headers: headers() });
+            if (!response.ok) {
+                return refused(response);
+            }
+            return response.text();
+        },
+        /** Import a session file: a new session, paused, the importer its author. */
+        importFile: async (text, options = {}) => {
+            const query = new URLSearchParams();
+            if (options.agent) {
+                query.set('agent', options.agent);
+            }
+            if (options.format) {
+                query.set('format', options.format);
+            }
+            const search = query.toString();
+            const response = await fetcher(`${root}/api/v1/apps/sessions/import${search ? `?${search}` : ''}`, {
+                method: 'POST',
+                headers: headers({ 'Content-Type': 'application/x-ndjson' }),
+                body: text,
+            });
+            if (!response.ok) {
+                return refused(response);
+            }
+            return (await response.json());
+        },
+        /** Rename the session (at most 200 characters). */
+        rename: (uid, title) => json(`${at(uid)}/title`, 'PUT', { title }),
+        /** Archive it (hidden from the list unless asked for), or bring it back. */
+        archive: (uid, archived) => json(`${at(uid)}/archived`, 'PUT', { archived }),
         /** Its conversation as a person reads it (`messagesOfThread`). */
         messages: async (uid) => messagesOfThread((await json(`${at(uid)}/messages`)).messages),
     };