@datalayer/agent-runtimes 1.6.33 → 1.6.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,6 +21,16 @@ export type HostSelf = Readonly<{
21
21
  }>;
22
22
  directOnly: readonly string[];
23
23
  paused: boolean;
24
+ /**
25
+ * The registered webhook, if any: where, the key its secret is derived
26
+ * under, and whether ai-agents asks it registered again.
27
+ */
28
+ delivery?: Readonly<{
29
+ key?: string;
30
+ renew: boolean;
31
+ url: string;
32
+ version: number;
33
+ }>;
24
34
  /** The installation's own uid: what its deliveries are addressed to. */
25
35
  uid: string;
26
36
  }>;
@@ -94,8 +104,13 @@ export declare class DatalayerHostClient {
94
104
  linked: boolean;
95
105
  principalUid?: string;
96
106
  }>;
97
- /** Where deliveries are pushed: answered the secret they are signed with, once. */
107
+ /**
108
+ * Where deliveries are pushed: answered the secret they are signed with,
109
+ * once, and the key it is derived under (kept beside it: every push names
110
+ * it). Registering again moves the version: the old secret stops.
111
+ */
98
112
  setWebhook(hostKey: string, url: string): Promise<{
113
+ key?: string;
99
114
  signingSecret: string;
100
115
  version: number;
101
116
  }>;
@@ -106,6 +106,16 @@ export class DatalayerHostClient {
106
106
  })),
107
107
  directOnly: host.direct_only ?? [],
108
108
  paused: host.paused ?? false,
109
+ ...(host.delivery?.url
110
+ ? {
111
+ delivery: {
112
+ ...(host.delivery.key ? { key: host.delivery.key } : {}),
113
+ renew: host.delivery.renew ?? false,
114
+ url: host.delivery.url,
115
+ version: host.delivery.version ?? 0,
116
+ },
117
+ }
118
+ : {}),
109
119
  uid: host.uid,
110
120
  };
111
121
  }
@@ -147,7 +157,11 @@ export class DatalayerHostClient {
147
157
  const state = await this.#call('Datalayer did not say whether the account is linked', `/apps/hosts/self/links/${encodeURIComponent(externalUserId)}`, { hostKey }, linkStateSchema);
148
158
  return { linked: state.linked, principalUid: state.principal_uid };
149
159
  }
150
- /** Where deliveries are pushed: answered the secret they are signed with, once. */
160
+ /**
161
+ * Where deliveries are pushed: answered the secret they are signed with,
162
+ * once, and the key it is derived under (kept beside it: every push names
163
+ * it). Registering again moves the version: the old secret stops.
164
+ */
151
165
  async setWebhook(hostKey, url) {
152
166
  const hook = await this.#call('Datalayer did not register the delivery address', '/apps/hosts/self/delivery', {
153
167
  body: {
@@ -157,7 +171,11 @@ export class DatalayerHostClient {
157
171
  hostKey,
158
172
  method: 'PUT',
159
173
  }, webhookSchema);
160
- return { signingSecret: hook.signing_secret, version: hook.version };
174
+ return {
175
+ ...(hook.key ? { key: hook.key } : {}),
176
+ signingSecret: hook.signing_secret,
177
+ version: hook.version,
178
+ };
161
179
  }
162
180
  /** What the installation has not acknowledged, oldest first: pushed or not. */
