@coasys/ad4m 0.13.1-staging.4 → 0.13.1-staging.6

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.
Files changed (63) hide show
  1. package/lib/index.cjs +807 -275
  2. package/lib/index.js +804 -276
  3. package/lib/src/Ad4mClient.d.ts +6 -0
  4. package/lib/src/Ad4mClient.js +8 -0
  5. package/lib/src/apiClient.d.ts +32 -0
  6. package/lib/src/apiClient.js +132 -13
  7. package/lib/src/generated/api/AgentMessage.d.ts +10 -0
  8. package/lib/src/generated/api/AgentMessage.js +2 -0
  9. package/lib/src/generated/api/AgentReply.d.ts +9 -0
  10. package/lib/src/generated/api/AgentReply.js +2 -0
  11. package/lib/src/generated/api/RpcMethods.d.ts +6 -0
  12. package/lib/src/generated/api/RpcMethods.js +1 -0
  13. package/lib/src/generated/api/RunAgentRequest.d.ts +26 -0
  14. package/lib/src/generated/api/RunAgentRequest.js +1 -0
  15. package/lib/src/generated/api/index.d.ts +3 -0
  16. package/lib/src/index.d.ts +1 -0
  17. package/lib/src/index.js +1 -0
  18. package/lib/src/model/Ad4mModel.d.ts +7 -0
  19. package/lib/src/model/Ad4mModel.js +16 -13
  20. package/lib/src/model/ModelQueryBuilder.d.ts +2 -0
  21. package/lib/src/model/ModelQueryBuilder.js +36 -57
  22. package/lib/src/model/types.d.ts +6 -0
  23. package/lib/src/neighbourhood/SfuManager.d.ts +15 -0
  24. package/lib/src/neighbourhood/SfuManager.js +39 -2
  25. package/lib/src/perspectives/LiveQuery.d.ts +40 -4
  26. package/lib/src/perspectives/LiveQuery.js +94 -10
  27. package/lib/src/perspectives/Mentioning.d.ts +37 -0
  28. package/lib/src/perspectives/Mentioning.js +58 -0
  29. package/lib/src/perspectives/PerspectiveClient.d.ts +26 -2
  30. package/lib/src/perspectives/PerspectiveClient.js +19 -4
  31. package/lib/src/perspectives/PerspectiveProxy.d.ts +34 -3
  32. package/lib/src/perspectives/PerspectiveProxy.js +52 -16
  33. package/lib/src/perspectives/TextContent.d.ts +4 -0
  34. package/lib/src/perspectives/TextContent.js +4 -0
  35. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +104 -12
  36. package/lib/src/perspectives/WakerSubscriptionManager.js +252 -66
  37. package/package.json +2 -2
  38. package/src/Ad4mClient.ts +9 -0
  39. package/src/apiClient.test.ts +467 -3
  40. package/src/apiClient.ts +133 -13
  41. package/src/generated/api/AgentMessage.ts +10 -0
  42. package/src/generated/api/AgentReply.ts +10 -0
  43. package/src/generated/api/RpcMethods.ts +4 -0
  44. package/src/generated/api/RunAgentRequest.ts +26 -0
  45. package/src/generated/api/index.ts +3 -0
  46. package/src/index.ts +1 -0
  47. package/src/model/Ad4mModel.test.ts +128 -364
  48. package/src/model/Ad4mModel.ts +16 -17
  49. package/src/model/ModelQueryBuilder.ts +39 -59
  50. package/src/model/types.ts +6 -0
  51. package/src/model/write-round-trips.test.ts +215 -0
  52. package/src/neighbourhood/SfuManager.test.ts +151 -2
  53. package/src/neighbourhood/SfuManager.ts +38 -1
  54. package/src/perspectives/LiveQuery.test.ts +173 -1
  55. package/src/perspectives/LiveQuery.ts +110 -10
  56. package/src/perspectives/Mentioning.test.ts +78 -0
  57. package/src/perspectives/Mentioning.ts +42 -0
  58. package/src/perspectives/PerspectiveClient.ts +36 -4
  59. package/src/perspectives/PerspectiveProxy.test.ts +24 -2
  60. package/src/perspectives/PerspectiveProxy.ts +61 -16
  61. package/src/perspectives/TextContent.ts +4 -0
  62. package/src/perspectives/WakerSubscriptionManager.test.ts +608 -152
  63. package/src/perspectives/WakerSubscriptionManager.ts +313 -67
