@datalayer/agent-runtimes 1.5.43 → 1.5.44

package/lib/portable/activity.d.ts

@@ -0,0 +1,78 @@
+export type RecordKind = 'session'
+/** A run began: in progress until it answers (R-15). Not a step. */
+ | 'run' | 'tool_call' | 'decision' | 'check' | 'approval' | 'output' | 'feedback'
+/** A turn of a conversation: what was asked, what it answered (V-16). */
+ | 'turn'
+/** What it did, step by step (P-16); a harness's session, turn and plan events (SHIELD §6.4). */
+ | 'step'
+/** What one of its channels was sent, or why not: `{channel, event, delivery, detail}` (R-37). */
+ | 'notification';
+/** One entry of an application's record. */
+export type RecordEntry = {
+    uid: string;
+    appUid: string;
+    sessionUid: string;
+    deploymentUid: string;
+    version: number;
+    kind: RecordKind;
+    summary: string;
+    payload: Record<string, unknown>;
+    createdAt: string;
+    /** `test` for a session its tests ran (the Evals engine's); empty for real use. */
+    purpose: string;
+};
+/** An entry as ai-agents answers with it. */
+export declare function entryOf(raw: Record<string, unknown>): RecordEntry;
+/** How the run an entry ends ended: `answered`, `stopped`, `gone`; `''` for any other entry. */
+export declare function runEndOf(entry: RecordEntry): string;
+/** An entry in words: its summary, or how its run ended when its words are not kept. */
+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;
+/** A run its schedule plans, as the scheduler says (R-15). */
+export type ScheduledRun = {
+    deploymentUid: string;
+    appUid: string;
+    version: number;
+    /** Which of its triggers, by position in its Appspec. */
+    position: number;
+    cron: string;
+    description: string;
+    /** When it runs next; empty when the scheduler does not say. */
+    nextAt: 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. */
+    inProgress: RecordEntry[];
+    /** Its live deployments' next runs, soonest first. */
+    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[];
+    /** The offset of the next page of completed sessions; `null` after the last. */
+    nextOffset: number | null;
+};
+/** `/apps/activity`'s answer, read. */
+export declare function activityOf(body: Record<string, unknown>): AppActivity;
+/** Pages as one: in progress and scheduled from the first, completed from all, the last page's next offset. */
+export declare function mergeActivityPages(pages: readonly AppActivity[]): AppActivity;
+/** What Activity says, on every client (checked against the vocabulary). */
+export declare const ACTIVITY_WORDS: {
+    readonly inProgress: "In progress";
+    readonly scheduled: "Scheduled";
+    readonly completed: "Completed";
+    readonly working: "Working since";
+    readonly next: "next";
+    readonly wakes: "It also starts on its own when something happens:";
+    readonly nothing: "Nothing yet.";
+};
+/** What happens that starts it on its own, in words (LOOP W-03): its event triggers. */
+export declare const wakesOn: (triggers: ReadonlyArray<{
+    type: string;
+    event?: string;
+    description?: string;
+}> | undefined) => string[];
+/** A scheduled run in words: what it does, and on which version. */
+export declare const scheduledSays: (run: ScheduledRun) => string;

package/lib/portable/activity.js

