@datalayer/agent-runtimes 1.5.22 → 1.5.24

package/lib/chat/presence/Presence.d.ts

@@ -9,7 +9,8 @@
  * @module chat/presence/Presence
  */
 import type { ReactNode } from 'react';
-import { type PresenceState } from './presenceStatus';
+import { type PresenceLineProps } from '../../portable/views';
+import type { PresenceState } from './presenceStatus';
 /**
  * A face at `size`: an emoji drawn in Fluent Emoji, the same on every
  * platform (LOOP T-20) — the system's, as text, only for one Datalayer ships
@@ -28,6 +29,5 @@ export declare function PresenceFace({ face, size, state, }: {
     size: number;
     state: PresenceState;
 }): import("react").JSX.Element;
-export declare function PresenceLine({ state }: {
-    state: PresenceState;
-}): import("react").JSX.Element;
+/** The line beside its face: `portable/views`' contract, as Datalayer Mobile draws it too. */
+export declare function PresenceLine({ state }: PresenceLineProps): import("react").JSX.Element;

package/lib/chat/presence/Presence.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Box } from '@datalayer/primer-addons';
 import { Text } from '@primer/react';
 import { FluentEmoji } from '@datalayer/core/lib/components/emoji';
-import { PRESENCE_LINES } from './presenceStatus';
+import { presenceLine } from '../../portable/views';
 const ACCENT = 'var(--theme-accent)';
 /**
  * A face at `size`: an emoji drawn in Fluent Emoji, the same on every
@@ -22,6 +22,7 @@ export function PresenceFace({ face, size, state, }) {
                     },
                 } }), _jsx(Box, { as: "span", display: "inline-flex", opacity: paused ? 0.55 : 1, filter: paused ? 'grayscale(0.6)' : 'none', transition: "opacity var(--theme-motion-status, 0ms) var(--theme-motion-easing, ease)", children: _jsx(FaceDrawing, { face: face, size: size }) })] }));
 }
+/** The line beside its face: `portable/views`' contract, as Datalayer Mobile draws it too. */
 export function PresenceLine({ state }) {
     return (_jsx(Text, { role: "status", "aria-live": "polite", "data-presence-line": state, sx: {
             fontSize: 0,
@@ -29,5 +30,5 @@ export function PresenceLine({ state }) {
             fontWeight: state === 'waiting' ? 'semibold' : 'normal',
             whiteSpace: 'nowrap',
             flexShrink: 0,
-        }, children: PRESENCE_LINES[state] }));
+        }, children: presenceLine({ state }) }));
 }

package/lib/chat/presence/presenceStatus.d.ts

@@ -1,38 +1,7 @@
 /**
- * What an application is doing, in plain words (LOOP T-08): the one line of
- * status beside its face.
+ * What an application is doing, in plain words (LOOP T-08): kept in
+ * `portable/presence`, which Datalayer Mobile reads too (MOBILE M-030).
  *
  * @module chat/presence/presenceStatus
  */
-/**
- * The states a person is told about. Paused is its deployment's: its owner
- * paused it (LOOP R-17), and it answers nobody until it is resumed.
- */
-export type PresenceState = 'idle' | 'thinking' | 'working' | 'waiting' | 'paused';
-/** The line each state is said by. */
-export declare const PRESENCE_LINES: Record<PresenceState, string>;
-/** The newest tool call of the conversation, as far as presence reads it. */
-export interface PresenceTool {
-    /** It has not returned. */
-    open: boolean;
-    /** It waits on a person's approval. */
-    pendingApproval: boolean;
-}
-/**
- * The state, from whether a turn is running, the newest tool call, and
- * whether its deployment is paused.
- *
- * Paused wins: a paused application does nothing, whatever its last turn
- * left behind.
- * Waiting for an approval is said whether or not the turn is still
- * streaming — the stream may end while the approval is asked. A tool that
- * has not returned counts as work only during a turn: a stopped turn can
- * leave one open, and the application is not working then.
- */
-export declare function presenceState(busy: boolean, tool?: PresenceTool, paused?: boolean): PresenceState;
-/**
- * The newest tool call of the conversation: whether it has not returned, and
- * whether it waits on a person's approval. A tool call is an item with a
- * tool name and a call id; it has returned once it is complete or failed.
- */
-export declare function presenceToolOf(items: readonly unknown[]): PresenceTool;
+export { PRESENCE_LINES, presenceOfConversation, presenceState, presenceToolOf, type PresenceState, type PresenceTool, } from '../../portable/presence';

package/lib/chat/presence/presenceStatus.js

