@datalayer/agent-runtimes 1.5.83 → 1.5.85

package/lib/apps/apps/appspec.js

@@ -36,6 +36,7 @@ export const APP_THEME_VARIANTS = [
     'ivory',
     'sun',
     'loop',
+    'vscode',
 ];
 /** The colour modes a theme is worn in. */
 export const APP_THEME_MODES = ['light', 'dark', 'auto'];

package/lib/chat/base/ChatBase.js

@@ -39,7 +39,7 @@ import { AI_MODEL_CATALOGUE, DEFAULT_MODEL, isChatModel, } from '../../specs/mod
 import { internalQueryClient, isToolCallMessage, getMessageText, createProtocolAdapter, getApiBaseFromConfig, sanitizeAssistantContent, } from '../../utils/index.js';
 import { BROWSER_LIMITS, emptyConversation, HARNESS_TOOL_CALL, reduceConversation, withError, withoutItems, withPrompt, withTurnEnded, } from '../../portable/conversation.js';
 import { conversationEventsOf, snapshotOfMessages, } from '../../portable/adapterEvents.js';
-import { conversationDrawer, emptyChatLayer, rowIdOf, toolCallOf, } from './conversationItems.js';
+import { conversationDrawer, emptyChatLayer, rowIdOf, toolCallOf, withToolSummaries, } from './conversationItems.js';
 import { useConfig, useSkills, useSkillActions, useContextSnapshot, useSandbox, } from '../../hooks/index.js';
 import { useAgentRuntimeWebSocket } from '../../hooks/useAgentRuntimes.js';
 import { agentRuntimeStore, useAgentRuntimeStore, useAgentRuntimeWsState, } from '../../stores/agentRuntimeStore.js';
@@ -1163,7 +1163,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     const chatTextRef = useRef(chatText);
     chatTextRef.current = chatText;
     const drawConversation = useMemo(() => conversationDrawer(text => chatTextRef.current.error(text)), []);
-    const displayItems = useMemo(() => drawConversation(conversation, layer), [drawConversation, conversation, layer]);
+    const displayItems = useMemo(() => withToolSummaries(drawConversation(conversation, layer), frontendTools), [drawConversation, conversation, layer, frontendTools]);
     const displayItemsRef = useRef(displayItems);
     displayItemsRef.current = displayItems;
     /*

package/lib/chat/base/conversationItems.d.ts

@@ -16,6 +16,7 @@ import type { Display } from '@datalayer/reactor/ui';
 import type { ConversationItem, ConversationState } from '../../portable/conversation';
 import type { DisplayItem, DisplayToolCallStatus, ToolCallMessage } from '../../types/chat';
 import type { ChatMessage, MessageSpeaker } from '../../types/messages';
+import type { FrontendToolDefinition } from '../../types/tools';
 type ToolItem = Extract<ConversationItem, {
     kind: 'tool';
 }>;
@@ -46,6 +47,12 @@ export declare const rowIdOf: (item: DisplayItem) => string;
 export declare function cardStatusOf(item: ToolItem): DisplayToolCallStatus;
 /** A tool call as its card draws it. */
 export declare function toolCallOf(item: ToolItem): ToolCallMessage;
