@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
package/src/apiClient.ts CHANGED
@@ -59,6 +59,37 @@ const MAX_RECONNECT_DELAY_MS = 30_000
59
59
  const WATCH_RETRY_DELAY_MS = 1_000
60
60
  const MAX_WATCH_RETRIES = 5
61
61
 
62
+ /** An open socket sends a ping this often, and must deliver some message
63
+ * (the pong will do) within an interval of the first ping it left
64
+ * unanswered. After a network switch a socket can stay OPEN for minutes with
65
+ * no close event, since no FIN or RST ever arrives; this notices it within
66
+ * two intervals. */
67
+ const PING_INTERVAL_MS = 10_000
68
+
69
+ /** The slowest link a socket is given time for. The executor reads a ping
70
+ * only after the frames sent before it, so a ping left unanswered counts as
71
+ * silence only once everything the socket sent before that ping could have
72
+ * crossed this link and PONG_RETURN_MS more have passed, if that takes longer
73
+ * than PING_INTERVAL_MS. Messages that come in meanwhile do not shorten this:
74
+ * they say nothing about how far an upload has got. */
75
+ const SLOWEST_LINK_BYTES_PER_MS = 16 // 16 kB/s
76
+
77
+ /** How long a pong gets to come back after its ping could have been read
78
+ * behind a large write. Shorter than PING_INTERVAL_MS, so the few ms a small
79
+ * frame adds before a ping on an idle socket never cost a ping interval. */
80
+ const PONG_RETURN_MS = 5_000
81
+
82
+ /** The bytes `text` takes as UTF-8, as a WebSocket text frame sends it. */
83
+ function utf8Length(text: string): number {
84
+ let bytes = text.length
85
+ for (let i = 0; i < text.length; i++) {
86
+ const unit = text.charCodeAt(i)
87
+ // A surrogate is half of a 4-byte pair: 2 units, 2 extra bytes.
88
+ if (unit >= 0x80) bytes += unit < 0x800 || (unit >= 0xd800 && unit <= 0xdfff) ? 1 : 2
89
+ }
90
+ return bytes
91
+ }
92
+
62
93
  let _idCounter = 0
