@datalayer/agent-runtimes 1.5.48 → 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/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": {
@@ -380,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,7 +22,7 @@ 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, 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';

package/package.json

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