+/**
+ * The cards of the page's own tools, with what each says of its call
+ * (`summaryOf`) once it returned. A card nothing changes is the one drawn,
+ * so React leaves it as it was.
+ */
+export declare function withToolSummaries(items: DisplayItem[], tools?: readonly Pick<FrontendToolDefinition, 'name' | 'summaryOf'>[]): DisplayItem[];
 /**
  * A drawer of a conversation: each row drawn once, and drawn again only when
  * it, or what the web holds beside it, changed — so a message streaming

package/lib/chat/base/conversationItems.js

@@ -2,6 +2,7 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+import { isToolCallMessage } from '../../utils/index.js';
 export const emptyChatLayer = () => ({
     extras: new Map(),
     displays: new Map(),
@@ -52,6 +53,35 @@ export function toolCallOf(item) {
         ...(item.exitCode !== null ? { exitCode: item.exitCode } : {}),
     };
 }
+/**
+ * The cards of the page's own tools, with what each says of its call
+ * (`summaryOf`) once it returned. A card nothing changes is the one drawn,
+ * so React leaves it as it was.
+ */
+export function withToolSummaries(items, tools = []) {
+    const summarizing = tools.filter(tool => tool.summaryOf);
+    if (summarizing.length === 0) {
+        return items;
+    }
+    let changed = false;
+    const said = items.map(item => {
+        if (!isToolCallMessage(item)) {
+            return item;
+        }
+        const call = item;
+        const tool = summarizing.find(entry => entry.name === call.toolName);
+        if (!tool?.summaryOf || call.result === undefined) {
+            return item;
+        }
+        const summary = tool.summaryOf(call.args, call.result)?.trim();
+        if (!summary || summary === call.summary) {
+            return item;
+        }
+        changed = true;
+        return { ...call, summary };
+    });
+    return changed ? said : items;
+}
 /**
  * A drawer of a conversation: each row drawn once, and drawn again only when
  * it, or what the web holds beside it, changed — so a message streaming

package/lib/portable/hosts/contracts.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 /**
- * The generic Datalayer host contracts, as ai-agents answers them, for every chat host (Slack, Discord).
+ * The generic Datalayer host contracts, as ai-agents answers them, for every chat host (Slack, Discord, WhatsApp).
  * These shapes are shared with ai-agents through `contracts.json`, beside
  * this file and byte-identical to ai-agents' `tests/fixtures/hosts/`, which
  * both sides test. A delivery's `target` stays opaque here: each host

package/lib/portable/hosts/contracts.js

@@ -5,7 +5,7 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import { z } from 'zod';
 /**
- * The generic Datalayer host contracts, as ai-agents answers them, for every chat host (Slack, Discord).
+ * The generic Datalayer host contracts, as ai-agents answers them, for every chat host (Slack, Discord, WhatsApp).
  * These shapes are shared with ai-agents through `contracts.json`, beside
  * this file and byte-identical to ai-agents' `tests/fixtures/hosts/`, which
  * both sides test. A delivery's `target` stays opaque here: each host

package/lib/portable/hosts/contracts.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "about": "The generic host contracts of the chat hosts, as ai-agents and the runtime's session API answer them. Shared verbatim by ai-agents (tests/fixtures/hosts) and agent-runtimes (src/portable/hosts, read by the Slack and Discord adapters from lib/portable/hosts): each side's tests check its half against this file.",
+  "about": "The generic host contracts of the chat hosts, as ai-agents and the runtime's session API answer them. Shared verbatim by ai-agents (tests/fixtures/hosts) and agent-runtimes (src/portable/hosts, read by the Slack, Discord and WhatsApp adapters from lib/portable/hosts): each side's tests check its half against this file.",
   "headers": {
     "host_key": "X-Datalayer-Host-Key",
     "signature": "X-Datalayer-Signature",
@@ -493,5 +493,63 @@
       "threadId": "456789012345678901",
       "userId": "567890123456789012"
     }
+  },
+  "whatsapp": {
+    "about": "WhatsApp's forms of the generic contracts: the installation is <waba_id>:<phone_number_id>, one per connected business number; a person is their business-scoped user id (BSUID: a country code, a period and up to 128 characters; never the phone number), which the external id pattern admits as it is, no hash in between; a 1:1 chat is a direct place named by the BSUID, a group a channel named by its group id; the session uid is hostSessionUid(\"whatsapp\", [waba_id, phone_number_id, user_id]) for a chat and [waba_id, phone_number_id, group_id] for a group; a turn's provenance names the message by its wamid.",
+    "waba_id": "102290129340398",
+    "phone_number_id": "106540352242922",
+    "bind_request": {
+      "code": "dlhc_…",
+      "external_id": "102290129340398:106540352242922",
+      "name": "Acme"
+    },
+    "external_user_id": "US.13491208655302741918",
+    "external_user_name": "Alice",
+    "external_user_id_longest": "US.11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
+    "direct": {
+      "place": {
+        "kind": "direct",
+        "id": "US.13491208655302741918"
+      }
+    },
+    "group": {
+      "id": "120363025246125486",
+      "place": {
+        "kind": "channel",
+        "id": "120363025246125486"
+      }
+    },
+    "session": {
+      "parts": [
+        "102290129340398",
+        "106540352242922",
+        "US.13491208655302741918"
+      ],
+      "uid": "whatsapp-870e7e8165519947ec9c7df03d378b342cee380e"
+    },
+    "group_session": {
+      "parts": [
+        "102290129340398",
+        "106540352242922",
+        "120363025246125486"
+      ],
+      "uid": "whatsapp-49aeadff03b2d02e6359121f9a55bae904640b35"
+    },
+    "provenance": {
+      "host_kind": "whatsapp",
+      "place": {
+        "kind": "direct",
+        "id": "US.13491208655302741918"
+      },
+      "message_id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQzQUY3RjU0QjRFRjc2MzBCNkJCNAA="
+    },
+    "target": {
+      "phoneNumberId": "106540352242922",
+      "userId": "US.13491208655302741918"
+    },
+    "group_target": {
+      "phoneNumberId": "106540352242922",
+      "groupId": "120363025246125486"
+    }
   }
 }

package/lib/portable/hosts/forbiddenGraph.js

@@ -26,6 +26,7 @@ export const FORBIDDEN = [
     /^@datalayer\/reactor$/,
     /^@datalayer\/slack$/,
     /^@datalayer\/discord$/,
+    /^@datalayer\/whatsapp$/,
 ];
 export const isForbidden = (name) => FORBIDDEN.some(pattern => pattern.test(name));
 /** The package name an import specifier names: `@scope/name/deep` → `@scope/name`. */