@@ -45,6 +45,12 @@ export declare class Ad4mClient {
45
45
  * new client. Returns a function that removes the callback.
46
46
  */
47
47
  onAuthFailed(callback: (reason: string) => void): () => void;
48
+ /**
49
+ * Reconnect now if the connection to the executor dropped and the client is
50
+ * waiting out its backoff: for a host that knows the executor is back (it
51
+ * restarted it, or the device woke). A no-op while connected or connecting.
52
+ */
53
+ reconnectNow(): void;
48
54
  /** Close all event connections and clear in-memory caches */
49
55
  close(): void;
50
56
  }
@@ -104,6 +104,14 @@ export class Ad4mClient {
104
104
  onAuthFailed(callback) {
105
105
  return __classPrivateFieldGet(this, _Ad4mClient_apiClient, "f").onAuthFailed(callback);
106
106
  }
107
+ /**
108
+ * Reconnect now if the connection to the executor dropped and the client is
109
+ * waiting out its backoff: for a host that knows the executor is back (it
110
+ * restarted it, or the device woke). A no-op while connected or connecting.
111
+ */
112
+ reconnectNow() {
113
+ __classPrivateFieldGet(this, _Ad4mClient_apiClient, "f").reconnectNow();
114
+ }
107
115
  /** Close all event connections and clear in-memory caches */
108
116
  close() {
109
117
  __classPrivateFieldGet(this, _Ad4mClient_agentClient, "f").clearByDidCache();
@@ -56,6 +56,14 @@ export declare class ApiClient {
56
56
  private _wsReconnectTimer;
57
57
  private _wsReconnectDelay;
58
58
  private _wsPingTimer;
59
+ /** When the open socket was first pinged since it last delivered a message; null while none is unanswered. */
60
+ private _wsPingedAt;
61
+ /** When that ping could have reached the executor, which reads it only after what the socket sent before it. */
62
+ private _wsPingArrivesBy;
63
+ /** When everything the open socket sent so far could have crossed a SLOWEST_LINK_BYTES_PER_MS link.
64
+ * A message from the socket does not move it back: hearing from the executor says nothing
65
+ * about how much of a large upload has reached it. */
66
+ private _wsSentBy;
59
67
  private _watching;
60
68
  private _watchScheduled;
61
69
  private _watchDone;
@@ -71,8 +79,32 @@ export declare class ApiClient {
71
79
  * reconnecting and tell the `onAuthFailed` callbacks, once. */
72
80
  private _failAuth;
73
81
  private _startPing;
82
+ /** Send on `ws`, counting how long what the open socket sent could take to cross the slowest link. */
83
+ private _send;
84
+ /** The socket answered nothing for a whole ping interval: treat it as
85
+ * closed now. Its close event can take minutes on a dead connection,
86
+ * since the close frame gets no answer either; `_onClose` ignores it then. */
87
+ private _dropSilentSocket;
74
88
  private _stopPing;
75
89
  private _scheduleReconnect;
90
+ /** End the wait for the next dial, if one is pending, without dialling. */
91
+ private _cancelReconnect;
92
+ /**
93
+ * Dial now if the client is waiting out its reconnect backoff (up to 30 s)
94
+ * instead of letting the wait run out. For the moments the host knows the
95
+ * executor may be reachable again: an executor it restarted is up, the
96
+ * device woke. In a browser the client does this itself on `online` and when
97
+ * the page becomes visible. Does nothing while a socket is open or
98
+ * connecting, after `closeAll()` with nothing to reconnect, or once the
99
+ * executor refused the token.
100
+ */
101
+ reconnectNow(): void;
102
+ private _wakeListening;
103
+ /** `online` always; `visibilitychange` only when the page became visible. */
104
+ private readonly _onWake;
105
+ /** Listen for `online` and `visibilitychange` exactly while a reconnect
106
+ * timer is pending. Outside a browser (no `window`) it registers nothing. */
107
+ private _listenForWake;
76
108
  /**
77
109
  * Call an executor method over the WebSocket, connecting first if needed.
78
110
  * Params and result are typed by the executor's method table
@@ -18,6 +18,34 @@ const MAX_RECONNECT_DELAY_MS = 30000;
18
18
  * MAX_WATCH_RETRIES times in a row. */
19
19
  const WATCH_RETRY_DELAY_MS = 1000;
20
20
  const MAX_WATCH_RETRIES = 5;
21
+ /** An open socket sends a ping this often, and must deliver some message
22
+ * (the pong will do) within an interval of the first ping it left
23
+ * unanswered. After a network switch a socket can stay OPEN for minutes with
24
+ * no close event, since no FIN or RST ever arrives; this notices it within
25
+ * two intervals. */
26
+ const PING_INTERVAL_MS = 10000;
27
+ /** The slowest link a socket is given time for. The executor reads a ping
28
+ * only after the frames sent before it, so a ping left unanswered counts as
29
+ * silence only once everything the socket sent before that ping could have
30
+ * crossed this link and PONG_RETURN_MS more have passed, if that takes longer
31
+ * than PING_INTERVAL_MS. Messages that come in meanwhile do not shorten this:
32
+ * they say nothing about how far an upload has got. */
33
+ const SLOWEST_LINK_BYTES_PER_MS = 16; // 16 kB/s
34
+ /** How long a pong gets to come back after its ping could have been read
35
+ * behind a large write. Shorter than PING_INTERVAL_MS, so the few ms a small
36
+ * frame adds before a ping on an idle socket never cost a ping interval. */
37
+ const PONG_RETURN_MS = 5000;
38
+ /** The bytes `text` takes as UTF-8, as a WebSocket text frame sends it. */
39
+ function utf8Length(text) {
40
+ let bytes = text.length;
41
+ for (let i = 0; i < text.length; i++) {
42
+ const unit = text.charCodeAt(i);
43
+ // A surrogate is half of a 4-byte pair: 2 units, 2 extra bytes.
44
+ if (unit >= 0x80)
45
+ bytes += unit < 0x800 || (unit >= 0xd800 && unit <= 0xdfff) ? 1 : 2;
46
+ }
47
+ return bytes;
48
+ }
21
49
  let _idCounter = 0;
22
50
  function nextId() {
23
51
  return String(++_idCounter);
@@ -52,6 +80,14 @@ export class ApiClient {
52
80
  this._wsReconnectTimer = null;
53
81
  this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
54
82
  this._wsPingTimer = null;
83
+ /** When the open socket was first pinged since it last delivered a message; null while none is unanswered. */
84
+ this._wsPingedAt = null;
85
+ /** When that ping could have reached the executor, which reads it only after what the socket sent before it. */
86
+ this._wsPingArrivesBy = 0;
87
+ /** When everything the open socket sent so far could have crossed a SLOWEST_LINK_BYTES_PER_MS link.
88
+ * A message from the socket does not move it back: hearing from the executor says nothing
89
+ * about how much of a large upload has reached it. */
90
+ this._wsSentBy = 0;
55
91
  // The executor sends a socket only the events it asked for (`events.watch`).
56
92
  // What the executor has for the open socket, as sent; a new socket has `{}`.
57
93
  this._watching = '{}';
@@ -61,6 +97,13 @@ export class ApiClient {
61
97
  this._watchSent = Promise.resolve();
62
98
  this._watchRetries = 0;
63
99
  this._watchRetryTimer = null;
100
+ this._wakeListening = false;
101
+ /** `online` always; `visibilitychange` only when the page became visible. */
102
+ this._onWake = (event) => {
103
+ if (event.type === 'visibilitychange' && typeof document !== 'undefined' && document.visibilityState !== 'visible')
104
+ return;
105
+ this.reconnectNow();
106
+ };
64
107
  this.baseUrl = baseUrl;
65
108
  this.token = token;
66
109
  this._webSocketImpl = webSocketImpl;
@@ -84,6 +127,9 @@ export class ApiClient {
84
127
  return;
85
128
  if (this._authFailed !== null)
86
129
  throw new RpcError(401, this._authFailed);
130
+ // A dial ends any wait for one: a call or subscriber that dials during the backoff
131
+ // leaves no timer behind to swallow the retry after this socket's own drop.
132
+ this._cancelReconnect();
87
133
  const WsImpl = this._webSocketImpl ?? globalThis.WebSocket;
88
134
  const ws = new WsImpl(this._getWsUrl());
89
135
  this._ws = ws;
@@ -108,6 +154,8 @@ export class ApiClient {
108
154
  // Only watchApplied() awaits this; a close before open is not an error otherwise.
109
155
  this._wsOpen.catch(() => { });
110
156
  ws.onmessage = (event) => {
157
+ if (this._ws === ws)
158
+ this._wsPingedAt = null;
111
159
  let parsed;
112
160
  try {
113
161
  parsed = JSON.parse(event.data);
@@ -133,7 +181,8 @@ export class ApiClient {
133
181
  this._failAuth(rpcError.body);
134
182
  return;
135
183
  }
136
- if (parsed.type === 'pong')
184
+ // A dropped socket's events are not this client's any more: its successor watches again.
185
+ if (parsed.type === 'pong' || this._ws !== ws)
137
186
  return;
138
187
  const perspective = parsed.perspectiveUuid;
139
188
  const regs = this._handlers.get(parsed.type);
@@ -156,14 +205,14 @@ export class ApiClient {
156
205
  if (this._ws !== ws)
157
206
  return;
158
207
  this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
159
- this._startPing();
208
+ this._startPing(ws);
160
209
  // The watch goes out before the queued calls, so the events they cause reach listeners.
161
210
  this._watching = '{}';
162
211
  this._watchRetries = 0;
163
212
  this._flushWatch();
164
213
  for (const pending of this._pendingCalls.values()) {
165
214
  if (!pending.sent) {
166
- ws.send(pending.message);
215
+ this._send(ws, pending.message);
167
216
  pending.sent = true;
168
217
  }
169
218
  }
@@ -214,13 +263,40 @@ export class ApiClient {
214
263
  for (const cb of [...this._authFailedCallbacks])
215
264
  callSafely(cb, 'Error in auth-failed callback:', reason);
216
265
  }
217
- _startPing() {
266
+ _startPing(ws) {
218
267
  this._stopPing();
268
+ this._wsPingedAt = null;
269
+ this._wsSentBy = 0;
219
270
  this._wsPingTimer = setInterval(() => {
220
- if (this._ws?.readyState === 1 /* OPEN */) {
221
- this._ws.send(JSON.stringify({ type: 'ping' }));
271
+ if (this._ws !== ws)
272
+ return;
273
+ const ping = JSON.stringify({ type: 'ping' });
274
+ if (this._wsPingedAt === null) {
275
+ this._wsPingedAt = performance.now();
276
+ this._send(ws, ping);
277
+ this._wsPingArrivesBy = this._wsSentBy;
278
+ return;
279
+ }
280
+ if (performance.now() >= Math.max(this._wsPingedAt + PING_INTERVAL_MS, this._wsPingArrivesBy + PONG_RETURN_MS)) {
281
+ this._dropSilentSocket(ws);
282
+ return;
222
283
  }
223
- }, 30000);
284
+ this._send(ws, ping);
285
+ }, PING_INTERVAL_MS);
286
+ }
287
+ /** Send on `ws`, counting how long what the open socket sent could take to cross the slowest link. */
288
+ _send(ws, text) {
289
+ if (this._ws === ws)
290
+ this._wsSentBy = Math.max(this._wsSentBy, performance.now()) + utf8Length(text) / SLOWEST_LINK_BYTES_PER_MS;
291
+ ws.send(text);
292
+ }
293
+ /** The socket answered nothing for a whole ping interval: treat it as
294
+ * closed now. Its close event can take minutes on a dead connection,
295
+ * since the close frame gets no answer either; `_onClose` ignores it then. */
296
+ _dropSilentSocket(ws) {
297
+ console.warn(`WebSocket silent for ${performance.now() - (this._wsPingedAt ?? performance.now())} ms after a ping; reconnecting`);
298
+ this._onClose(ws);
299
+ ws.close();
224
300
  }
225
301
  _stopPing() {
226
302
  if (this._wsPingTimer) {
@@ -235,8 +311,54 @@ export class ApiClient {
235
311
  this._wsReconnectDelay = Math.min(this._wsReconnectDelay * 2, MAX_RECONNECT_DELAY_MS);
236
312
  this._wsReconnectTimer = setTimeout(() => {
237
313
  this._wsReconnectTimer = null;
314
+ this._listenForWake(false);
238
315
  this._ensureWs();
239
316
  }, delay);
317
+ this._listenForWake(true);
318
+ }
319
+ /** End the wait for the next dial, if one is pending, without dialling. */
320
+ _cancelReconnect() {
321
+ if (this._wsReconnectTimer) {
322
+ clearTimeout(this._wsReconnectTimer);
323
+ this._wsReconnectTimer = null;
324
+ }
325
+ this._listenForWake(false);
326
+ }
327
+ /**
328
+ * Dial now if the client is waiting out its reconnect backoff (up to 30 s)
329
+ * instead of letting the wait run out. For the moments the host knows the
330
+ * executor may be reachable again: an executor it restarted is up, the
331
+ * device woke. In a browser the client does this itself on `online` and when
332
+ * the page becomes visible. Does nothing while a socket is open or
333
+ * connecting, after `closeAll()` with nothing to reconnect, or once the
334
+ * executor refused the token.
335
+ */
336
+ reconnectNow() {
337
+ if (!this._wsReconnectTimer || this._ws || this._authFailed !== null)
338
+ return;
339
+ this._cancelReconnect();
340
+ // The executor is likely back, so a failure now starts the backoff over.
341
+ this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
342
+ this._ensureWs();
343
+ }
344
+ /** Listen for `online` and `visibilitychange` exactly while a reconnect
345
+ * timer is pending. Outside a browser (no `window`) it registers nothing. */
346
+ _listenForWake(on) {
347
+ if (on === this._wakeListening)
348
+ return;
349
+ const win = typeof window !== 'undefined' ? window : undefined;
350
+ if (typeof win?.addEventListener !== 'function')
351
+ return;
352
+ const doc = typeof document !== 'undefined' && typeof document.addEventListener === 'function' ? document : undefined;
353
+ this._wakeListening = on;
354
+ if (on) {
355
+ win.addEventListener('online', this._onWake);
356
+ doc?.addEventListener('visibilitychange', this._onWake);
357
+ }
358
+ else {
359
+ win.removeEventListener('online', this._onWake);
360
+ doc?.removeEventListener('visibilitychange', this._onWake);
361
+ }
240
362
  }
241
363
  // ── RPC call method ─────────────────────────────────────────────────────
242
364
  /**
@@ -282,7 +404,7 @@ export class ApiClient {
282
404
  }, timeoutMs);
283
405
  const onAbort = () => {
284
406
  if (pending.sent && this._ws?.readyState === 1 /* OPEN */) {
285
- this._ws.send(JSON.stringify({ id: nextId(), type: 'request.cancel', params: { targetId: id } }));
407
+ this._send(this._ws, JSON.stringify({ id: nextId(), type: 'request.cancel', params: { targetId: id } }));
286
408
  }
287
409
  settle(() => reject(new DOMException('Aborted', 'AbortError')));
288
410
  };
@@ -305,7 +427,7 @@ export class ApiClient {
305
427
  return;
306
428
  }
307
429
  if (this._ws.readyState === 1 /* OPEN */) {
308
- this._ws.send(message);
430
+ this._send(this._ws, message);
309
431
  pending.sent = true;
310
432
  }
311
433
  });
@@ -426,10 +548,7 @@ export class ApiClient {
426
548
  clearTimeout(this._watchRetryTimer);
427
549
  this._watchRetryTimer = null;
428
550
  }
429
- if (this._wsReconnectTimer) {
430
- clearTimeout(this._wsReconnectTimer);
431
- this._wsReconnectTimer = null;
432
- }
551
+ this._cancelReconnect();
433
552
  const ws = this._ws;
434
553
  this._ws = null;
435
554
  this._wsOpen = null;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * One turn of the conversation, as the caller holds it.
3
+ */
4
+ export type AgentMessage = {
5
+ /**
6
+ * `user` or `assistant`.
7
+ */
8
+ role: string;
9
+ content: string;
10
+ };
@@ -0,0 +1,2 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ export {};
@@ -0,0 +1,9 @@
1
+ /**
2
+ * How a session ended.
3
+ */
4
+ export type AgentReply = {
5
+ /**
6
+ * What the model said last: its answer to the person.
7
+ */
8
+ text: string;
9
+ };
@@ -0,0 +1,2 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ export {};
@@ -5,6 +5,7 @@ import type { Agent } from "./Agent";
5
5
  import type { AgentAddEntanglementProofsParams } from "./AgentAddEntanglementProofsParams";
6
6
  import type { AgentByDidParams } from "./AgentByDidParams";
7
7
  import type { AgentRemoveAppParams } from "./AgentRemoveAppParams";
8
+ import type { AgentReply } from "./AgentReply";
8
9
  import type { AgentRevokeTokenParams } from "./AgentRevokeTokenParams";
9
10
  import type { AgentSignature } from "./AgentSignature";
10
11
  import type { AgentStatus } from "./AgentStatus";
@@ -125,6 +126,7 @@ import type { PublishLanguageRequest } from "./PublishLanguageRequest";
125
126
  import type { PublishNeighbourhoodRequest } from "./PublishNeighbourhoodRequest";
126
127
  import type { RequestCapabilityRequest } from "./RequestCapabilityRequest";
127
128
  import type { RequestPaymentRequest } from "./RequestPaymentRequest";
129
+ import type { RunAgentRequest } from "./RunAgentRequest";
128
130
  import type { RunInterpretationRequest } from "./RunInterpretationRequest";
129
131
  import type { RunInterpretationWithHarnessRequest } from "./RunInterpretationWithHarnessRequest";
130
132
  import type { RuntimeComputeLogParams } from "./RuntimeComputeLogParams";
@@ -636,6 +638,10 @@ export interface RpcMethods {
636
638
  params: PerspectiveSubscriptionParams;
637
639
  result: PerspectiveResynced;
638
640
  };
641
+ "perspective.runAgent": {
642
+ params: RunAgentRequest;
643
+ result: AgentReply;
644
+ };
639
645
  "perspective.runInterpretation": {
640
646
  params: RunInterpretationRequest;
641
647
  result: Array<string>;
@@ -92,6 +92,7 @@ export const LONG_METHODS = new Set([
92
92
  "language.publish",
93
93
  "neighbourhood.join",
94
94
  "neighbourhood.publish",
95
+ "perspective.runAgent",
95
96
  "perspective.runInterpretation",
96
97
  "perspective.runInterpretationWithHarness",
97
98
  "runtime.restartHolochain",
@@ -0,0 +1,26 @@
1
+ import type { AgentMessage } from "./AgentMessage";
2
+ export type RunAgentRequest = {
3
+ uuid: string;
4
+ /**
5
+ * The conversation so far, the person's request last.
6
+ */
7
+ messages: Array<AgentMessage>;
8
+ /**
9
+ * What the person is looking at, as a hint for the model (`{ "recordId": "…" }`).
10
+ */
11
+ context?: Record<string, unknown>;
12
+ /**
13
+ * Tools that write which the model may call — `instance_update`, `template_update`; only
14
+ * tools that write inside the perspective (`agent_session::SESSION_WRITES`). None means a
15
+ * session that only reads.
16
+ */
17
+ writeTools?: Array<string>;
18
+ /**
19
+ * A model id; the node's default language model when absent.
20
+ */
21
+ model?: string;
22
+ /**
23
+ * How many tool calls the model may make before it must answer. Default 20.
24
+ */
25
+ maxToolCalls?: number;
26
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -2,6 +2,8 @@ export type { AddLinkExpressionRequest } from "./AddLinkExpressionRequest";
2
2
  export type { AddLinkRequest } from "./AddLinkRequest";
3
3
  export type { AddLinksBulkRequest } from "./AddLinksBulkRequest";
4
4
  export type { AddSdnaRequest } from "./AddSdnaRequest";
5
+ export type { AgentMessage } from "./AgentMessage";
6
+ export type { AgentReply } from "./AgentReply";
5
7
  export type { AgentsByDidsRequest } from "./AgentsByDidsRequest";
6
8
  export type { ApplyTemplateRequest } from "./ApplyTemplateRequest";
7
9
  export type { CommitBatchRequest } from "./CommitBatchRequest";
@@ -33,6 +35,7 @@ export type { QueryRequest } from "./QueryRequest";
33
35
  export type { RemoveLinkRequest } from "./RemoveLinkRequest";
34
36
  export type { RemoveLinksBulkRequest } from "./RemoveLinksBulkRequest";
35
37
  export type { ResyncSubscriptionRequest } from "./ResyncSubscriptionRequest";
38
+ export type { RunAgentRequest } from "./RunAgentRequest";
36
39
  export type { RunInterpretationRequest } from "./RunInterpretationRequest";
37
40
  export type { SetDefaultModelRequest } from "./SetDefaultModelRequest";
38
41
  export type { SetFreeHostingEnabledRequest } from "./SetFreeHostingEnabledRequest";
@@ -21,6 +21,7 @@ export * from "./perspectives/AutoProcessor";
21
21
  export * from "./perspectives/InterpretationModels";
22
22
  export * from "./perspectives/FlowModels";
23
23
  export * from "./perspectives/TextContent";
24
+ export * from "./perspectives/Mentioning";
24
25
  export * from "./perspectives/Container";
25
26
  export * from "./perspectives/FlowInstance";
26
27
  export * from "./perspectives/SparqlBindings";
package/lib/src/index.js CHANGED
@@ -21,6 +21,7 @@ export * from "./perspectives/AutoProcessor";
21
21
  export * from "./perspectives/InterpretationModels";
22
22
  export * from "./perspectives/FlowModels";
23
23
  export * from "./perspectives/TextContent";
24
+ export * from "./perspectives/Mentioning";
24
25
  export * from "./perspectives/Container";
25
26
  // Also exports FlowFireOutcome / FlowProposeResult, the result shapes of the
26
27
  // flow write API — they live beside the `proposeTransition()` surface.
@@ -346,6 +346,13 @@ export declare class Ad4mModel {
346
346
  * @internal
347
347
  */
348
348
  static parseModelResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, raw: any, include?: IncludeMap, properties?: string[]): T[];
349
+ /**
350
+ * Snapshot freshly built instances for dirty tracking, with the relations
351
+ * `include` loaded (its `$`-prefixed projection keys are not relations).
352
+ * Used by every query path, and by ModelQueryBuilder for pushed results.
353
+ * @internal
354
+ */
355
+ static takeSnapshots(instances: Ad4mModel[], include?: IncludeMap): void;
349
356
  /**
350
357
  * Build the wire parameters for one query over several classes.
351
358
  *
@@ -1137,6 +1137,20 @@ export class Ad4mModel {
1137
1137
  return [];
1138
1138
  return arr.map((json) => jsonToModelInstance(this, perspective, json, include, properties));
1139
1139
  }
1140
+ /**
1141
+ * Snapshot freshly built instances for dirty tracking, with the relations
1142
+ * `include` loaded (its `$`-prefixed projection keys are not relations).
1143
+ * Used by every query path, and by ModelQueryBuilder for pushed results.
1144
+ * @internal
1145
+ */
1146
+ static takeSnapshots(instances, include) {
1147
+ const relations = include
1148
+ ? Object.fromEntries(Object.entries(include).filter(([k]) => !k.startsWith('$')))
1149
+ : undefined;
1150
+ const snapshot = relations && Object.keys(relations).length > 0 ? relations : undefined;
1151
+ for (const inst of instances)
1152
+ inst.takeSnapshot?.(snapshot);
1153
+ }
1140
1154
  // ── One query over several classes (#1238) ────────────────────────────────
1141
1155
  /**
1142
1156
  * Build the wire parameters for one query over several classes.
@@ -1238,12 +1252,7 @@ export class Ad4mModel {
1238
1252
  const { classNames, queryJson } = Ad4mModel.prepareUnionQueryParams(classes, query);
1239
1253
  const result = await perspective.modelQuery(classNames, queryJson, options);
1240
1254
  const results = Ad4mModel.parseUnionResult(classes, perspective, result, query.include, query.properties);
1241
- const snapshotRelations = query.include
1242
- ? Object.fromEntries(Object.entries(query.include).filter(([k]) => !k.startsWith('$')))
1243
- : undefined;
1244
- for (const inst of results) {
1245
- inst.takeSnapshot?.(snapshotRelations && Object.keys(snapshotRelations).length > 0 ? snapshotRelations : undefined);
1246
- }
1255
+ Ad4mModel.takeSnapshots(results, query.include);
1247
1256
  return { results, totalCount: result.totalCount };
1248
1257
  }
1249
1258
  /**
@@ -1309,13 +1318,7 @@ export class Ad4mModel {
1309
1318
  const instances = result.instances.map((json) => {
1310
1319
  return jsonToModelInstance(this, perspective, json, query.include, query.properties);
1311
1320
  });
1312
- // Take snapshots for dirty tracking (exclude $-prefixed projection keys)
1313
- const snapshotRelations = query.include
1314
- ? Object.fromEntries(Object.entries(query.include).filter(([k]) => !k.startsWith('$')))
1315
- : undefined;
1316
- for (const inst of instances) {
1317
- inst.takeSnapshot(snapshotRelations && Object.keys(snapshotRelations).length > 0 ? snapshotRelations : undefined);
1318
- }
1321
+ Ad4mModel.takeSnapshots(instances, query.include);
1319
1322
  return {
1320
1323
  results: instances,
1321
1324
  totalCount: result.totalCount,
@@ -42,6 +42,8 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
42
42
  private execute;
43
43
  /** Build model instances from a raw result pushed by a subscription. */
44
44
  private parse;
45
+ /** Snapshot instances for dirty tracking, as `execute` does for its rows. */
46
+ private takeSnapshots;
45
47
  /** Ends the current subscription, if any, on the client and the executor. */
46
48
  dispose(): void;
47
49
  /** Open a live model query for `params` as the current subscription.