@datalayer/agent-runtimes 1.5.47 → 1.5.49

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

@@ -41,16 +41,29 @@ export type Place = Readonly<{
     kind: 'channel' | 'direct';
     id: string;
 }>;
+/**
+ * Where a turn comes from, as the session API takes it on the turn itself
+ * (`provenance`, plans/DISCORD.md §4.3, §4.4; at most 1 KiB): the host's
+ * kind, the place, the thread and the message.
+ */
+export type TurnProvenance = Readonly<{
+    host_kind: string;
+    place: Place;
+    thread: string;
+    message_id: string;
+}>;
 /**
  * What is the host's own in a turn: the session uid its thread derives
  * (`hostSessionUid`), the place Datalayer checks the channel policy against,
- * the delivery target handed back with every delivery, and what is said when
- * its installation holds no host key.
+ * the delivery target handed back with every delivery, the provenance sent
+ * with the turn, and what is said when its installation holds no host key.
  */
 export type HostShape<P> = Readonly<{
     sessionUidOf(request: HostTurnRequest<P>): string;
     placeOf(request: HostTurnRequest<P>): Place;
     targetOf(request: HostTurnRequest<P>): Record<string, unknown>;
+    /** The turn's provenance; a host that sends none leaves it out. */
+    provenanceOf?(request: HostTurnRequest<P>): TurnProvenance;
     notBound: string;
 }>;
 /**

package/lib/portable/hosts/agentClient.js

@@ -220,6 +220,7 @@ export class HttpAgentClient {
         const host = await this.credentials.forTurn(request);
         assertTrustedStreamUrl(this.apiUrl, host.sessionApiUrl);
         const sessionId = request.sessionId ?? this.shape.sessionUidOf(request);
+        const provenance = this.shape.provenanceOf?.(request);
         const headers = {
             accept: 'text/event-stream',
             authorization: `Bearer ${host.accessToken}`,
@@ -231,6 +232,7 @@ export class HttpAgentClient {
                 body: JSON.stringify({
                     external_event_id: request.externalEventId,
                     text: request.prompt,
+                    ...(provenance ? { provenance } : {}),
                 }),
                 headers,
                 method: 'POST',
@@ -243,6 +245,7 @@ export class HttpAgentClient {
                     opener: request.prompt,
                     session: sessionId,
                     ...(host.userToken ? { user_token: host.userToken } : {}),
+                    ...(provenance ? { provenance } : {}),
                 }),
                 headers,
                 method: 'POST',

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

@@ -5,8 +5,9 @@ import type { ApprovalPresentation } from './contracts';
  * tool proves that every material argument is shown: each argument the server
  * presented is named by the renderer, or the card fails closed. An unknown
  * tool, an argument the renderer does not know, an attachment, and every
- * destructive, financial or publishing action are reviewed in Datalayer
- * (SLACK §15, 5). They render ai-agents' presentation v1, a different input
+ * action that is not mail (reads, writes, other sends, destructive, financial,
+ * publishing, executing) are reviewed in Datalayer (SLACK §15, 5, decided by
+ * the user on 16 October 2026: mail only). They render ai-agents' presentation v1, a different input
  * from `../approvals.ts` and `../approvalCard.ts`. Moved from the Slack
  * service (plans/DISCORD.md DC-004).
  *
@@ -31,8 +32,14 @@ type Renderer = Readonly<{
     matches(presentation: ApprovalPresentation): boolean;
     render(presentation: ApprovalPresentation): RenderedAction;
 }>;
-/** Action classes that are decided in Datalayer only (§15, 5). */
+/**
+ * Action classes that are decided in Datalayer only: every class but `send`,
+ * since only mail is decided in a host (decided by the user on 16 October
+ * 2026, SLACK §15, 5).
+ */
 export declare const DATALAYER_ONLY: Set<"unknown" | "read" | "write" | "send" | "delete" | "publish" | "execute" | "financial">;