163
181
  async outbox(hostKey, limit = 100) {
@@ -12,6 +12,20 @@ export declare const HOST_KEY_HEADER = "X-Datalayer-Host-Key";
12
12
  export declare const SIGNATURE_HEADER = "X-Datalayer-Signature";
13
13
  export declare const TIMESTAMP_HEADER = "X-Datalayer-Timestamp";
14
14
  export declare const DELIVERY_HEADER = "X-Datalayer-Delivery";
15
+ /**
16
+ * The version of ai-agents' own key a push was signed under
17
+ * (`ai-agents-host-deliveries-v<N>`), the `key` its registration was
18
+ * answered. Absent on a webhook registered under the platform's shared
19
+ * secret, which is refused after {@link SHARED_SECRET_DELIVERIES_UNTIL}.
20
+ */
21
+ export declare const DELIVERY_KEY_HEADER = "X-Datalayer-Delivery-Key";
22
+ export declare const DELIVERY_KEY_PATTERN: RegExp;
23
+ /**
24
+ * The end of the platform's HS256 window (31 December 2026, 00:00 UTC):
25
+ * from then on a push without a `key` is refused, and ai-agents holds such a
26
+ * registration's pushes in the outbox until its host registers again.
27
+ */
28
+ export declare const SHARED_SECRET_DELIVERIES_UNTIL: number;
15
29
  export declare const IDEMPOTENCY_HEADER = "Idempotency-Key";
16
30
  /** The presentation version the hosts render; another is reviewed in Datalayer. */
17
31
  export declare const PRESENTATION_VERSION = 1;
@@ -51,6 +65,12 @@ export declare const selfSchema: z.ZodObject<{
51
65
  }, z.core.$strip>>>;
52
66
  direct_only: z.ZodOptional<z.ZodArray<z.ZodString>>;
53
67
  paused: z.ZodOptional<z.ZodBoolean>;
68
+ delivery: z.ZodOptional<z.ZodObject<{
69
+ url: z.ZodOptional<z.ZodString>;
70
+ version: z.ZodOptional<z.ZodNumber>;
71
+ key: z.ZodOptional<z.ZodString>;
72
+ renew: z.ZodOptional<z.ZodBoolean>;
73
+ }, z.core.$loose>>;
54
74
  }, z.core.$loose>;
55
75
  }, z.core.$strip>;
56
76
  /** `POST /apps/hosts/handoffs`: a one-use code that opens one session or approval (S-305). */
@@ -68,6 +88,7 @@ export declare const webhookSchema: z.ZodObject<{
68
88
  events: z.ZodArray<z.ZodString>;
69
89
  version: z.ZodNumber;
70
90
  signing_secret: z.ZodString;
91
+ key: z.ZodOptional<z.ZodString>;
71
92
  }, z.core.$strip>;
72
93
  /** One delivery of the outbox, as `GET …/self/deliveries` lists it. */