@@ -2,52 +2,10 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/** The line each state is said by. */
-export const PRESENCE_LINES = {
-    idle: 'Ready',
-    thinking: 'Thinking…',
-    working: 'Working…',
-    waiting: 'Waiting for you',
-    paused: 'Paused',
-};
 /**
- * The state, from whether a turn is running, the newest tool call, and
- * whether its deployment is paused.
+ * What an application is doing, in plain words (LOOP T-08): kept in
+ * `portable/presence`, which Datalayer Mobile reads too (MOBILE M-030).
  *
- * Paused wins: a paused application does nothing, whatever its last turn
- * left behind.
- * Waiting for an approval is said whether or not the turn is still
- * streaming — the stream may end while the approval is asked. A tool that
- * has not returned counts as work only during a turn: a stopped turn can
- * leave one open, and the application is not working then.
+ * @module chat/presence/presenceStatus
  */
-export function presenceState(busy, tool, paused = false) {
-    if (paused) {
-        return 'paused';
-    }
-    if (tool?.open && tool.pendingApproval) {
-        return 'waiting';
-    }
-    if (!busy) {
-        return 'idle';
-    }
-    return tool?.open ? 'working' : 'thinking';
-}
-/**
- * The newest tool call of the conversation: whether it has not returned, and
- * whether it waits on a person's approval. A tool call is an item with a
- * tool name and a call id; it has returned once it is complete or failed.
- */
-export function presenceToolOf(items) {
-    for (let index = items.length - 1; index >= 0; index -= 1) {
-        const item = items[index];
-        if (typeof item.toolName === 'string' && item.toolCallId) {
-            const open = item.status !== 'complete' && item.status !== 'error';
-            const pendingApproval = open &&
-                item.result
-                    ?.pending_approval === true;
-            return { open, pendingApproval };
-        }
-    }
-    return { open: false, pendingApproval: false };
-}
+export { PRESENCE_LINES, presenceOfConversation, presenceState, presenceToolOf, } from '../../portable/presence';

package/lib/portable/fixtures.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A conversation with one row of every kind, and a question waiting: the
+ * fixture every renderer of `portable/views` is tested against — the web's
+ * and Datalayer Mobile's (MOBILE §4.2) — so that a change of a row's words or
+ * states is caught once.
+ *
+ * @module portable/fixtures
+ */
+import { type ConversationState } from './conversation';
+/** A fresh copy of the fixture conversation. */
+export declare function conversationFixture(): ConversationState;

package/lib/portable/fixtures.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A conversation with one row of every kind, and a question waiting: the
+ * fixture every renderer of `portable/views` is tested against — the web's
+ * and Datalayer Mobile's (MOBILE §4.2) — so that a change of a row's words or
+ * states is caught once.
+ *
+ * @module portable/fixtures
+ */
+import { emptyConversation } from './conversation';
+import { RUN_END_WORDS } from './records';
+/** A fresh copy of the fixture conversation. */
+export function conversationFixture() {
+    return {
+        ...emptyConversation(),
+        items: [
+            {
+                kind: 'message',
+                id: 'm-1',
+                role: 'user',
+                text: 'Where is order 7?',
+                streaming: false,
+            },
+            {
+                kind: 'tool',
+                id: 't-1',
+                name: 'lookup_order',
+                args: '{"order":7}',
+                status: 'complete',
+                result: 'Shipped on Monday.',
+                error: '',
+            },
+            {
+                kind: 'tool',
+                id: 't-2',
+                name: 'send_mail',
+                args: '{}',
+                status: 'error',
+                result: '',
+                error: 'Refused by its rule.',
+            },
+            {
+                kind: 'step',
+                id: 's-1',
+                name: 'Check the carrier',
+                status: 'complete',
+            },
+            {
+                kind: 'message',
+                id: 'm-2',
+                role: 'assistant',
+                text: 'It **shipped** on Monday.',
+                streaming: false,
+            },
+            { kind: 'end', id: 'e-1', end: 'stopped', words: RUN_END_WORDS.stopped },
+            { kind: 'error', id: 'x-1', text: 'The runtime did not answer.' },
+        ],
+        asking: {
+            kind: 'choice',
+            prompt: 'Track it by mail?',
+            options: ['Yes', 'No'],
+            schema: null,
+            accept: [],
+        },
+        dropped: 3,
+    };
+}

package/lib/portable/index.d.ts