package/lib/portable/hosts/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * What a chat host service (Slack, Discord) shares, on Node: the ai-agents
+ * What a chat host service (Slack, Discord, WhatsApp) shares, on Node: the ai-agents
  * host contracts and client, the agent client over the session API, the
  * semantic events a turn is reduced to, approval renderers, deliveries, the
  * turn's state, application resolution, the durable queue, quotas, secrets

package/lib/portable/hosts/index.js

@@ -3,7 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * What a chat host service (Slack, Discord) shares, on Node: the ai-agents
+ * What a chat host service (Slack, Discord, WhatsApp) shares, on Node: the ai-agents
  * host contracts and client, the agent client over the session API, the
  * semantic events a turn is reduced to, approval renderers, deliveries, the
  * turn's state, application resolution, the durable queue, quotas, secrets

package/lib/portable/hosts/sessionUid.d.ts

@@ -2,6 +2,8 @@
  * `<kind>-<40 hex>`: the SHA-256 of the thread's parts joined by `:`, and
  * `:<generation>` once the thread started over or switched application. The
  * same parts give the same uid (Slack: app, enterprise or `-`, team,
- * channel, thread ts; Discord: application, guild, channel, thread).
+ * channel, thread ts; Discord: application, guild, channel, thread;
+ * WhatsApp: WABA, phone number id, and the person's BSUID for a chat or the
+ * group's id for a group).
  */
 export declare function hostSessionUid(kind: string, parts: readonly string[], generation?: number): string;

package/lib/portable/hosts/sessionUid.js