73
94
  export declare const outboxItemSchema: z.ZodObject<{
@@ -186,9 +207,15 @@ export declare function deliverySignature(secret: string, timestamp: number, raw
186
207
  /**
187
208
  * Verify a pushed delivery before trusting it: its signature in constant
188
209
  * time, and a timestamp within five minutes, so a captured push cannot be
189
- * replayed later.
210
+ * replayed later. `key` is what the registration was answered with the
211
+ * secret: the push must name it (`keyHeader`, {@link DELIVERY_KEY_HEADER}).
212
+ * A secret kept without one was derived from the platform's shared secret:
213
+ * accepted until {@link SHARED_SECRET_DELIVERIES_UNTIL} only, then refused
214
+ * until the host registers again.
190
215
  */
191
216
  export declare function verifyDelivery(input: {
217
+ key?: string;
218
+ keyHeader?: string;
192
219
  nowSeconds?: number;
193
220
  rawBody: string | Buffer;
194
221
  secret: string;
@@ -17,6 +17,20 @@ export const HOST_KEY_HEADER = 'X-Datalayer-Host-Key';
17
17
  export const SIGNATURE_HEADER = 'X-Datalayer-Signature';
18
18
  export const TIMESTAMP_HEADER = 'X-Datalayer-Timestamp';
19
19
  export const DELIVERY_HEADER = 'X-Datalayer-Delivery';
20
+ /**
21
+ * The version of ai-agents' own key a push was signed under
22
+ * (`ai-agents-host-deliveries-v<N>`), the `key` its registration was
23
+ * answered. Absent on a webhook registered under the platform's shared
24
+ * secret, which is refused after {@link SHARED_SECRET_DELIVERIES_UNTIL}.
25
+ */
26
+ export const DELIVERY_KEY_HEADER = 'X-Datalayer-Delivery-Key';
27
+ export const DELIVERY_KEY_PATTERN = /^ai-agents-host-deliveries-v\d+$/;
28
+ /**
29
+ * The end of the platform's HS256 window (31 December 2026, 00:00 UTC):
30
+ * from then on a push without a `key` is refused, and ai-agents holds such a
31
+ * registration's pushes in the outbox until its host registers again.
32
+ */
33
+ export const SHARED_SECRET_DELIVERIES_UNTIL = Date.parse('2026-12-31T00:00:00Z') / 1000;
20
34
  export const IDEMPOTENCY_HEADER = 'Idempotency-Key';
21
35
  /** The presentation version the hosts render; another is reviewed in Datalayer. */
22
36
  export const PRESENTATION_VERSION = 1;
@@ -60,6 +74,19 @@ export const selfSchema = z.object({
60
74
  .optional(),
61
75
  direct_only: z.array(z.string()).optional(),
62
76
  paused: z.boolean().optional(),
77
+ /**
78
+ * The registered webhook: `renew` when ai-agents asks it registered
79
+ * again (its secret rests on a key ai-agents no longer signs with).
80
+ */
81
+ delivery: z
82
+ .object({
83
+ url: z.string().optional(),
84
+ version: z.number().int().optional(),
85
+ key: z.string().optional(),
86
+ renew: z.boolean().optional(),
87
+ })
88
+ .loose()
89
+ .optional(),
63
90
  })
64
91
  .loose(),
65
92
  });
@@ -78,6 +105,8 @@ export const webhookSchema = z.object({
78
105
  events: z.array(z.string()),
79
106
  version: z.number().int(),
80
107
  signing_secret: z.string().min(32),
108
+ /** The version of ai-agents' key the secret is derived under; absent: the shared secret. */
109
+ key: z.string().regex(DELIVERY_KEY_PATTERN).optional(),
81
110
  });
82
111
  /** One delivery of the outbox, as `GET …/self/deliveries` lists it. */
83
112
  export const outboxItemSchema = z
@@ -217,7 +246,11 @@ export function deliverySignature(secret, timestamp, rawBody) {
217
246
  /**
218
247
  * Verify a pushed delivery before trusting it: its signature in constant
219
248
  * time, and a timestamp within five minutes, so a captured push cannot be
220
- * replayed later.
249
+ * replayed later. `key` is what the registration was answered with the
250
+ * secret: the push must name it (`keyHeader`, {@link DELIVERY_KEY_HEADER}).
251
+ * A secret kept without one was derived from the platform's shared secret:
252
+ * accepted until {@link SHARED_SECRET_DELIVERIES_UNTIL} only, then refused
253
+ * until the host registers again.
221
254
  */
222
255
  export function verifyDelivery(input) {
223
256
  const stamp = Number(input.timestamp);
@@ -226,6 +259,17 @@ export function verifyDelivery(input) {
226
259
  Math.abs(now - stamp) > (input.toleranceSeconds ?? 300)) {
227
260
  throw new Error("The delivery's timestamp is missing or too old.");
228
261
  }
262
+ if (input.key) {
263
+ if (input.keyHeader !== input.key) {
264
+ throw new Error('The delivery names another signing key.');
265
+ }
266
+ }
267
+ else if (input.keyHeader) {
268
+ throw new Error('The delivery names a key this registration was not answered.');
269
+ }
270
+ else if (now >= SHARED_SECRET_DELIVERIES_UNTIL) {
271
+ throw new Error("The delivery's secret was derived from the platform's shared secret, refused since 31 December 2026: register again.");
272
+ }
229
273
  const expected = Buffer.from(deliverySignature(input.secret, stamp, input.rawBody));
230
274
  const given = Buffer.from(input.signature ?? '');
231
275
  if (expected.length !== given.length || !timingSafeEqual(expected, given)) {
@@ -6,6 +6,7 @@
6
6
  "signature": "X-Datalayer-Signature",
7
7
  "timestamp": "X-Datalayer-Timestamp",
8
8
  "delivery": "X-Datalayer-Delivery",
9
+ "delivery_key": "X-Datalayer-Delivery-Key",
9
10
  "idempotency_key": "Idempotency-Key"
10
11
  },
11
12
  "routes": {
@@ -249,7 +250,8 @@
249
250
  "events",
250
251
  "version",
251
252
  "signing_secret"
252
- ]
253
+ ],
254
+ "key_about": "Once ai-agents signs deliveries with its own ring, the answer also names the ring's version, key (ai-agents-host-deliveries-v<N>), and every push says it in the delivery_key header. A registration without key, or under a version that no longer signs, is answered delivery.renew: true by GET self: the host registers again and keeps the new secret and key. Past the HS256 window (2026-12-31T00:00:00Z) a push without the header is refused by the host and ai-agents holds a keyless registration's pushes."
253
255
  },
254
256
  "delivery": {
255
257
  "events": [
@@ -23,10 +23,21 @@ export type BoundHostKey = Readonly<{
23
23
  hostKey: string;
24
24
  hostUid: string;
25
25
  }>;
26
+ /**
27
+ * What an installation's pushes are signed with, as its registration was
28
+ * answered: the secret, the key it is derived under (none: the platform's
29
+ * shared secret, accepted until the end of its window only), and the
30
+ * registration's version (none: kept before the version was).
31
+ */
32
+ export type DeliverySecret = Readonly<{
33
+ key?: string;
34
+ secret: string;
35
+ version?: number;
36
+ }>;
26
37
  /** Where a host keeps its installations, as deliveries read them. */
27
38
  export interface DeliverySink {
28
39
  /** What Datalayer signs an installation's pushes with, or `undefined` for an unknown one. */
29
- deliverySecretOf(hostUid: string): Promise<string | undefined>;
40
+ deliverySecretOf(hostUid: string): Promise<DeliverySecret | undefined>;
30
41
  /** The installation's key, or `undefined` once it was removed (late work is dropped). */
31
42
  hostKeyOf(hostUid: string): Promise<string | undefined>;
32
43
  /** Every installation bound at Datalayer: whose outbox is read. */
@@ -57,6 +68,29 @@ export declare function receiveDelivery(job: DeliveryJob, input: {
57
68
  export declare function deliveryRoute(sink: Pick<DeliverySink, 'deliverySecretOf'>, enqueue: (job: DeliveryJob) => Promise<void>, nowSeconds?: () => number): (request: IncomingMessage & {
58
69
  params?: Record<string, string | string[]>;
59
70
  }, response: ServerResponse) => Promise<void>;
71
+ /**
72
+ * Each bound installation's webhook registered again when ai-agents asks
73
+ * (`GET …/self` answers `delivery.renew`: its secret rests on a key
74
+ * ai-agents no longer signs with), or when what the host kept is not what
75
+ * ai-agents registered: another key, or another version (a renewal whose
76
+ * secret was not kept, or two replicas renewing at once, the later answer
77
+ * kept first). The new secret, key and version are handed to `keep`, where
78
+ * the host stores the old ones; an installation with no webhook reads its
79
+ * outbox and is left alone.
80
+ */
81
+ export declare class DeliveryRenewal {
82
+ #private;
83
+ readonly sink: Pick<DeliverySink, 'boundHosts' | 'deliverySecretOf'>;
84
+ readonly client: Pick<DatalayerHostClient, 'self' | 'setWebhook'>;
85
+ readonly keep: (hostUid: string, secret: DeliverySecret) => Promise<void>;
86
+ readonly logger: Pick<Console, 'warn'>;
87
+ constructor(sink: Pick<DeliverySink, 'boundHosts' | 'deliverySecretOf'>, client: Pick<DatalayerHostClient, 'self' | 'setWebhook'>, keep: (hostUid: string, secret: DeliverySecret) => Promise<void>, logger?: Pick<Console, 'warn'>);
88
+ /** One pass over the bound installations: how many registered again. */
89
+ renewOnce(): Promise<number>;
90
+ /** A pass now, then one every `intervalSeconds` (an hour by default). */
91
+ start(intervalSeconds?: number): void;
92
+ stop(): void;
93
+ }
60
94
  /**
61
95
  * The outbox, read when a push was missed or no address is registered
62
96
  * (`GET …/self/deliveries`): each delivery of every bound installation
@@ -2,7 +2,7 @@
2
2
  * Copyright (c) 2025-2026 Datalayer, Inc.
3
3
  * Distributed under the terms of the Modified BSD License.
4
4
  */
5
- import { DELIVERY_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, verifyDelivery, } from './contracts.js';
5
+ import { DELIVERY_HEADER, DELIVERY_KEY_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, verifyDelivery, } from './contracts.js';
6
6
  /** Where Datalayer pushes an installation's deliveries, under the service's public address. */
7
7
  export const DELIVERY_PATH = '/datalayer/deliveries';
8
8
  export const DELIVERY_ROUTE = `${DELIVERY_PATH}/:hostUid`;
@@ -56,8 +56,8 @@ export function deliveryRoute(sink, enqueue, nowSeconds) {
56
56
  try {
57
57
  const named = request.params?.hostUid;
58
58
  const hostUid = typeof named === 'string' ? named : '';
59
- const secret = hostUid ? await sink.deliverySecretOf(hostUid) : undefined;
60
- if (!secret) {
59
+ const kept = hostUid ? await sink.deliverySecretOf(hostUid) : undefined;
60
+ if (!kept?.secret) {
61
61
  return answer(404, { ok: false, error: 'unknown installation' });
62
62
  }
63
63
  const header = (name) => {
@@ -68,9 +68,11 @@ export function deliveryRoute(sink, enqueue, nowSeconds) {
68
68
  let delivery;
69
69
  try {
70
70
  delivery = verifyDelivery({
71
+ key: kept.key,
72
+ keyHeader: header(DELIVERY_KEY_HEADER),
71
73
  nowSeconds: nowSeconds?.(),
72
74
  rawBody,
73
- secret,
75
+ secret: kept.secret,
74
76
  signature: header(SIGNATURE_HEADER),
75
77
  timestamp: header(TIMESTAMP_HEADER),
76
78
  });
@@ -90,6 +92,84 @@ export function deliveryRoute(sink, enqueue, nowSeconds) {
90
92
  }
91
93
  };
92
94
  }
95
+ /**
96
+ * Each bound installation's webhook registered again when ai-agents asks
97
+ * (`GET …/self` answers `delivery.renew`: its secret rests on a key
98
+ * ai-agents no longer signs with), or when what the host kept is not what
99
+ * ai-agents registered: another key, or another version (a renewal whose
100
+ * secret was not kept, or two replicas renewing at once, the later answer
101
+ * kept first). The new secret, key and version are handed to `keep`, where
102
+ * the host stores the old ones; an installation with no webhook reads its
103
+ * outbox and is left alone.
104
+ */
105
+ export class DeliveryRenewal {
106
+ sink;
107
+ client;
108
+ keep;
109
+ logger;
110
+ #timer;
111
+ #running = false;
112
+ constructor(sink, client, keep, logger = console) {
113
+ this.sink = sink;
114
+ this.client = client;
115
+ this.keep = keep;
116
+ this.logger = logger;
117
+ }
118
+ /** One pass over the bound installations: how many registered again. */
119
+ async renewOnce() {
120
+ let renewed = 0;
121
+ for (const { hostKey, hostUid } of await this.sink.boundHosts()) {
122
+ try {
123
+ const delivery = (await this.client.self(hostKey)).delivery;
124
+ if (!delivery) {
125
+ continue;
126
+ }
127
+ const kept = await this.sink.deliverySecretOf(hostUid);
128
+ const current = !!kept?.secret &&
129
+ kept.key === delivery.key &&
130
+ (kept.version === undefined || kept.version === delivery.version);
131
+ if (!delivery.renew && current) {
132
+ continue;
133
+ }
134
+ const hook = await this.client.setWebhook(hostKey, delivery.url);
135
+ await this.keep(hostUid, {
136
+ ...(hook.key ? { key: hook.key } : {}),
137
+ secret: hook.signingSecret,
138
+ version: hook.version,
139
+ });
140
+ renewed += 1;
141
+ }
142
+ catch (error) {
143
+ this.logger.warn(`The webhook of one installation was not registered again: ${error.message}`);
144
+ }
145
+ }
146
+ return renewed;
147
+ }
148
+ /** A pass now, then one every `intervalSeconds` (an hour by default). */
149
+ start(intervalSeconds = 3600) {
150
+ if (intervalSeconds <= 0 || this.#timer) {
151
+ return;
152
+ }
153
+ const pass = () => {
154
+ if (this.#running) {
155
+ return;
156
+ }
157
+ this.#running = true;
158
+ void this.renewOnce().finally(() => {
159
+ this.#running = false;
160
+ });
161
+ };
162
+ pass();
163
+ this.#timer = setInterval(pass, intervalSeconds * 1000);
164
+ this.#timer.unref?.();
165
+ }
166
+ stop() {
167
+ if (this.#timer) {
168
+ clearInterval(this.#timer);
169
+ }
170
+ this.#timer = undefined;
171
+ }
172
+ }
93
173
  /**
94
174
  * The outbox, read when a push was missed or no address is registered
95
175
  * (`GET …/self/deliveries`): each delivery of every bound installation
@@ -25,7 +25,7 @@ export { DatalayerHostClient, HostRefusedError, type BoundHost, type HostProvide
25
25
  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 SessionBinder, type Starter, type StarterSource, type TurnProvenance, type TurnStream, } from './agentClient';
26
26
  export { hostSessionUid } from './sessionUid';
27
27
  export { DATALAYER_ONLY, MAIL_WORDS, RENDERERS, renderApproval, type RenderedAction, type RenderedField, } from './approvalRenderers';
28
- export { DELIVERY_PATH, DELIVERY_ROUTE, DeliveryPoller, deliveryRoute, receiveDelivery, type BoundHostKey, type DeliveryClaimStore, type DeliveryJob, type DeliverySink, } from './deliveries';
28
+ export { DELIVERY_PATH, DELIVERY_ROUTE, DeliveryPoller, DeliveryRenewal, deliveryRoute, receiveDelivery, type BoundHostKey, type DeliveryClaimStore, type DeliveryJob, type DeliverySecret, type DeliverySink, } from './deliveries';
29
29
  export { TurnState, type TurnEnding, type TurnFile, type TurnTool, } from './turnState';
30
30
  export { resolveApplication, usableAllowances, type AllowanceView, type ApplicationRefusal, type ApplicationResolution, type ChannelRule, } from './resolution';
31
31
  export { MemoryWorkQueue, tablePrefixOf, type ConnectionPool, type Queryable, type QueryAnswer, type WorkQueue, } from './queue';
@@ -30,7 +30,7 @@ export { DatalayerHostClient, HostRefusedError, } from './client.js';
30
30
  export { agUiEventsOf, assertTrustedStreamUrl, DevelopmentCredentials, HostKeyCredentials, hostSessionOf, HostStarters, HttpAgentClient, InstallationCredentials, lastAnswer, } from './agentClient.js';
31
31
  export { hostSessionUid } from './sessionUid.js';
32
32
  export { DATALAYER_ONLY, MAIL_WORDS, RENDERERS, renderApproval, } from './approvalRenderers.js';
33
- export { DELIVERY_PATH, DELIVERY_ROUTE, DeliveryPoller, deliveryRoute, receiveDelivery, } from './deliveries.js';
33
+ export { DELIVERY_PATH, DELIVERY_ROUTE, DeliveryPoller, DeliveryRenewal, deliveryRoute, receiveDelivery, } from './deliveries.js';
34
34
  export { TurnState, } from './turnState.js';
35
35
  export { resolveApplication, usableAllowances, } from './resolution.js';
36
36
  export { MemoryWorkQueue, tablePrefixOf, } from './queue.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@datalayer/agent-runtimes",
3
- "version": "1.6.33",
3
+ "version": "1.6.35",
4
4
  "type": "module",
5
5
  "workspaces": [
6
6
  ".",