@@ -12,5 +12,8 @@ export { AG_UI_NOT_ALLOWED, AG_UI_NOT_ON_RUNTIME, agUiRefusal, refusalBody, refu
 export { ASKED_FOR_TAG, askedOf, RUN_END_WORDS } from './records';
 export { messagesOfThread, openThread, snapshotOfStream, THREAD_WORDS, } from './thread';
 export { CUT_MARK, DIAGNOSTIC_LIMIT, emptyConversation, formFieldsOf, ITEM_LIMIT, MESSAGE_TEXT_LIMIT, questionOf, questionWords, reduceConversation, TOOL_TEXT_LIMIT, withError, withPrompt, withTurnEnded, type ConversationItem, type ConversationQuestion, type ConversationState, type TurnEnd, } from './conversation';
+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 QuestionCardProps, type StepItem, type StepRowProps, type ToolItem, type ToolRowProps, type TurnEndItem, type TurnEndRowProps, } from './views';
+export { conversationFixture } from './fixtures';
 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

@@ -19,5 +19,10 @@ export { ASKED_FOR_TAG, askedOf, RUN_END_WORDS } from './records';
 export { messagesOfThread, openThread, snapshotOfStream, THREAD_WORDS, } from './thread';
 // A conversation as its stream builds it, for a native client.
 export { CUT_MARK, DIAGNOSTIC_LIMIT, emptyConversation, formFieldsOf, ITEM_LIMIT, MESSAGE_TEXT_LIMIT, questionOf, questionWords, reduceConversation, TOOL_TEXT_LIMIT, withError, withPrompt, withTurnEnded, } from './conversation';
+// What an application is doing, in the words beside its face (LOOP T-08).
+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';
 // The runtime's routes a native client drives.
 export { agentRunClient, agentRuntimesUrlOf, appSessionsClient, RuntimeRefusal, } from './sessions';

package/lib/portable/presence.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What an application is doing, in plain words (LOOP T-08): the one line of
+ * status beside its face — the same states and words in the web chat
+ * (`chat/presence`) and on Datalayer Mobile (MOBILE M-030).
+ *
+ * @module portable/presence
+ */
+import type { ConversationState } from './conversation';
+/**
+ * The states a person is told about. Paused is its deployment's: its owner
+ * paused it (LOOP R-17), and it answers nobody until it is resumed.
+ */
+export type PresenceState = 'idle' | 'thinking' | 'working' | 'waiting' | 'paused';
+/** The line each state is said by. */
+export declare const PRESENCE_LINES: Record<PresenceState, string>;
+/** The newest tool call of the conversation, as far as presence reads it. */
+export interface PresenceTool {
+    /** It has not returned. */
+    open: boolean;
+    /** It waits on a person's approval. */
+    pendingApproval: boolean;
+}
+/**
+ * The state, from whether a turn is running, the newest tool call, and
+ * whether its deployment is paused.
+ *
+ * Paused wins: a paused application does nothing, whatever its last turn
+ * left behind.
+ * Waiting for an approval is said whether or not the turn is still
+ * streaming — the stream may end while the approval is asked. A tool that
+ * has not returned counts as work only during a turn: a stopped turn can
+ * leave one open, and the application is not working then.
+ */
+export declare function presenceState(busy: boolean, tool?: PresenceTool, paused?: boolean): PresenceState;
+/**
+ * The newest tool call of the conversation: whether it has not returned, and
+ * whether it waits on a person's approval. A tool call is an item with a
+ * tool name and a call id; it has returned once it is complete or failed.
+ */
+export declare function presenceToolOf(items: readonly unknown[]): PresenceTool;
+/**
+ * The state of a conversation a native client holds (`reduceConversation`):
+ * from whether its turn streams, its newest tool call, the question its
+ * application waits on, and whether its deployment is paused. A question
+ * asked and not answered is waiting for the person, as an approval is.
+ */
+export declare function presenceOfConversation(state: Pick<ConversationState, 'items' | 'running' | 'asking'>, paused?: boolean): PresenceState;