@@ -0,0 +1,129 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What an application is doing (LOOP 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
+ * and Datalayer Mobile (MOBILE M-015b). Pure: each client fetches with its own
+ * authentication and hands the body here.
+ *
+ * @module portable/activity
+ */
+import { RUN_END_WORDS } from './records';
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const records = (value) => Array.isArray(value) ? value.filter(isRecord) : [];
+const said = (value) => typeof value === 'string' ? value : value == null ? '' : String(value);
+/** An entry as ai-agents answers with it. */
+export function entryOf(raw) {
+    return {
+        uid: said(raw.uid),
+        appUid: said(raw.app_uid),
+        sessionUid: said(raw.session_uid),
+        deploymentUid: said(raw.deployment_uid),
+        version: Number(raw.version) || 0,
+        kind: (said(raw.kind) || 'output'),
+        summary: said(raw.summary),
+        payload: isRecord(raw.payload) ? raw.payload : {},
+        createdAt: said(raw.created_at),
+        purpose: said(raw.purpose),
+    };
+}
+/** How the run an entry ends ended: `answered`, `stopped`, `gone`; `''` for any other entry. */
+export function runEndOf(entry) {
+    const status = entry.kind === 'output' ? entry.payload.status : undefined;
+    return typeof status === 'string' && status in RUN_END_WORDS ? status : '';
+}
+/** An entry in words: its summary, or how its run ended when its words are not kept. */
+export function entrySaid(entry) {
+    return entry.summary || RUN_END_WORDS[runEndOf(entry)] || '';
+}
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+/** A session in a sentence: how many calls, what stopped it, how it ended. */
+export function sessionSentence(entries) {
+    const calls = entries.filter(entry => entry.kind === 'tool_call').length;
+    const checks = entries.filter(entry => entry.kind === 'check');
+    const ends = entries.map(runEndOf).filter(Boolean);
+    const answers = ends.filter(end => end === 'answered').length;
+    const parts = [];
+    parts.push(calls === 0 ? 'No tool called' : plural(calls, 'tool call'));
+    if (checks.length) {
+        parts.push(`${plural(checks.length, 'step')} a check did not let pass`);
+    }
+    const unsent = entries.filter(entry => entry.kind === 'notification' && entry.payload.delivery !== 'sent');
+    if (unsent.length) {
+        parts.push(`${plural(unsent.length, 'notification')} not sent`);
+    }
+    if (ends[ends.length - 1] === 'stopped') {
+        parts.push('stopped');
+    }
+    else if (answers) {
+        parts.push(plural(answers, 'answer'));
+    }
+    return `${parts.join(', ')}.`;
+}
+/** `/apps/activity`'s answer, read. */
+export function activityOf(body) {
+    return {
+        inProgress: records(body.in_progress).map(entryOf),
+        scheduled: records(body.scheduled).map(raw => ({
+            deploymentUid: said(raw.deployment_uid),
+            appUid: said(raw.app_uid),
+            version: Number(raw.version) || 0,
+            position: Number(raw.position) || 0,
+            cron: said(raw.cron),
+            description: said(raw.description),
+            nextAt: said(raw.next_at),
+        })),
+        scheduledProblem: said(body.scheduled_problem),
+        completed: records(body.completed).map(entryOf),
+        nextOffset: typeof body.next_offset === 'number' ? body.next_offset : null,
+    };
+}
+/** Pages as one: in progress and scheduled from the first, completed from all, the last page's next offset. */
+export function mergeActivityPages(pages) {
+    const [first] = pages;
+    if (!first) {
+        return {
+            inProgress: [],
+            scheduled: [],
+            scheduledProblem: '',
+            completed: [],
+            nextOffset: null,
+        };
+    }
+    const seen = new Set();
+    const completed = pages
+        .flatMap(page => page.completed)
+        .filter(entry => {
+        const key = entry.uid || entry.sessionUid;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+    return {
+        ...first,
+        completed,
+        nextOffset: pages[pages.length - 1].nextOffset,
+    };
+}
+/** What Activity says, on every client (checked against the vocabulary). */
+export const ACTIVITY_WORDS = {
+    inProgress: 'In progress',
+    scheduled: 'Scheduled',
+    completed: 'Completed',
+    working: 'Working since',
+    next: 'next',
+    wakes: 'It also starts on its own when something happens:',
+    nothing: 'Nothing yet.',
+};
+/** What happens that starts it on its own, in words (LOOP W-03): its event triggers. */
+export const wakesOn = (triggers) => (triggers ?? [])
+    .filter(trigger => trigger.type === 'event' && (trigger.description || trigger.event))
+    .map(trigger => trigger.description ||
+    `When ${String(trigger.event).replace(/_/g, ' ')}`);
+/** A scheduled run in words: what it does, and on which version. */
+export const scheduledSays = (run) => `${run.description || 'Its schedule'} (${run.cron}) · version ${run.version}`;

package/lib/portable/fixtures.d.ts

@@ -18,3 +18,10 @@ export declare function shieldDisplayFixtures(): {
     terminal: Record<string, unknown>;
 };
 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
+ * next page — what the Studio's Activity and the phone's read alike (MOBILE
+ * M-015b).
+ */
+export declare function activityFixture(): Record<string, unknown>;

package/lib/portable/fixtures.js

@@ -118,3 +118,53 @@ export function conversationFixture() {
         dropped: 3,
     };
 }
+/**
+ * `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
+ * next page — what the Studio's Activity and the phone's read alike (MOBILE
+ * M-015b).
+ */
+export function activityFixture() {
+    return {
+        success: true,
+        in_progress: [
+            {
+                uid: 'e-run',
+                app_uid: 'app-1',
+                session_uid: 's-2',
+                deployment_uid: 'd-1',
+                version: 3,
+                kind: 'run',
+                summary: 'Triage the inbox',
+                payload: {},
+                created_at: '2026-10-16T08:00:00Z',
+            },
+        ],
+        scheduled: [
+            {
+                deployment_uid: 'd-1',
+                app_uid: 'app-1',
+                version: 3,
+                position: 0,
+                cron: '0 8 * * 1-5',
+                description: 'Every weekday morning',
+                next_at: '2026-10-17T08:00:00Z',
+            },
+        ],
+        scheduled_problem: '',
+        completed: [
+            {
+                uid: 'e-out',
+                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',
+            },
+        ],
+        next_offset: 20,
+    };
+}

package/lib/portable/index.d.ts

@@ -16,7 +16,7 @@ export { BROWSER_LIMITS, CUT_MARK, DEVICE_LIMITS, DIAGNOSTIC_LIMIT, emptyConvers
 export { conversationEventsOf, sanitizeAssistantContent, snapshotOfMessages, type AdapterEvent, type SaidMessage, } from './adapterEvents';
 export { PRESENCE_LINES, presenceOfConversation, presenceState, presenceToolOf, type PresenceState, type PresenceTool, } from './presence';
 export { ANSWER_BELOW, ANSWER_COMPLETE, composerOf, droppedWords, ENDED_WORDS, messageLabel, OPENING_WORDS, presenceLine, showsQuestion, stepLine, TOOL_STATUS_WORDS, toolLabel, type ComposerProps, type ComposerState, type ConversationViewProps, type ErrorItem, type ErrorRowProps, type MessageItem, type MessageRowProps, type PresenceLineProps, type ProtocolDisplayProps, type QuestionCardProps, type StepItem, type StepRowProps, type ToolItem, type ToolRowProps, type TurnEndItem, type TurnEndRowProps, } from './views';
-export { conversationFixture } from './fixtures';
+export { activityFixture, conversationFixture } from './fixtures';
 export { DISPLAY_META_KEY, displayLine, displayOfToolResult, PAP_CONFIRM_TYPE, PAP_HANDOFF_TOOL, PAP_OUTCOME_TYPE, PAP_REPLIES_TYPE, PAP_SIGN_IN_TYPE, protocolDisplayOf, replyAuthor, type ActionClass, type ProtocolDisplay, DIFF_LINES_LIMIT, SHIELD_DIFF_TYPE, SHIELD_TERMINAL_TYPE, languageOf, unifiedDiffLines, unifiedDiffText, type DiffLine, } from './displays';
 export { shieldDisplayFixtures } from './fixtures';
 export { isPapSignInTool, PAP_SIGN_IN_WORDS, readPapSignIn, safeSignInUrl, type PapSignInWaiting, } from './signIn';
@@ -24,5 +24,8 @@ 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 { 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';
 export type { ChatMessage } from '../types/messages';

package/lib/portable/index.js

@@ -27,7 +27,7 @@ export { conversationEventsOf, sanitizeAssistantContent, snapshotOfMessages, } f
 export { PRESENCE_LINES, presenceOfConversation, presenceState, presenceToolOf, } from './presence';
 // One contract for every renderer of a conversation's components.
 export { ANSWER_BELOW, ANSWER_COMPLETE, composerOf, droppedWords, ENDED_WORDS, messageLabel, OPENING_WORDS, presenceLine, showsQuestion, stepLine, TOOL_STATUS_WORDS, toolLabel, } from './views';
-export { conversationFixture } from './fixtures';
+export { activityFixture, conversationFixture } from './fixtures';
 // The protocol displays a run's tool results carry (MOBILE M-037).
 export { DISPLAY_META_KEY, displayLine, displayOfToolResult, PAP_CONFIRM_TYPE, PAP_HANDOFF_TOOL, PAP_OUTCOME_TYPE, PAP_REPLIES_TYPE, PAP_SIGN_IN_TYPE, protocolDisplayOf, replyAuthor, 
 // A coding agent's diff and terminal (SHIELD §4.3, SH-16).
@@ -42,5 +42,11 @@ 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 (MOBILE M-036).
 export { failureOf, otlpMetricsOf, RunMeter, } from './runMeasures';
+// What an application is doing, and its record's entries (LOOP R-15, MOBILE M-015b).
+export { ACTIVITY_WORDS, activityOf, entryOf, entrySaid, mergeActivityPages, runEndOf, scheduledSays, sessionSentence, wakesOn, } from './activity';
+// A deployment's pause, resume and reset, and its recorded events (LOOP R-17, MOBILE M-041b).
+export { deploymentEventLine, deploymentEventOf, notDeletedOf, resetBody, resetCountsOf, resetLines, stateChangeBody, stoppedWorkLine, stoppedWorkOf, } from './lifecycle';
+// A person's agent runtimes, and an agent's summary (MOBILE M-014b).
+export { agentRuntimesOf, agentSummaryOfRuntime, CREATING_STATUSES, isAgentRuntime, isCreatingAgent, runtimeOf, } from './runtimes';
 // The runtime's routes a native client drives.
 export { agentRunClient, agentRuntimesUrlOf, appSessionsClient, RuntimeRefusal, } from './sessions';

package/lib/portable/lifecycle.d.ts

@@ -0,0 +1,77 @@
+/**
+ * A deployment's lifecycle as its owner drives it (LOOP R-17, D-04): pause
+ * and resume one exact version, reset what it holds, and the events recorded
+ * with who did each. The requests' bodies, the answers read and the words
+ * said — the same in the Studio and Datalayer Mobile (MOBILE M-041b). Pure:
+ * each client sends them with its own authentication.
+ *
+ * @module portable/lifecycle
+ */
+/** Whether a deployment answers now. */
+export type DeploymentState = 'live' | 'paused';
+/** Pause or resume, for one exact version: `PATCH /apps/deployments/{uid}`'s body. */
+export declare const stateChangeBody: (version: number, state: DeploymentState) => {
+    version: number;
+    state: DeploymentState;
+};
+/** What pausing stopped, and what it could not, with why. */
+export type StoppedWork = {
+    stopped: {
+        what: string;
+        runtime: string;
+    }[];
+    notStopped: {
+        what: string;
+        runtime: string;
+        why: string;
+    }[];
+};
+export declare function stoppedWorkOf(raw: Record<string, unknown>): StoppedWork;
+/** What pausing did, in a sentence. */
+export declare function stoppedWorkLine(work: StoppedWork): string;
+/** What a Reset deletes, counted for its confirmation. */
+export type ResetCounts = {
+    conversations: number;
+    entries: number;
+    schedules: number;
+    /**
+     * Why its memories stay: they are its application's, not the
+     * deployment's (LOOP R-18) — forgotten under *What it remembers*.
+     */
+    memoriesNote: string;
+};
+export declare function resetCountsOf(raw: Record<string, unknown>): ResetCounts;
+/** The Reset confirmed against the counts the person was shown: `POST …/reset`'s body. */
+export declare const resetBody: (counts: Pick<ResetCounts, "conversations" | "schedules">) => {
+    conversations: number;
+    schedules: number;
+};
+/** What a Reset could not delete, with why: `POST …/reset`'s answer. */
+export declare function notDeletedOf(body: Record<string, unknown>): {
+    what: string;
+    why: string;
+}[];
+/**
+ * What goes, as the confirmation lists it — "12 conversations, 2
+ * schedules" — and what does not, said apart.
+ */
+export declare function resetLines(counts: ResetCounts): {
+    goes: string;
+    stays: string[];
+};
+/** What happened to a deployment, recorded with who did it (D-04, R-17). */
+export type DeploymentEventKind = 'promoted' | 'rolled_back' | 'paused' | 'resumed' | 'reset';
+/** Who promoted, rolled back, paused, resumed or reset a deployment, and when. */
+export type DeploymentEvent = {
+    uid: string;
+    kind: DeploymentEventKind;
+    actor: string;
+    at: string;
+    details: Record<string, unknown>;
+};
+export declare function deploymentEventOf(raw: Record<string, unknown>): DeploymentEvent;
+/**
+ * One event, in a line: "Paused by eric, 4 Oct 2026, 10:12", "Rolled back
+ * from version 3 to version 2 by eric, …".
+ */
+export declare function deploymentEventLine(event: DeploymentEvent, locale?: string): string;

package/lib/portable/lifecycle.js

@@ -0,0 +1,135 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Pause or resume, for one exact version: `PATCH /apps/deployments/{uid}`'s body. */
+export const stateChangeBody = (version, state) => {
+    if (!Number.isInteger(version) || version < 1) {
+        throw new Error(`A deployment's state is changed for one exact version: ${String(version)} is none.`);
+    }
+    return { version, state };
+};
+const listOf = (raw) => Array.isArray(raw)
+    ? raw.filter(item => item && typeof item === 'object')
+    : [];
+const said = (value) => typeof value === 'string' ? value : value == null ? '' : String(value);
+const count = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+};
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+export function stoppedWorkOf(raw) {
+    return {
+        stopped: listOf(raw.stopped).map(item => ({
+            what: said(item.what),
+            runtime: said(item.runtime),
+        })),
+        notStopped: listOf(raw.not_stopped).map(item => ({
+            what: said(item.what),
+            runtime: said(item.runtime),
+            why: said(item.why),
+        })),
+    };
+}
+/** What pausing did, in a sentence. */
+export function stoppedWorkLine(work) {
+    const stopped = work.stopped.length;
+    const first = stopped === 0
+        ? 'Paused: nothing was running.'
+        : `Paused: ${plural(stopped, 'session')} in progress stopped.`;
+    if (!work.notStopped.length) {
+        return first;
+    }
+    const missed = work.notStopped
+        .map(item => `${item.what}${item.runtime ? ` (${item.runtime})` : ''}: ${item.why}`)
+        .join(' ');
+    return `${first} Not stopped — ${missed}`;
+}
+export function resetCountsOf(raw) {
+    return {
+        conversations: count(raw.conversations),
+        entries: count(raw.entries),
+        schedules: count(raw.schedules),
+        memoriesNote: typeof raw.memories_note === 'string' ? raw.memories_note : '',
+    };
+}
+/** The Reset confirmed against the counts the person was shown: `POST …/reset`'s body. */
+export const resetBody = (counts) => ({
+    conversations: counts.conversations,
+    schedules: counts.schedules,
+});
+/** What a Reset could not delete, with why: `POST …/reset`'s answer. */
+export function notDeletedOf(body) {
+    return listOf(body.not_deleted).map(item => ({
+        what: said(item.what),
+        why: said(item.why),
+    }));
+}
+/**
+ * What goes, as the confirmation lists it — "12 conversations, 2
+ * schedules" — and what does not, said apart.
+ */
+export function resetLines(counts) {
+    return {
+        goes: [
+            plural(counts.conversations, 'conversation'),
+            plural(counts.schedules, 'schedule'),
+        ].join(', '),
+        stays: [
+            'The deployment, its address and the version it runs stay.',
+            ...(counts.memoriesNote ? [counts.memoriesNote] : []),
+        ],
+    };
+}
+const EVENT_KINDS = [
+    'promoted',
+    'rolled_back',
+    'paused',
+    'resumed',
+    'reset',
+];
+export function deploymentEventOf(raw) {
+    if (!EVENT_KINDS.includes(raw.kind)) {
+        throw new Error(`A deployment's event of no known kind: ${String(raw.kind)}.`);
+    }
+    return {
+        uid: said(raw.uid),
+        kind: raw.kind,
+        actor: said(raw.actor_handle || raw.actor_uid || ''),
+        at: typeof raw.at === 'string' ? raw.at : '',
+        details: raw.details && typeof raw.details === 'object'
+            ? raw.details
+            : {},
+    };
+}
+/**
+ * One event, in a line: "Paused by eric, 4 Oct 2026, 10:12", "Rolled back
+ * from version 3 to version 2 by eric, …".
+ */
+export function deploymentEventLine(event, locale) {
+    const from = count(event.details.from);
+    const to = count(event.details.to);
+    const moved = from && to ? ` from version ${from} to version ${to}` : '';
+    const verb = {
+        promoted: `Promoted${moved}`,
+        rolled_back: `Rolled back${moved}`,
+        paused: 'Paused',
+        resumed: 'Resumed',
+        reset: 'Reset',
+    }[event.kind];
+    const when = event.at
+        ? new Date(event.at).toLocaleString(locale, {
+            dateStyle: 'medium',
+            timeStyle: 'short',
+        })
+        : '';
+    const deleted = event.details.deleted;
+    const what = event.kind === 'reset' && deleted
+        ? ` — ${plural(count(deleted.conversations), 'conversation')} and ${plural(count(deleted.schedules), 'schedule')} deleted`
+        : '';
+    // Paused by an owner of its owner's organization (I-09): said as such.
+    const forOrganization = event.kind === 'paused' && event.details.by === 'organization_owner'
+        ? ', an owner of your organization'
+        : '';
+    return `${verb}${event.actor ? ` by ${event.actor}${forOrganization}` : ''}${when ? `, ${when}` : ''}${what}`;
+}

package/lib/portable/runtimes.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A person's agent runtimes as the runtimes service lists them
+ * (`GET /api/runtimes/v1/runtimes`), and an agent's summary and status as
+ * every client says them — the web's `AgentSummary` badge and Datalayer
+ * Mobile's Agents (MOBILE M-014b). A raw runtime carries no application
+ * capabilities: no Rules, Protocols or Activity are read from it.
+ *
+ * @module portable/runtimes
+ */
+/** One agent runtime, as a client lists it. */
+export type AgentRuntime = {
+    uid: string;
+    runtimeName: string;
+    givenName: string;
+    environment: string;
+    /** The agentspec it runs, when the runtime says. */
+    agentSpecId: string;
+    type: string;
+    state: string;
+    startedAt: string;
+    expiredAt: string;
+    /** Its Jupyter address, from which its agents' is read (`agentRuntimesUrlOf`). */
+    ingress: string;
+};
+/** A runtime of the runtimes service's answer. */
+export declare function runtimeOf(raw: Record<string, unknown>): AgentRuntime;
+/** The runtimes service's list, agent runtimes only: notebooks and terminals belong to the web workspace. */
+export declare function agentRuntimesOf(body: Record<string, unknown>): AgentRuntime[];
+/** An agent runtime, not a notebook's or a terminal's. */
+export declare const isAgentRuntime: (runtime: AgentRuntime) => boolean;
+/** What a summary of an agent says of it. */
+export interface AgentSummaryData {
+    agentName: string;
+    location: string;
+    specId?: string;
+    /**
+     * The framework turning this agent's loop, as its spec declares it —
+     * `pydantic-ai` server-side, `vercel-ai` in the page.
+     */
+    harness?: string;
+    /**
+     * The runtime variant the host chose: `<location>-<harness>`.
+     *
+     * Shown next to the harness rather than instead of it, because they answer
+     * different questions and can disagree: the harness is what the spec asked
+     * for, the variant is what it actually got.
+     */
+    variant?: string;
+    status?: string;
+    baseUrl?: string;
+    sandboxBaseUrl?: string;
+    agentId?: string;
+    isReady?: boolean;
+    error?: string;
+}
+/**
+ * Statuses that represent an agent actively being created/started. The spinner
+ * only shows for these; app-navigation states ("selected", "switching") and
+ * settled states ("ready", "running", ...) never spin.
+ */
+export declare const CREATING_STATUSES: ReadonlySet<string>;
+/**
+ * An agent genuinely being created: it is not ready, has no id yet, and its
+ * status is one of creation or startup.
+ */
+export declare function isCreatingAgent(summary: AgentSummaryData): boolean;
+/** The summary of an agent the runtimes service lists: named as given, at Datalayer. */
+export declare function agentSummaryOfRuntime(runtime: AgentRuntime): AgentSummaryData;

package/lib/portable/runtimes.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const text = (value) => typeof value === 'string' ? value : '';
+/** A runtime of the runtimes service's answer. */
+export function runtimeOf(raw) {
+    const environment = isRecord(raw.environment) ? raw.environment : {};
+    return {
+        uid: text(raw.uid),
+        runtimeName: text(raw.runtime_name) || text(raw.pod_name),
+        givenName: text(raw.given_name),
+        environment: text(environment.title) ||
+            text(environment.name) ||
+            text(raw.environment_title) ||
+            text(raw.environment_name),
+        agentSpecId: text(raw.agent_spec_id) || text(raw.attached_agent_spec_id_s),
+        type: text(raw.type),
+        state: text(raw.state) || text(raw.status) || 'running',
+        startedAt: text(raw.started_at),
+        expiredAt: text(raw.expired_at),
+        ingress: text(raw.ingress),
+    };
+}
+/** The runtimes service's list, agent runtimes only: notebooks and terminals belong to the web workspace. */
+export function agentRuntimesOf(body) {
+    const listed = Array.isArray(body.runtimes) ? body.runtimes : [];
+    return listed
+        .filter(isRecord)
+        .map(runtimeOf)
+        .filter(runtime => runtime.runtimeName && isAgentRuntime(runtime));
+}
+/** An agent runtime, not a notebook's or a terminal's. */
+export const isAgentRuntime = (runtime) => runtime.type === 'agent' ||
+    Boolean(runtime.agentSpecId) ||
+    /agent/i.test(runtime.environment);
+/**
+ * Statuses that represent an agent actively being created/started. The spinner
+ * only shows for these; app-navigation states ("selected", "switching") and
+ * settled states ("ready", "running", ...) never spin.
+ */
+export const CREATING_STATUSES = new Set([
+    'creating',
+    'starting',
+    'launching',
+    'connecting',
+    'pending',
+    'resuming',
+]);
+/**
+ * An agent genuinely being created: it is not ready, has no id yet, and its
+ * status is one of creation or startup.
+ */
+export function isCreatingAgent(summary) {
+    return (!summary.isReady &&
+        !summary.agentId &&
+        CREATING_STATUSES.has((summary.status || '').toLowerCase()));
+}
+/** The summary of an agent the runtimes service lists: named as given, at Datalayer. */
+export function agentSummaryOfRuntime(runtime) {
+    return {
+        agentName: runtime.givenName || runtime.runtimeName,
+        location: 'datalayer',
+        specId: runtime.agentSpecId || undefined,
+        status: runtime.state,
+        isReady: !CREATING_STATUSES.has(runtime.state.toLowerCase()),
+    };
+}