+/** The words of a tool's name that make a send mail: contracts.json `mail_words`. */
+export declare const MAIL_WORDS: ReadonlySet<string>;
 /** The renderers, the first that matches wins: Datalayer-only before any other. */
 export declare const RENDERERS: readonly Renderer[];
 /**

package/lib/portable/hosts/approvalRenderers.js

@@ -2,8 +2,14 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/** Action classes that are decided in Datalayer only (§15, 5). */
+/**
+ * Action classes that are decided in Datalayer only: every class but `send`,
+ * since only mail is decided in a host (decided by the user on 16 October
+ * 2026, SLACK §15, 5).
+ */
 export const DATALAYER_ONLY = new Set([
+    'read',
+    'write',
     'delete',
     'publish',
     'financial',
@@ -28,7 +34,19 @@ function rendered(name, presentation, fields, known, extra = []) {
     ];
     return { complete: reasons.length === 0, fields, reasons, renderer: name };
 }
-const MAIL_TOOL = /(^|[_.-])(send|draft)[_.-]?(e?mail|message)($|[_.-])|^gmail[_.-]send|^mail[_.-]send$/i;
+/** The words of a tool's name that make a send mail: contracts.json `mail_words`. */
+export const MAIL_WORDS = new Set([
+    'email',
+    'gmail',
+    'mail',
+]);
+/** A tool name's words, as ai-agents reads them (camelCase and separators split). */
+const wordsOf = (name) => name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+const isMail = (toolName) => wordsOf(toolName).some(word => MAIL_WORDS.has(word));
 const MAIL_KEYS = [
     'to',
     'cc',
@@ -42,8 +60,7 @@ const MAIL_KEYS = [
 /** Mail: every recipient, the subject, the whole body; an attachment goes to Datalayer. */
 const mail = {
     name: 'mail',
-    matches: presentation => presentation.action_class === 'send' &&
-        MAIL_TOOL.test(presentation.tool_name),
+    matches: presentation => presentation.action_class === 'send' && isMail(presentation.tool_name),
     render(presentation) {
         const args = presentation.arguments;
         const fields = [];
@@ -82,53 +99,14 @@ const mail = {
         return rendered('mail', presentation, fields, MAIL_KEYS, extra);
     },
 };
-const WRITE_TOOL = /(^|[_.-])(write|update|edit|append|create|save|set|rename|move)[_.-]?/i;
-const WRITE_KEYS = [
-    'path',
-    'file',
-    'filename',
-    'name',
-    'title',
-    'content',
-    'text',
-    'new_path',
-    'destination',
-    'mode',
-];
-/** A write: where, and the whole of what is written. */
-const write = {
-    name: 'write',
-    matches: presentation => presentation.action_class === 'write' &&
-        WRITE_TOOL.test(presentation.tool_name),
-    render(presentation) {
-        const args = presentation.arguments;
-        const fields = [];
-        for (const [key, label] of [
-            ['path', 'Where'],
-            ['file', 'Where'],
-            ['filename', 'Where'],
-            ['name', 'Name'],
-            ['title', 'Title'],
-            ['new_path', 'Moved to'],
-            ['destination', 'Moved to'],
-            ['mode', 'How'],
-            ['content', 'What is written'],
-            ['text', 'What is written'],
-        ])
-            if (args[key] !== undefined)
-                fields.push({ label, value: text(args[key]) });
-        const extra = fields.length === 0
-            ? ['The request does not say what it writes: review it in Datalayer.']
-            : [];
-        return rendered('write', presentation, fields, WRITE_KEYS, extra);
-    },
-};
-/** Delete, publish, money and running code: shown, decided only in Datalayer (§15, 5). */
+/** Everything but mail: shown, decided only in Datalayer (§15, 5). */
 const datalayerOnly = {
     name: 'datalayer-only',
     matches: presentation => DATALAYER_ONLY.has(presentation.action_class),
     render(presentation) {
         const words = {
+            read: 'Only mail is decided outside Datalayer: reading is decided in Datalayer.',
+            write: 'Only mail is decided outside Datalayer: writing is decided in Datalayer.',
             delete: 'Deleting is decided in Datalayer.',
             execute: 'Running code is decided in Datalayer.',
             financial: 'Moving money is decided in Datalayer.',
@@ -145,22 +123,8 @@ const datalayerOnly = {
         };
     },
 };
-/** A read: every argument, by its name, whole — nothing is changed or sent. */
-const read = {
-    name: 'read',
-    matches: presentation => presentation.action_class === 'read',
-    render(presentation) {
-        const fields = Object.entries(presentation.arguments).map(([key, value]) => ({ label: key, value: text(value) }));
-        return rendered('read', presentation, fields, Object.keys(presentation.arguments));
-    },
-};
 /** The renderers, the first that matches wins: Datalayer-only before any other. */
-export const RENDERERS = [
-    datalayerOnly,
-    mail,
-    write,
-    read,
-];
+export const RENDERERS = [datalayerOnly, mail];
 /**
  * How a host shows an approval, by the renderer that knows its tool; with
  * none, nothing is decided in the host.

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

@@ -53,6 +53,22 @@ export declare class DatalayerHostClient {
      * channel policy and whether it is paused.
      */
     self(hostKey: string): Promise<HostSelf>;
+    /**
+     * The host's own administration (plans/DISCORD.md DC-106,
+     * `/datalayer-admin`): pause, resume or one channel's rule, for the host
+     * user linked to the installation's owner; Datalayer refuses anyone else
+     * (403), whatever their role in the host.
+     */
+    admin(hostKey: string, externalUserId: string, change: Readonly<{
+        paused?: boolean;
+        channel?: Readonly<{
+            id: string;
+            state: 'allow' | 'deny';
+            deployment?: string;
+        }>;
+    }>): Promise<{
+        paused: boolean;
+    }>;
     /** The host unlinks one of its users: how many links ended. */
     unlink(hostKey: string, externalUserId: string): Promise<number>;
     /** A one-use code a host user redeems, signed in to Datalayer, to link their account. */

package/lib/portable/hosts/client.js

@@ -102,6 +102,22 @@ export class DatalayerHostClient {
             paused: host.paused ?? false,
         };
     }
+    /**
+     * The host's own administration (plans/DISCORD.md DC-106,
+     * `/datalayer-admin`): pause, resume or one channel's rule, for the host
+     * user linked to the installation's owner; Datalayer refuses anyone else
+     * (403), whatever their role in the host.
+     */
+    async admin(hostKey, externalUserId, change) {
+        const answered = await this.#call('Datalayer did not take the change', '/apps/hosts/self/admin', {
+            body: { external_user_id: externalUserId, ...change },
+            hostKey,
+            method: 'POST',
+        }, z.object({
+            host: z.object({ paused: z.boolean().optional() }).loose(),
+        }));
+        return { paused: answered.host.paused ?? false };
+    }
     /** The host unlinks one of its users: how many links ended. */
     async unlink(hostKey, externalUserId) {
         const answered = await this.#call('Datalayer did not unlink the account', `/apps/hosts/self/links/${encodeURIComponent(externalUserId)}`, { hostKey, method: 'DELETE' }, z.object({ revoked: z.number().int() }));

package/lib/portable/hosts/contracts.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "about": "The generic host contracts of plans/SLACK.md §4.3, as ai-agents and the runtime's session API answer them. Shared verbatim by ai-agents (tests/fixtures/hosts) and the Slack adapter (tech/datalayer/slack, test/contracts): each side's tests check its half against this file.",
+  "about": "The generic host contracts of plans/SLACK.md §4.3 and plans/DISCORD.md §4.3, 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.",
   "headers": {
     "host_key": "X-Datalayer-Host-Key",
     "signature": "X-Datalayer-Signature",
@@ -29,7 +29,8 @@
     "preview_link": "GET /api/ai-agents/v1/apps/hosts/links/preview?code={code}",
     "change_host": "PATCH /api/ai-agents/v1/apps/hosts/{uid}",
     "handoff": "POST /api/ai-agents/v1/apps/hosts/handoffs",
-    "redeem_handoff": "POST /api/ai-agents/v1/apps/hosts/handoffs/redeem"
+    "redeem_handoff": "POST /api/ai-agents/v1/apps/hosts/handoffs/redeem",
+    "admin": "POST /api/ai-agents/v1/apps/hosts/self/admin"
   },
   "bind": {
     "request": {
@@ -147,7 +148,19 @@
         "state"
       ]
     },
-    "replay": "The same Idempotency-Key (or, without one, the same external_event_id) and the same request answer the original session and turn with replayed=true, and run nothing; the same key with another request is 409."
+    "replay": "The same Idempotency-Key (or, without one, the same external_event_id) and the same request answer the original session and turn with replayed=true, and run nothing; the same key with another request is 409.",
+    "optional_request": {
+      "provenance": {
+        "host_kind": "discord",
+        "place": {
+          "kind": "channel",
+          "id": "345678901234567890"
+        },
+        "thread": "456789012345678901",
+        "message_id": "456789012345678901"
+      }
+    },
+    "provenance_limit_bytes": 1024
   },
   "webhook": {
     "request": {
@@ -239,9 +252,12 @@
       "unknown"
     ],
     "host_decidable": [
-      "read",
-      "send",
-      "write"
+      "send"
+    ],
+    "mail_words": [
+      "email",
+      "gmail",
+      "mail"
     ],
     "example": {
       "version": 1,
@@ -377,5 +393,75 @@
       "expired": 410,
       "spent_or_unknown": 404
     }
+  },
+  "admin": {
+    "request": {
+      "external_user_id": "567890123456789012",
+      "paused": true
+    },
+    "channel_request": {
+      "external_user_id": "567890123456789012",
+      "channel": {
+        "id": "345678901234567890",
+        "state": "deny"
+      }
+    },
+    "response_keys": [
+      "success",
+      "host"
+    ],
+    "refusals": {
+      "not_the_owner": 403,
+      "nothing_to_change": 422
+    }
+  },
+  "discord": {
+    "about": "Discord's forms of the generic contracts (plans/DISCORD.md §4.3): the installation is <application_id>:<guild_id>, a member is their snowflake, a thread is sent as its parent channel, the session uid is hostSessionUid(\"discord\", [application, guild, channel, thread]).",
+    "application_id": "123456789012345678",
+    "guild_id": "234567890123456789",
+    "bind_request": {
+      "code": "dlhc_…",
+      "external_id": "123456789012345678:234567890123456789",
+      "name": "Acme"
+    },
+    "external_user_id": "567890123456789012",
+    "thread": {
+      "channel": {
+        "id": "456789012345678901",
+        "type": 11,
+        "parent_id": "345678901234567890"
+      },
+      "place": {
+        "kind": "channel",
+        "id": "345678901234567890"
+      }
+    },
+    "direct": {
+      "channel": {
+        "id": "678901234567890123",
+        "type": 1
+      },
+      "place": {
+        "kind": "direct",
+        "id": "678901234567890123"
+      }
+    },
+    "session": {
+      "parts": [
+        "123456789012345678",
+        "234567890123456789",
+        "345678901234567890",
+        "456789012345678901"
+      ],
+      "uid": "discord-15beb80510370bbe027882df9d4d4666925017df"
+    },
+    "target": {
+      "applicationId": "123456789012345678",
+      "channelId": "345678901234567890",
+      "guildId": "234567890123456789",
+      "messageId": "456789012345678901",
+      "threadId": "456789012345678901",
+      "userId": "567890123456789012"
+    }
   }
 }

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

@@ -22,9 +22,9 @@ export * from '../semantic';
 export { askQuestionOf, semanticOf, turnOf, type TurnInfo, } from '../semanticOfAgUi';
 export * from './contracts';
 export { DatalayerHostClient, HostRefusedError, type BoundHost, type HostSelf, } from './client';
-export { agUiEventsOf, assertTrustedStreamUrl, DevelopmentCredentials, HostKeyCredentials, hostSessionOf, HostStarters, HttpAgentClient, InstallationCredentials, lastAnswer, type AgentClient, type HostCredentials, type HostKeyLookup, type HostSession, type HostShape, type HostTurnRequest, type Place, type Starter, type StarterSource, type TurnStream, } from './agentClient';
+export { agUiEventsOf, assertTrustedStreamUrl, DevelopmentCredentials, HostKeyCredentials, hostSessionOf, HostStarters, HttpAgentClient, InstallationCredentials, lastAnswer, type AgentClient, type HostCredentials, type HostKeyLookup, type HostSession, type HostShape, type HostTurnRequest, type Place, type Starter, type StarterSource, type TurnProvenance, type TurnStream, } from './agentClient';
 export { hostSessionUid } from './sessionUid';
-export { DATALAYER_ONLY, RENDERERS, renderApproval, type RenderedAction, type RenderedField, } from './approvalRenderers';
+export { DATALAYER_ONLY, MAIL_WORDS, RENDERERS, renderApproval, type RenderedAction, type RenderedField, } from './approvalRenderers';
 export { DELIVERY_PATH, DELIVERY_ROUTE, DeliveryPoller, deliveryRoute, receiveDelivery, type BoundHostKey, type DeliveryClaimStore, type DeliveryJob, type DeliverySink, } from './deliveries';
 export { TurnState, type TurnEnding, type TurnFile, type TurnTool, } from './turnState';
 export { resolveApplication, usableAllowances, type AllowanceView, type ApplicationRefusal, type ApplicationResolution, type ChannelRule, } from './resolution';

package/lib/portable/hosts/index.js

@@ -29,7 +29,7 @@ export * from './contracts';
 export { DatalayerHostClient, HostRefusedError, } from './client';
 export { agUiEventsOf, assertTrustedStreamUrl, DevelopmentCredentials, HostKeyCredentials, hostSessionOf, HostStarters, HttpAgentClient, InstallationCredentials, lastAnswer, } from './agentClient';
 export { hostSessionUid } from './sessionUid';
-export { DATALAYER_ONLY, RENDERERS, renderApproval, } from './approvalRenderers';
+export { DATALAYER_ONLY, MAIL_WORDS, RENDERERS, renderApproval, } from './approvalRenderers';
 export { DELIVERY_PATH, DELIVERY_ROUTE, DeliveryPoller, deliveryRoute, receiveDelivery, } from './deliveries';
 export { TurnState, } from './turnState';
 export { resolveApplication, usableAllowances, } from './resolution';

package/package.json

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