package/lib/portable/presence.js

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The line each state is said by. */
+export const PRESENCE_LINES = {
+    idle: 'Ready',
+    thinking: 'Thinking…',
+    working: 'Working…',
+    waiting: 'Waiting for you',
+    paused: 'Paused',
+};
+/**
+ * The state, from whether a turn is running, the newest tool call, and
+ * whether its deployment is paused.
+ *
+ * Paused wins: a paused application does nothing, whatever its last turn
+ * left behind.
+ * Waiting for an approval is said whether or not the turn is still
+ * streaming — the stream may end while the approval is asked. A tool that
+ * has not returned counts as work only during a turn: a stopped turn can
+ * leave one open, and the application is not working then.
+ */
+export function presenceState(busy, tool, paused = false) {
+    if (paused) {
+        return 'paused';
+    }
+    if (tool?.open && tool.pendingApproval) {
+        return 'waiting';
+    }
+    if (!busy) {
+        return 'idle';
+    }
+    return tool?.open ? 'working' : 'thinking';
+}
+/**
+ * The newest tool call of the conversation: whether it has not returned, and
+ * whether it waits on a person's approval. A tool call is an item with a
+ * tool name and a call id; it has returned once it is complete or failed.
+ */
+export function presenceToolOf(items) {
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        const item = items[index];
+        if (typeof item.toolName === 'string' && item.toolCallId) {
+            const open = item.status !== 'complete' && item.status !== 'error';
+            const pendingApproval = open &&
+                item.result
+                    ?.pending_approval === true;
+            return { open, pendingApproval };
+        }
+    }
+    return { open: false, pendingApproval: false };
+}
+/**
+ * The state of a conversation a native client holds (`reduceConversation`):
+ * from whether its turn streams, its newest tool call, the question its
+ * application waits on, and whether its deployment is paused. A question
+ * asked and not answered is waiting for the person, as an approval is.
+ */
+export function presenceOfConversation(state, paused = false) {
+    let tool;
+    for (let index = state.items.length - 1; index >= 0; index -= 1) {
+        const item = state.items[index];
+        if (item.kind === 'tool') {
+            tool = { open: item.status === 'running', pendingApproval: false };
+            break;
+        }
+    }
+    const said = presenceState(state.running, tool, paused);
+    return said === 'idle' && state.asking ? 'waiting' : said;
+}