@@ -13,7 +13,9 @@ import { createHash } from 'node:crypto';
  * `<kind>-<40 hex>`: the SHA-256 of the thread's parts joined by `:`, and
  * `:<generation>` once the thread started over or switched application. The
  * same parts give the same uid (Slack: app, enterprise or `-`, team,
- * channel, thread ts; Discord: application, guild, channel, thread).
+ * channel, thread ts; Discord: application, guild, channel, thread;
+ * WhatsApp: WABA, phone number id, and the person's BSUID for a chat or the
+ * group's id for a group).
  */
 export function hostSessionUid(kind, parts, generation) {
     if (!/^[a-z][a-z0-9-]{1,31}$/.test(kind)) {

package/lib/portable/semantic-events.json

@@ -12,7 +12,8 @@
     "ask",
     "completion",
     "stop",
-    "error"
+    "error",
+    "sign-in"
   ],
   "producers": {
     "text": "AG-UI TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_CHUNK delta",
@@ -25,7 +26,8 @@
     "ask": "AG-UI RUN_FINISHED with result.asking (agent_runtimes/loop/apps/sessions.py question_of); the run stream carries no loop.ask event",
     "completion": "AG-UI RUN_FINISHED without asking",
     "stop": "the host itself, after its own Stop: a stopped session's stream ends without RUN_FINISHED or RUN_ERROR (agent_runtimes/loop/apps/sessions.py stop, _close); no AG-UI event carries it",
-    "error": "AG-UI RUN_ERROR message"
+    "error": "AG-UI RUN_ERROR message",
+    "sign-in": "AG-UI TOOL_CALL_RESULT of pap_sign_in (or pact_sign_in, with or without a gateway prefix) whose result is a sign-in waiting for the person with an https page (src/portable/signIn.ts readPapSignIn), after the tool's complete row; a page that is not https gives the row only"
   },
   "cases": [
     {
@@ -447,6 +449,119 @@
         }
       ],
       "semantic": []
+    },
+    {
+      "agui": [
+        {
+          "type": "TOOL_CALL_START",
+          "toolCallId": "c9",
+          "toolCallName": "pap_sign_in"
+        },
+        {
+          "type": "TOOL_CALL_RESULT",
+          "toolCallId": "c9",
+          "messageId": "r9",
+          "content": "{\"status\": \"waiting_for_the_person\", \"mode\": \"direct\", \"open\": \"https://iam.example.com/pap/start/t1\", \"company\": \"manzanita.example\", \"organization_name\": \"Manzanita\", \"organization_domain\": \"manzanita.example\"}"
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "tool",
+          "id": "c9",
+          "name": "pap_sign_in",
+          "status": "running"
+        },
+        {
+          "kind": "tool",
+          "id": "c9",
+          "name": "pap_sign_in",
+          "status": "complete"
+        },
+        {
+          "kind": "sign-in",
+          "toolCallId": "c9",
+          "toolName": "pap_sign_in",
+          "signIn": {
+            "mode": "direct",
+            "open": "https://iam.example.com/pap/start/t1",
+            "host": "iam.example.com",
+            "company": "manzanita.example",
+            "organization": {
+              "name": "Manzanita",
+              "domain": "manzanita.example"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "TOOL_CALL_START",
+          "toolCallId": "c10",
+          "toolCallName": "gateway_pap_sign_in"
+        },
+        {
+          "type": "TOOL_CALL_RESULT",
+          "toolCallId": "c10",
+          "messageId": "r10",
+          "content": "{\"structuredContent\": {\"status\": \"waiting_for_the_person\", \"mode\": \"device\", \"open\": \"https://manzanita.example/device\", \"code\": \"WDJB-MJHT\"}}"
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "tool",
+          "id": "c10",
+          "name": "gateway_pap_sign_in",
+          "status": "running"
+        },
+        {
+          "kind": "tool",
+          "id": "c10",
+          "name": "gateway_pap_sign_in",
+          "status": "complete"
+        },
+        {
+          "kind": "sign-in",
+          "toolCallId": "c10",
+          "toolName": "gateway_pap_sign_in",
+          "signIn": {
+            "mode": "device",
+            "open": "https://manzanita.example/device",
+            "host": "manzanita.example",
+            "code": "WDJB-MJHT"
+          }
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "TOOL_CALL_START",
+          "toolCallId": "c11",
+          "toolCallName": "pap_sign_in"
+        },
+        {
+          "type": "TOOL_CALL_RESULT",
+          "toolCallId": "c11",
+          "messageId": "r11",
+          "content": "{\"status\": \"waiting_for_the_person\", \"mode\": \"direct\", \"open\": \"http://manzanita.example/signin\"}"
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "tool",
+          "id": "c11",
+          "name": "pap_sign_in",
+          "status": "running"
+        },
+        {
+          "kind": "tool",
+          "id": "c11",
+          "name": "pap_sign_in",
+          "status": "complete"
+        }
+      ]
     }
   ],
   "answers": [

package/lib/portable/semantic.d.ts

@@ -10,8 +10,9 @@
  *
  * @module portable/semantic
  */
+import type { PapSignInWaiting } from './signIn';
 export declare const SEMANTIC_EVENTS_VERSION = 1;
-export declare const SEMANTIC_KINDS: readonly ["text", "progress", "tool", "approval", "table", "file", "citation", "ask", "completion", "stop", "error"];
+export declare const SEMANTIC_KINDS: readonly ["text", "progress", "tool", "approval", "table", "file", "citation", "ask", "completion", "stop", "error", "sign-in"];
 export type SemanticKind = (typeof SEMANTIC_KINDS)[number];
 export type AskQuestion = Readonly<{
     /** `text` and `choice` are answered in the host; `file` and `form` hand off to Datalayer. */
@@ -58,6 +59,17 @@ export type SemanticEvent = Readonly<{
 }> | Readonly<{
     kind: 'error';
     message: string;
+}> | Readonly<{
+    /**
+     * A company's sign-in waiting for the person (`pap_sign_in`, or a
+     * business's `pact_sign_in`): its page (https only), mode and code,
+     * as `signIn.ts` reads them. A host shows it as a button or the code
+     * with the page; the turn goes on once the person has signed in.
+     */
+    kind: 'sign-in';
+    toolCallId: string;
+    toolName: string;
+    signIn: PapSignInWaiting;
 }>;
 /** Whether an event ends the turn's presentation. */
 export declare function isTerminal(event: SemanticEvent): boolean;

package/lib/portable/semantic.js

@@ -2,18 +2,6 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/**
- * The semantic agent events a chat host renders (Slack, Discord), version 1:
- * a session's AG-UI stream reduced to what a host shows (`semanticOfAgUi.ts`),
- * never a notebook widget or a web component. The contract and its fixture
- * cases are `semantic-events.json`, beside this file, tested here
- * (`__tests__/semantic.unit.test.ts`) and by the runtime that emits the
- * events (`agent_runtimes/tests/test_semantic_events_contract.py`).
- *
- * Moved from the Slack service (DC-005, S-004, S-205).
- *
- * @module portable/semantic
- */
 export const SEMANTIC_EVENTS_VERSION = 1;
 export const SEMANTIC_KINDS = [
     'text',
@@ -27,6 +15,7 @@ export const SEMANTIC_KINDS = [
     'completion',
     'stop',
     'error',
+    'sign-in',
 ];
 /** Whether an event ends the turn's presentation. */
 export function isTerminal(event) {

package/lib/portable/semanticOfAgUi.js

@@ -2,6 +2,7 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+import { isPapSignInTool, readPapSignIn } from './signIn.js';
 /** A string field of an event, or the fallback: never an object stringified. */
 const stringOf = (value, fallback = '') => typeof value === 'string' ? value : fallback;
 const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
@@ -84,9 +85,20 @@ export function semanticOf(event, tools) {
                 return [{ kind: 'approval', toolCallId: id, toolName: name }];
             }
             const failed = result?.success === false || result?.isError === true;
-            return [
-                { kind: 'tool', id, name, status: failed ? 'failed' : 'complete' },
-            ];
+            const done = {
+                kind: 'tool',
+                id,
+                name,
+                status: failed ? 'failed' : 'complete',
+            };
+            // A company's sign-in waiting for the person: the host shows its page.
+            // A page that is not https is never shown: the tool's row says it.
+            const signIn = isPapSignInTool(name)
+                ? readPapSignIn(event.content)
+                : null;
+            return signIn && !('refused' in signIn)
+                ? [done, { kind: 'sign-in', toolCallId: id, toolName: name, signIn }]
+                : [done];
         }
         case 'STEP_STARTED':
             return typeof event.stepName === 'string' && event.stepName

package/lib/specs/appspecSchema.js

@@ -1961,7 +1961,7 @@ export const APPSPEC_SCHEMA = {
             properties: {
                 variant: {
                     $ref: '#/$defs/ThemeVariant',
-                    description: 'The theme: `datalayer`, `spatial`, `lovely`, `matrix`, `earth`, `sand`, `ivory`, `sun` or `loop`',
+                    description: 'The theme: `datalayer`, `spatial`, `lovely`, `matrix`, `earth`, `sand`, `ivory`, `sun`, `loop` or `vscode`',
                 },
                 mode: {
                     anyOf: [
@@ -2505,6 +2505,7 @@ export const APPSPEC_SCHEMA = {
                 'ivory',
                 'sun',
                 'loop',
+                'vscode',
             ],
             title: 'ThemeVariant',
             type: 'string',

package/lib/types/agentspecs.d.ts

@@ -717,7 +717,7 @@ export type AppLayout = 'chat' | 'page' | 'split';
 /** The one colour of an application; everything else is neutral. */
 export type AppAccent = 'green' | 'rose' | 'sky' | 'lime' | 'sun' | 'violet';
 /** A theme of Appearance's, which an application may run in (T-30). */
-export type AppThemeVariant = 'datalayer' | 'spatial' | 'lovely' | 'matrix' | 'earth' | 'sand' | 'ivory' | 'sun' | 'loop';
+export type AppThemeVariant = 'datalayer' | 'spatial' | 'lovely' | 'matrix' | 'earth' | 'sand' | 'ivory' | 'sun' | 'loop' | 'vscode';
 /** The colour mode it is worn in: `auto` follows the device. */
 export type AppThemeMode = 'light' | 'dark' | 'auto';
 /**

package/lib/types/tools.d.ts

@@ -149,6 +149,12 @@ export interface FrontendToolDefinition<TArgs = Record<string, unknown>, TResult
      * Required when location is 'frontend' (default)
      */
     handler?: (args: TArgs) => Promise<TResult>;
+    /**
+     * What its card says in place of its arguments' summary, from what it
+     * returned (`on analysis.ipynb`, the file a host's editor tool ran on);
+     * `undefined` keeps the arguments' summary. Asked only once it returned.
+     */
+    summaryOf?: (args: TArgs, result: TResult) => string | undefined;
     /**
      * Optional render function for custom UI during execution
      */

package/package.json

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