63
94
  function nextId(): string {
64
95
  return String(++_idCounter)
@@ -133,6 +164,14 @@ export class ApiClient {
133
164
  private _wsReconnectTimer: ReturnType<typeof setTimeout> | null = null
134
165
  private _wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS
135
166
  private _wsPingTimer: ReturnType<typeof setInterval> | null = null
167
+ /** When the open socket was first pinged since it last delivered a message; null while none is unanswered. */
168
+ private _wsPingedAt: number | null = null
169
+ /** When that ping could have reached the executor, which reads it only after what the socket sent before it. */
170
+ private _wsPingArrivesBy = 0
171
+ /** When everything the open socket sent so far could have crossed a SLOWEST_LINK_BYTES_PER_MS link.
172
+ * A message from the socket does not move it back: hearing from the executor says nothing
173
+ * about how much of a large upload has reached it. */
174
+ private _wsSentBy = 0
136
175
  // The executor sends a socket only the events it asked for (`events.watch`).
137
176
  // What the executor has for the open socket, as sent; a new socket has `{}`.
138
177
  private _watching: string | null = '{}'
@@ -154,6 +193,9 @@ export class ApiClient {
154
193
  private _ensureWs(): void {
155
194
  if (this._ws) return
156
195
  if (this._authFailed !== null) throw new RpcError(401, this._authFailed)
196
+ // A dial ends any wait for one: a call or subscriber that dials during the backoff
197
+ // leaves no timer behind to swallow the retry after this socket's own drop.
198
+ this._cancelReconnect()
157
199
  const WsImpl = this._webSocketImpl ?? globalThis.WebSocket
158
200
  const ws = new WsImpl(this._getWsUrl())
159
201
  this._ws = ws
@@ -178,6 +220,7 @@ export class ApiClient {
178
220
  this._wsOpen.catch(() => {})
179
221
 
180
222
  ws.onmessage = (event) => {
223
+ if (this._ws === ws) this._wsPingedAt = null
181
224
  let parsed: Record<string, unknown>
182
225
  try { parsed = JSON.parse(event.data) } catch (e) {
183
226
  console.error('Error parsing WebSocket data:', e)
@@ -198,7 +241,8 @@ export class ApiClient {
198
241
  if (rpcError.status === 401) this._failAuth(rpcError.body)
199
242
  return
200
243
  }
201
- if (parsed.type === 'pong') return
244
+ // A dropped socket's events are not this client's any more: its successor watches again.
245
+ if (parsed.type === 'pong' || this._ws !== ws) return
202
246
  const perspective = parsed.perspectiveUuid
203
247
  const regs = this._handlers.get(parsed.type as string)
204
248
  // Like DOM events: a handler added during dispatch waits for the
@@ -219,14 +263,14 @@ export class ApiClient {
219
263
  // A socket closed by _closeWs() must not take the calls queued for its successor.
220
264
  if (this._ws !== ws) return
221
265
  this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS
222
- this._startPing()
266
+ this._startPing(ws)
223
267
  // The watch goes out before the queued calls, so the events they cause reach listeners.
224
268
  this._watching = '{}'
225
269
  this._watchRetries = 0
226
270
  this._flushWatch()
227
271
  for (const pending of this._pendingCalls.values()) {
228
272
  if (!pending.sent) {
229
- ws.send(pending.message)
273
+ this._send(ws, pending.message)
230
274
  pending.sent = true
231
275
  }
232
276
  }
@@ -270,13 +314,40 @@ export class ApiClient {
270
314
  for (const cb of [...this._authFailedCallbacks]) callSafely(cb, 'Error in auth-failed callback:', reason)
271
315
  }
272
316
 
273
- private _startPing(): void {
317
+ private _startPing(ws: WebSocket): void {
274
318
  this._stopPing()
319
+ this._wsPingedAt = null
320
+ this._wsSentBy = 0
275
321
  this._wsPingTimer = setInterval(() => {
276
- if (this._ws?.readyState === 1 /* OPEN */) {
277
- this._ws.send(JSON.stringify({ type: 'ping' }))
322
+ if (this._ws !== ws) return
323
+ const ping = JSON.stringify({ type: 'ping' })
324
+ if (this._wsPingedAt === null) {
325
+ this._wsPingedAt = performance.now()
326
+ this._send(ws, ping)
327
+ this._wsPingArrivesBy = this._wsSentBy
328
+ return
278
329
  }
279
- }, 30_000)
330
+ if (performance.now() >= Math.max(this._wsPingedAt + PING_INTERVAL_MS, this._wsPingArrivesBy + PONG_RETURN_MS)) {
331
+ this._dropSilentSocket(ws)
332
+ return
333
+ }
334
+ this._send(ws, ping)
335
+ }, PING_INTERVAL_MS)
336
+ }
337
+
338
+ /** Send on `ws`, counting how long what the open socket sent could take to cross the slowest link. */
339
+ private _send(ws: WebSocket, text: string): void {
340
+ if (this._ws === ws) this._wsSentBy = Math.max(this._wsSentBy, performance.now()) + utf8Length(text) / SLOWEST_LINK_BYTES_PER_MS
341
+ ws.send(text)
342
+ }
343
+
344
+ /** The socket answered nothing for a whole ping interval: treat it as
345
+ * closed now. Its close event can take minutes on a dead connection,
346
+ * since the close frame gets no answer either; `_onClose` ignores it then. */
347
+ private _dropSilentSocket(ws: WebSocket): void {
348
+ console.warn(`WebSocket silent for ${performance.now() - (this._wsPingedAt ?? performance.now())} ms after a ping; reconnecting`)
349
+ this._onClose(ws)
350
+ ws.close()
280
351
  }
281
352
 
282
353
  private _stopPing(): void {
@@ -292,8 +363,60 @@ export class ApiClient {
292
363
  this._wsReconnectDelay = Math.min(this._wsReconnectDelay * 2, MAX_RECONNECT_DELAY_MS)
293
364
  this._wsReconnectTimer = setTimeout(() => {
294
365
  this._wsReconnectTimer = null
366
+ this._listenForWake(false)
295
367
  this._ensureWs()
296
368
  }, delay)
369
+ this._listenForWake(true)
370
+ }
371
+
372
+ /** End the wait for the next dial, if one is pending, without dialling. */
373
+ private _cancelReconnect(): void {
374
+ if (this._wsReconnectTimer) {
375
+ clearTimeout(this._wsReconnectTimer)
376
+ this._wsReconnectTimer = null
377
+ }
378
+ this._listenForWake(false)
379
+ }
380
+
381
+ /**
382
+ * Dial now if the client is waiting out its reconnect backoff (up to 30 s)
383
+ * instead of letting the wait run out. For the moments the host knows the
384
+ * executor may be reachable again: an executor it restarted is up, the
385
+ * device woke. In a browser the client does this itself on `online` and when
386
+ * the page becomes visible. Does nothing while a socket is open or
387
+ * connecting, after `closeAll()` with nothing to reconnect, or once the
388
+ * executor refused the token.
389
+ */
390
+ reconnectNow(): void {
391
+ if (!this._wsReconnectTimer || this._ws || this._authFailed !== null) return
392
+ this._cancelReconnect()
393
+ // The executor is likely back, so a failure now starts the backoff over.
394
+ this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS
395
+ this._ensureWs()
396
+ }
397
+
398
+ private _wakeListening = false
399
+ /** `online` always; `visibilitychange` only when the page became visible. */
400
+ private readonly _onWake = (event: Event): void => {
401
+ if (event.type === 'visibilitychange' && typeof document !== 'undefined' && document.visibilityState !== 'visible') return
402
+ this.reconnectNow()
403
+ }
404
+
405
+ /** Listen for `online` and `visibilitychange` exactly while a reconnect
406
+ * timer is pending. Outside a browser (no `window`) it registers nothing. */
407
+ private _listenForWake(on: boolean): void {
408
+ if (on === this._wakeListening) return
409
+ const win = typeof window !== 'undefined' ? window : undefined
410
+ if (typeof win?.addEventListener !== 'function') return
411
+ const doc = typeof document !== 'undefined' && typeof document.addEventListener === 'function' ? document : undefined
412
+ this._wakeListening = on
413
+ if (on) {
414
+ win.addEventListener('online', this._onWake)
415
+ doc?.addEventListener('visibilitychange', this._onWake)
416
+ } else {
417
+ win.removeEventListener('online', this._onWake)
418
+ doc?.removeEventListener('visibilitychange', this._onWake)
419
+ }
297
420
  }
298
421
 
299
422
  // ── RPC call method ─────────────────────────────────────────────────────
@@ -341,7 +464,7 @@ export class ApiClient {
341
464
  }, timeoutMs)
342
465
  const onAbort = () => {
343
466
  if (pending.sent && this._ws?.readyState === 1 /* OPEN */) {
344
- this._ws.send(JSON.stringify({ id: nextId(), type: 'request.cancel', params: { targetId: id } }))
467
+ this._send(this._ws, JSON.stringify({ id: nextId(), type: 'request.cancel', params: { targetId: id } }))
345
468
  }
346
469
  settle(() => reject(new DOMException('Aborted', 'AbortError')))
347
470
  }
@@ -364,7 +487,7 @@ export class ApiClient {
364
487
  return
365
488
  }
366
489
  if (this._ws!.readyState === 1 /* OPEN */) {
367
- this._ws!.send(message)
490
+ this._send(this._ws!, message)
368
491
  pending.sent = true
369
492
  }
370
493
  })
@@ -479,10 +602,7 @@ export class ApiClient {
479
602
  clearTimeout(this._watchRetryTimer)
480
603
  this._watchRetryTimer = null
481
604
  }
482
- if (this._wsReconnectTimer) {
483
- clearTimeout(this._wsReconnectTimer)
484
- this._wsReconnectTimer = null
485
- }
605
+ this._cancelReconnect()
486
606
  const ws = this._ws
487
607
  this._ws = null
488
608
  this._wsOpen = null
@@ -0,0 +1,10 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+
3
+ /**
4
+ * One turn of the conversation, as the caller holds it.
5
+ */
6
+ export type AgentMessage = {
7
+ /**
8
+ * `user` or `assistant`.
9
+ */
10
+ role: string, content: string, };
@@ -0,0 +1,10 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+
3
+ /**
4
+ * How a session ended.
5
+ */
6
+ export type AgentReply = {
7
+ /**
8
+ * What the model said last: its answer to the person.
9
+ */
10
+ text: string, };
@@ -8,6 +8,7 @@ import type { Agent } from "./Agent";
8
8
  import type { AgentAddEntanglementProofsParams } from "./AgentAddEntanglementProofsParams";
9
9
  import type { AgentByDidParams } from "./AgentByDidParams";
10
10
  import type { AgentRemoveAppParams } from "./AgentRemoveAppParams";
11
+ import type { AgentReply } from "./AgentReply";
11
12
  import type { AgentRevokeTokenParams } from "./AgentRevokeTokenParams";
12
13
  import type { AgentSignature } from "./AgentSignature";
13
14
  import type { AgentStatus } from "./AgentStatus";
@@ -128,6 +129,7 @@ import type { PublishLanguageRequest } from "./PublishLanguageRequest";
128
129
  import type { PublishNeighbourhoodRequest } from "./PublishNeighbourhoodRequest";
129
130
  import type { RequestCapabilityRequest } from "./RequestCapabilityRequest";
130
131
  import type { RequestPaymentRequest } from "./RequestPaymentRequest";
132
+ import type { RunAgentRequest } from "./RunAgentRequest";
131
133
  import type { RunInterpretationRequest } from "./RunInterpretationRequest";
132
134
  import type { RunInterpretationWithHarnessRequest } from "./RunInterpretationWithHarnessRequest";
133
135
  import type { RuntimeComputeLogParams } from "./RuntimeComputeLogParams";
@@ -298,6 +300,7 @@ export interface RpcMethods {
298
300
  "perspective.removeLinks": { params: PerspectiveRemoveLinksParams; result: Array<DecoratedLinkExpression> };
299
301
  "perspective.removeSubject": { params: PerspectiveRemoveSubjectParams; result: boolean };
300
302
  "perspective.resyncSubscription": { params: PerspectiveSubscriptionParams; result: PerspectiveResynced };
303
+ "perspective.runAgent": { params: RunAgentRequest; result: AgentReply };
301
304
  "perspective.runInterpretation": { params: RunInterpretationRequest; result: Array<string> };
302
305
  "perspective.runInterpretationWithHarness": { params: RunInterpretationWithHarnessRequest; result: Array<string> };
303
306
  "perspective.snapshot": { params: PerspectiveUuidParams; result: DecoratedPerspective | null };
@@ -476,6 +479,7 @@ export const LONG_METHODS: ReadonlySet<RpcMethod> = new Set<RpcMethod>([
476
479
  "language.publish",
477
480
  "neighbourhood.join",
478
481
  "neighbourhood.publish",
482
+ "perspective.runAgent",
479
483
  "perspective.runInterpretation",
480
484
  "perspective.runInterpretationWithHarness",
481
485
  "runtime.restartHolochain",
@@ -0,0 +1,26 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ import type { AgentMessage } from "./AgentMessage";
3
+
4
+ export type RunAgentRequest = { uuid: string,
5
+ /**
6
+ * The conversation so far, the person's request last.
7
+ */
8
+ messages: Array<AgentMessage>,
9
+ /**
10
+ * What the person is looking at, as a hint for the model (`{ "recordId": "…" }`).
11
+ */
12
+ context?: Record<string, unknown>,
13
+ /**
14
+ * Tools that write which the model may call — `instance_update`, `template_update`; only
15
+ * tools that write inside the perspective (`agent_session::SESSION_WRITES`). None means a
16
+ * session that only reads.
17
+ */
18
+ writeTools?: Array<string>,
19
+ /**
20
+ * A model id; the node's default language model when absent.
21
+ */
22
+ model?: string,
23
+ /**
24
+ * How many tool calls the model may make before it must answer. Default 20.
25
+ */
26
+ maxToolCalls?: number, };
@@ -10,6 +10,8 @@ export type { AddLinkExpressionRequest } from "./AddLinkExpressionRequest";
10
10
  export type { AddLinkRequest } from "./AddLinkRequest";
11
11
  export type { AddLinksBulkRequest } from "./AddLinksBulkRequest";
12
12
  export type { AddSdnaRequest } from "./AddSdnaRequest";
13
+ export type { AgentMessage } from "./AgentMessage";
14
+ export type { AgentReply } from "./AgentReply";
13
15
  export type { AgentsByDidsRequest } from "./AgentsByDidsRequest";
14
16
  export type { ApplyTemplateRequest } from "./ApplyTemplateRequest";
15
17
  export type { CommitBatchRequest } from "./CommitBatchRequest";
@@ -41,6 +43,7 @@ export type { QueryRequest } from "./QueryRequest";
41
43
  export type { RemoveLinkRequest } from "./RemoveLinkRequest";
42
44
  export type { RemoveLinksBulkRequest } from "./RemoveLinksBulkRequest";
43
45
  export type { ResyncSubscriptionRequest } from "./ResyncSubscriptionRequest";
46
+ export type { RunAgentRequest } from "./RunAgentRequest";
44
47
  export type { RunInterpretationRequest } from "./RunInterpretationRequest";
45
48
  export type { SetDefaultModelRequest } from "./SetDefaultModelRequest";
46
49
  export type { SetFreeHostingEnabledRequest } from "./SetFreeHostingEnabledRequest";
package/src/index.ts 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.