package/lib/portable/views.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The conversation's components, as one contract for every renderer (MOBILE
+ * §4.1–4.2, M-032): the props each one takes, and what each says — to the
+ * eye and to a screen reader — computed here once, so that a native renderer
+ * (Datalayer Mobile's `.native` views) and the web's draw the same rows with
+ * the same words and states, over `reduceConversation`'s state.
+ *
+ * A renderer owns its markup and its look, never these words, these states or
+ * the rule of when a person may type.
+ *
+ * @module portable/views
+ */
+import type { ConversationItem, ConversationQuestion, ConversationState } from './conversation';
+import { type PresenceState } from './presence';
+export type MessageItem = Extract<ConversationItem, {
+    kind: 'message';
+}>;
+export type ToolItem = Extract<ConversationItem, {
+    kind: 'tool';
+}>;
+export type StepItem = Extract<ConversationItem, {
+    kind: 'step';
+}>;
+export type TurnEndItem = Extract<ConversationItem, {
+    kind: 'end';
+}>;
+export type ErrorItem = Extract<ConversationItem, {
+    kind: 'error';
+}>;
+/** A message: the person's words as they are, an answer through the safe Markdown subset. */
+export type MessageRowProps = {
+    item: MessageItem;
+};
+/** A tool call, collapsed until the person opens it. */
+export type ToolRowProps = {
+    item: ToolItem;
+    expanded: boolean;
+    onToggle: () => void;
+};
+/** A step of the application's code. */
+export type StepRowProps = {
+    item: StepItem;
+};
+/** How a turn that said nothing ended. */
+export type TurnEndRowProps = {
+    item: TurnEndItem;
+};
+/** A failure, announced. */
+export type ErrorRowProps = {
+    item: ErrorItem;
+};
+/** What the application waits for the person to answer (`loop.ask`). */
+export type QuestionCardProps = {
+    question: ConversationQuestion;
+    busy: boolean;
+    /** A choice, or words, answered by a message. */
+    onChoose: (option: string) => void;
+    /** A form, answered by a settings change. */
+    onForm: (values: Record<string, unknown>) => void;
+};
+/** The line beside the application's face. */
+export type PresenceLineProps = {
+    state: PresenceState;
+};
+/** The message box and its one button: Send, or Stop while a turn streams. */
+export type ComposerProps = ComposerState & {
+    draft: string;
+    onDraft: (draft: string) => void;
+    onSend: () => void;
+    onStop: () => void;
+};
+/** A whole conversation: its state and what the person can do to it. */
+export type ConversationViewProps = {
+    state: ConversationState;
+    /** It is being read from the server. */
+    opening: boolean;
+    /** It was ended; its record stays. */
+    ended: boolean;
+    /** Why nothing can be sent, when nothing can (paused, closed). */
+    closed?: string;
+    placeholder: string;
+    onSend: (words: string) => void;
+    onStop: () => void;
+    onForm: (values: Record<string, unknown>) => void;
+};
+/** A tool call's state, in words. */
+export declare const TOOL_STATUS_WORDS: Record<ToolItem['status'], string>;
+/** Said while a conversation is read from the server. */
+export declare const OPENING_WORDS = "Opening your conversation\u2026";
+/** Said once an answer is complete — once, never token by token. */
+export declare const ANSWER_COMPLETE = "The answer is complete.";
+/** Said in place of the message box of an ended conversation. */
+export declare const ENDED_WORDS = "This conversation has ended. Its record stays.";
+/** Said under a question answered in the message box. */
+export declare const ANSWER_BELOW = "Answer in the message box below.";
+/** What a message says to a screen reader: whose, and its words. */
+export declare const messageLabel: (item: MessageItem) => string;
+/** A tool call's one line: its name and its state. */
+export declare const toolLabel: (item: ToolItem) => string;
+/** A step's one line: running or done, and its name. */
+export declare const stepLine: (item: StepItem) => string;
+/** Said of the oldest rows a device did not keep, or nothing. */
+export declare const droppedWords: (dropped: number) => string;
+/** The line of a presence state. */
+export declare const presenceLine: ({ state }: PresenceLineProps) => string;
+/** Whether the person may type, why not, and what the box says. */
+export type ComposerState = {
+    /** Why nothing can be sent; `''` when something can. */
+    blocked: string;
+    canType: boolean;
+    /** A turn is streaming: the button is Stop. */
+    running: boolean;
+    placeholder: string;
+};
+/**
+ * The message box, from the conversation: closed or ended, nothing is sent;
+ * while it opens or a turn streams, nothing is typed; a form or a file
+ * question is answered elsewhere; a text question puts its prompt in the box.
+ */
+export declare function composerOf({ state, opening, ended, closed, placeholder, running, }: Pick<ConversationViewProps, 'state' | 'opening' | 'ended' | 'closed' | 'placeholder'> & {
+    /** A turn is running, as its client knows it before its first event. */
+    running?: boolean;
+}): ComposerState;
+/** Whether the question card is shown: asked, and no turn streaming. */
+export declare const showsQuestion: (state: ConversationState, running?: boolean) => boolean;

package/lib/portable/views.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { PRESENCE_LINES } from './presence';
+/** A tool call's state, in words. */
+export const TOOL_STATUS_WORDS = {
+    running: 'running',
+    complete: 'done',
+    error: 'failed',
+};
+/** Said while a conversation is read from the server. */
+export const OPENING_WORDS = 'Opening your conversation…';
+/** Said once an answer is complete — once, never token by token. */
+export const ANSWER_COMPLETE = 'The answer is complete.';
+/** Said in place of the message box of an ended conversation. */
+export const ENDED_WORDS = 'This conversation has ended. Its record stays.';
+/** Said under a question answered in the message box. */
+export const ANSWER_BELOW = 'Answer in the message box below.';
+/** What a message says to a screen reader: whose, and its words. */
+export const messageLabel = (item) => `${item.role === 'user' ? 'You' : 'Answer'}: ${item.text}`;
+/** A tool call's one line: its name and its state. */
+export const toolLabel = (item) => `Tool ${item.name || 'call'}, ${TOOL_STATUS_WORDS[item.status]}`;
+/** A step's one line: running or done, and its name. */
+export const stepLine = (item) => `${item.status === 'running' ? '…' : '✓'} ${item.name}`;
+/** Said of the oldest rows a device did not keep, or nothing. */
+export const droppedWords = (dropped) => dropped > 0
+    ? `${dropped} earlier ${dropped === 1 ? 'row is' : 'rows are'} not kept on this device.`
+    : '';
+/** The line of a presence state. */
+export const presenceLine = ({ state }) => PRESENCE_LINES[state];
+/**
+ * The message box, from the conversation: closed or ended, nothing is sent;
+ * while it opens or a turn streams, nothing is typed; a form or a file
+ * question is answered elsewhere; a text question puts its prompt in the box.
+ */
+export function composerOf({ state, opening, ended, closed, placeholder, running = state.running, }) {
+    const blocked = closed || (ended ? ENDED_WORDS : '');
+    const asking = state.asking;
+    return {
+        blocked,
+        running,
+        canType: !blocked &&
+            !opening &&
+            !running &&
+            asking?.kind !== 'form' &&
+            asking?.kind !== 'file',
+        placeholder: asking?.kind === 'text' ? asking.prompt : placeholder,
+    };
+}
+/** Whether the question card is shown: asked, and no turn streaming. */
+export const showsQuestion = (state, running = state.running) => Boolean(state.asking) && !running;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.5.22",
+    "version": "1.5.24",
     "type": "module",
     "workspaces": [
         ".",