@coasys/ad4m 0.13.1-staging.11 → 0.13.1-staging.13

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 (157) hide show
  1. package/lib/index.cjs +547 -72
  2. package/lib/index.js +547 -72
  3. package/lib/src/apiClient.d.ts +7 -2
  4. package/lib/src/apiClient.js +3 -2
  5. package/lib/src/generated/api/AISessionMessage.d.ts +4 -3
  6. package/lib/src/generated/api/AiEndpoint.d.ts +3 -2
  7. package/lib/src/generated/api/Cardinality.d.ts +7 -0
  8. package/lib/src/generated/api/Cardinality.js +2 -0
  9. package/lib/src/generated/api/CascadeStep.d.ts +12 -0
  10. package/lib/src/generated/api/CascadeStep.js +2 -0
  11. package/lib/src/generated/api/CollectionItemAdded.d.ts +14 -0
  12. package/lib/src/generated/api/CollectionItemAdded.js +2 -0
  13. package/lib/src/generated/api/CollectionItemRemoved.d.ts +12 -0
  14. package/lib/src/generated/api/CollectionItemRemoved.js +2 -0
  15. package/lib/src/generated/api/CollectionItems.d.ts +7 -0
  16. package/lib/src/generated/api/CollectionItems.js +2 -0
  17. package/lib/src/generated/api/ConfigChanged.d.ts +8 -0
  18. package/lib/src/generated/api/ConfigChanged.js +2 -0
  19. package/lib/src/generated/api/ConfigKeyInfo.d.ts +10 -0
  20. package/lib/src/generated/api/ConfigKeyInfo.js +1 -0
  21. package/lib/src/generated/api/ConfigRefusal.d.ts +6 -0
  22. package/lib/src/generated/api/ConfigRefusal.js +1 -0
  23. package/lib/src/generated/api/DeviceKeys.d.ts +9 -0
  24. package/lib/src/generated/api/DeviceKeys.js +2 -0
  25. package/lib/src/generated/api/Events.d.ts +2 -0
  26. package/lib/src/generated/api/InstanceAddToCollection.d.ts +16 -0
  27. package/lib/src/generated/api/InstanceAddToCollection.js +2 -0
  28. package/lib/src/generated/api/InstanceCreate.d.ts +31 -0
  29. package/lib/src/generated/api/InstanceCreate.js +2 -0
  30. package/lib/src/generated/api/InstanceCreated.d.ts +17 -0
  31. package/lib/src/generated/api/InstanceCreated.js +1 -0
  32. package/lib/src/generated/api/InstanceError.d.ts +55 -0
  33. package/lib/src/generated/api/InstanceError.js +1 -0
  34. package/lib/src/generated/api/InstanceRemove.d.ts +12 -0
  35. package/lib/src/generated/api/InstanceRemove.js +2 -0
  36. package/lib/src/generated/api/InstanceRemoveFromCollection.d.ts +16 -0
  37. package/lib/src/generated/api/InstanceRemoveFromCollection.js +2 -0
  38. package/lib/src/generated/api/InstanceRemoved.d.ts +10 -0
  39. package/lib/src/generated/api/InstanceRemoved.js +2 -0
  40. package/lib/src/generated/api/InstanceUpdate.d.ts +15 -0
  41. package/lib/src/generated/api/InstanceUpdate.js +2 -0
  42. package/lib/src/generated/api/InstanceUpdated.d.ts +5 -0
  43. package/lib/src/generated/api/InstanceUpdated.js +2 -0
  44. package/lib/src/generated/api/KeyClass.d.ts +4 -0
  45. package/lib/src/generated/api/KeyClass.js +2 -0
  46. package/lib/src/generated/api/LogTail.d.ts +6 -0
  47. package/lib/src/generated/api/LogTail.js +2 -0
  48. package/lib/src/generated/api/LogTailParams.d.ts +9 -0
  49. package/lib/src/generated/api/LogTailParams.js +2 -0
  50. package/lib/src/generated/api/PerspectiveInstanceAddToCollectionParams.d.ts +14 -0
  51. package/lib/src/generated/api/PerspectiveInstanceAddToCollectionParams.js +2 -0
  52. package/lib/src/generated/api/PerspectiveInstanceCreateParams.d.ts +29 -0
  53. package/lib/src/generated/api/PerspectiveInstanceCreateParams.js +2 -0
  54. package/lib/src/generated/api/PerspectiveInstanceRemoveFromCollectionParams.d.ts +14 -0
  55. package/lib/src/generated/api/PerspectiveInstanceRemoveFromCollectionParams.js +2 -0
  56. package/lib/src/generated/api/PerspectiveInstanceRemoveParams.d.ts +9 -0
  57. package/lib/src/generated/api/PerspectiveInstanceRemoveParams.js +2 -0
  58. package/lib/src/generated/api/PerspectiveInstanceUpdateParams.d.ts +13 -0
  59. package/lib/src/generated/api/PerspectiveInstanceUpdateParams.js +2 -0
  60. package/lib/src/generated/api/Pinned.d.ts +5 -0
  61. package/lib/src/generated/api/Pinned.js +2 -0
  62. package/lib/src/generated/api/ReadOnlyReason.d.ts +4 -0
  63. package/lib/src/generated/api/ReadOnlyReason.js +2 -0
  64. package/lib/src/generated/api/RefusalReason.d.ts +4 -0
  65. package/lib/src/generated/api/RefusalReason.js +2 -0
  66. package/lib/src/generated/api/RpcMethods.d.ts +60 -0
  67. package/lib/src/generated/api/RpcMethods.js +3 -0
  68. package/lib/src/generated/api/RuntimeConfig.d.ts +23 -0
  69. package/lib/src/generated/api/RuntimeConfig.js +1 -0
  70. package/lib/src/generated/api/SetConfigParams.d.ts +7 -0
  71. package/lib/src/generated/api/SetConfigParams.js +2 -0
  72. package/lib/src/generated/api/SetConfigResult.d.ts +8 -0
  73. package/lib/src/generated/api/SetConfigResult.js +1 -0
  74. package/lib/src/generated/api/ValidationError.d.ts +34 -0
  75. package/lib/src/generated/api/ValidationError.js +1 -0
  76. package/lib/src/generated/api/ValidationProblem.d.ts +34 -0
  77. package/lib/src/generated/api/ValidationProblem.js +1 -0
  78. package/lib/src/generated/api/WriteStep.d.ts +37 -0
  79. package/lib/src/generated/api/WriteStep.js +2 -0
  80. package/lib/src/generated/api/index.d.ts +30 -0
  81. package/lib/src/identity/IdentityClient.d.ts +14 -0
  82. package/lib/src/identity/IdentityClient.js +17 -0
  83. package/lib/src/model/shacl-gen.js +4 -2
  84. package/lib/src/neighbourhood/MeshManager.d.ts +17 -1
  85. package/lib/src/neighbourhood/MeshManager.js +17 -0
  86. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +7 -2
  87. package/lib/src/neighbourhood/NeighbourhoodProxy.js +7 -2
  88. package/lib/src/neighbourhood/Session.d.ts +5 -3
  89. package/lib/src/neighbourhood/Session.js +171 -26
  90. package/lib/src/perspectives/PerspectiveClient.d.ts +34 -0
  91. package/lib/src/perspectives/PerspectiveClient.js +45 -0
  92. package/lib/src/perspectives/PerspectiveProxy.d.ts +33 -0
  93. package/lib/src/perspectives/PerspectiveProxy.js +67 -2
  94. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +23 -1
  95. package/lib/src/perspectives/WakerSubscriptionManager.js +187 -36
  96. package/lib/src/runtime/RuntimeClient.d.ts +13 -1
  97. package/lib/src/runtime/RuntimeClient.js +20 -0
  98. package/lib/src/shacl/SHACLShape.js +6 -2
  99. package/package.json +2 -2
  100. package/src/Ad4mClient.test.ts +118 -2
  101. package/src/apiClient.ts +10 -4
  102. package/src/generated/api/AISessionMessage.ts +4 -3
  103. package/src/generated/api/AiEndpoint.ts +3 -2
  104. package/src/generated/api/Cardinality.ts +6 -0
  105. package/src/generated/api/CascadeStep.ts +6 -0
  106. package/src/generated/api/CollectionItemAdded.ts +11 -0
  107. package/src/generated/api/CollectionItemRemoved.ts +9 -0
  108. package/src/generated/api/CollectionItems.ts +6 -0
  109. package/src/generated/api/ConfigChanged.ts +7 -0
  110. package/src/generated/api/ConfigKeyInfo.ts +8 -0
  111. package/src/generated/api/ConfigRefusal.ts +4 -0
  112. package/src/generated/api/DeviceKeys.ts +8 -0
  113. package/src/generated/api/Events.ts +2 -0
  114. package/src/generated/api/InstanceAddToCollection.ts +14 -0
  115. package/src/generated/api/InstanceCreate.ts +32 -0
  116. package/src/generated/api/InstanceCreated.ts +16 -0
  117. package/src/generated/api/InstanceError.ts +10 -0
  118. package/src/generated/api/InstanceRemove.ts +11 -0
  119. package/src/generated/api/InstanceRemoveFromCollection.ts +14 -0
  120. package/src/generated/api/InstanceRemoved.ts +9 -0
  121. package/src/generated/api/InstanceUpdate.ts +14 -0
  122. package/src/generated/api/InstanceUpdated.ts +3 -0
  123. package/src/generated/api/KeyClass.ts +6 -0
  124. package/src/generated/api/LogTail.ts +6 -0
  125. package/src/generated/api/LogTailParams.ts +10 -0
  126. package/src/generated/api/PerspectiveInstanceAddToCollectionParams.ts +11 -0
  127. package/src/generated/api/PerspectiveInstanceCreateParams.ts +29 -0
  128. package/src/generated/api/PerspectiveInstanceRemoveFromCollectionParams.ts +11 -0
  129. package/src/generated/api/PerspectiveInstanceRemoveParams.ts +7 -0
  130. package/src/generated/api/PerspectiveInstanceUpdateParams.ts +11 -0
  131. package/src/generated/api/Pinned.ts +7 -0
  132. package/src/generated/api/ReadOnlyReason.ts +6 -0
  133. package/src/generated/api/RefusalReason.ts +6 -0
  134. package/src/generated/api/RpcMethods.ts +30 -0
  135. package/src/generated/api/RuntimeConfig.ts +24 -0
  136. package/src/generated/api/SetConfigParams.ts +6 -0
  137. package/src/generated/api/SetConfigResult.ts +7 -0
  138. package/src/generated/api/ValidationError.ts +34 -0
  139. package/src/generated/api/ValidationProblem.ts +7 -0
  140. package/src/generated/api/WriteStep.ts +6 -0
  141. package/src/generated/api/index.ts +34 -0
  142. package/src/identity/IdentityClient.ts +20 -0
  143. package/src/model/shacl-gen.ts +4 -2
  144. package/src/neighbourhood/MeshManager.test.ts +57 -0
  145. package/src/neighbourhood/MeshManager.ts +26 -0
  146. package/src/neighbourhood/NeighbourhoodProxy.ts +7 -2
  147. package/src/neighbourhood/Session.test.ts +355 -3
  148. package/src/neighbourhood/Session.ts +170 -28
  149. package/src/perspectives/PerspectiveClient.ts +56 -0
  150. package/src/perspectives/PerspectiveProxy.test.ts +34 -0
  151. package/src/perspectives/PerspectiveProxy.ts +76 -2
  152. package/src/perspectives/WakerSubscriptionManager.test.ts +379 -1
  153. package/src/perspectives/WakerSubscriptionManager.ts +189 -41
  154. package/src/runtime/RuntimeClient.ts +25 -1
  155. package/src/shacl/SHACLFlow.test.ts +4 -2
  156. package/src/shacl/SHACLShape.test.ts +10 -3
  157. package/src/shacl/SHACLShape.ts +6 -2
@@ -260,6 +260,14 @@ export class WakerSubscriptionManager {
260
260
  * keeps persisting them so a restart restores them (#1595).
261
261
  */
262
262
  this.reopening = new Map();
263
+ /**
264
+ * Mention subscriptions listening through their mention query only, because
265
+ * their text query failed to open (#1735: a TextContent `contains` scan over a
266
+ * large neighbourhood can take longer than the handshake budget). The text
267
+ * query alone is re-attempted: `timer` is the wait before the next attempt,
268
+ * `proxy` the attempt in flight. `release()` cancels both.
269
+ */
270
+ this.textRetries = new Map();
263
271
  /**
264
272
  * Cancellation tokens for in-flight `subscribe()` calls.
265
273
  *
@@ -318,6 +326,15 @@ export class WakerSubscriptionManager {
318
326
  * If a subscription with the same id already exists, it is disposed first.
319
327
  */
320
328
  async subscribe(sub) {
329
+ // The manager's own copy: it records `textHistoryRead` on it. A re-derived
330
+ // subscription under the same id keeps what the manager knows of its text
331
+ // query.
332
+ const prior = this.activeSubscriptions.get(sub.id) ??
333
+ this.pendingSubscriptions.get(sub.id) ??
334
+ this.reopening.get(sub.id)?.sub;
335
+ sub = { ...sub };
336
+ if (prior?.textHistoryRead && sub.textHistoryRead === undefined)
337
+ sub.textHistoryRead = true;
321
338
  // Dispose existing subscription with same id if any. Not `dispose()`: a
322
339
  // re-attempt must not start the backoff over.
323
340
  this.release(sub.id, false);
@@ -339,12 +356,15 @@ export class WakerSubscriptionManager {
339
356
  if (sub.mentionQuery) {
340
357
  this.logger.info(`[waker] ${sub.id}: model query over ${sub.mentionClass}:\n${sub.mentionQuery}`);
341
358
  }
342
- const proxy = sub.className
359
+ const textProxy = () => sub.className
343
360
  ? new QuerySubscriptionProxy(sub.perspective, sub.query, this.perspectiveClient, sub.className)
344
361
  : new QuerySubscriptionProxy(sub.perspective, sub.query, this.perspectiveClient);
362
+ const proxy = textProxy();
345
363
  const mentionProxy = sub.mentionQuery
346
364
  ? new QuerySubscriptionProxy(sub.perspective, sub.mentionQuery, this.perspectiveClient, sub.mentionClass)
347
365
  : undefined;
366
+ // The live proxies. A text query that failed while the mention query opened
367
+ // leaves it, and joins it again once a re-attempt opens (#1735).
348
368
  const proxies = mentionProxy ? [proxy, mentionProxy] : [proxy];
349
369
  // `cancelOpening`: a handshake given up on must not keep the executor
350
370
  // computing a first result nobody reads; abandoned ones piled up into
@@ -357,28 +377,49 @@ export class WakerSubscriptionManager {
357
377
  catch { }
358
378
  }
359
379
  };
360
- // Suppress unhandled rejection from proxy.initialized — QuerySubscriptionProxy
361
- // rejects this promise internally when subscribe() fails, and if nobody catches
362
- // it before the next microtask it crashes the process.
363
- for (const p of proxies) {
364
- if (p.initialized && typeof p.initialized.catch === "function")
365
- p.initialized.catch(() => { });
366
- }
367
- // One deadline for the whole handshake: `proxy.subscribe()` and the
380
+ // One deadline per query's handshake: `proxy.subscribe()` and the
368
381
  // `initialized` promise it resolves share the budget, so a hang in either
369
382
  // surfaces as the same loud-but-recoverable failure a rejection does.
370
- const budgetMs = this.subscribeTimeoutMs;
371
- const startedAt = Date.now();
372
- const bounded = (step, what) => budgetMs > 0
373
- ? withTimeout(step, Math.max(0, budgetMs - (Date.now() - startedAt)), `${what} timed out after ${budgetMs}ms`)
374
- : step;
375
- try {
376
- await bounded(Promise.all(proxies.map((p) => p.subscribe())), "subscribe handshake");
377
- if (this.isStale(sub.id, token)) {
378
- disposeProxies();
383
+ const open = async (p, budgetMs) => {
384
+ // Suppress unhandled rejection from proxy.initialized — QuerySubscriptionProxy
385
+ // rejects this promise internally when subscribe() fails, and if nobody catches
386
+ // it before the next microtask it crashes the process.
387
+ if (p.initialized && typeof p.initialized.catch === "function")
388
+ p.initialized.catch(() => { });
389
+ const startedAt = Date.now();
390
+ const bounded = (step, what) => budgetMs > 0
391
+ ? withTimeout(step, Math.max(0, budgetMs - (Date.now() - startedAt)), `${what} timed out after ${budgetMs}ms`)
392
+ : step;
393
+ await bounded(p.subscribe(), "subscribe handshake");
394
+ // Stale: the caller disposes the proxies.
395
+ if (this.isStale(sub.id, token))
379
396
  return;
397
+ await bounded(p.initialized, "subscription initialization");
398
+ };
399
+ // A mention subscription's two queries open independently: on a large
400
+ // neighbourhood the text query (a `contains` scan over every TextContent)
401
+ // can take longer than the budget while the mention query answers in under
402
+ // a second (#1735). Waiting on both made the whole subscription fail, and
403
+ // the agent got no wake at all, not even through a mention link. The
404
+ // mention query decides; a text query that fails is re-attempted on its own
405
+ // once the subscription listens.
406
+ const openings = proxies.map((p) => open(p, this.subscribeTimeoutMs));
407
+ for (const o of openings)
408
+ o.catch(() => { });
409
+ let textFailure;
410
+ try {
411
+ await openings[openings.length - 1];
412
+ if (mentionProxy) {
413
+ const [text] = await Promise.allSettled([openings[0]]);
414
+ if (text.status === "rejected") {
415
+ textFailure = text.reason?.message ?? String(text.reason);
416
+ try {
417
+ proxy.dispose({ cancelOpening: true });
418
+ }
419
+ catch { }
420
+ proxies.splice(proxies.indexOf(proxy), 1);
421
+ }
380
422
  }
381
- await bounded(Promise.all(proxies.map((p) => p.initialized)), "subscription initialization");
382
423
  }
383
424
  catch (err) {
384
425
  const msg = err?.message ?? String(err);
@@ -423,10 +464,14 @@ export class WakerSubscriptionManager {
423
464
  if (seen.size > 0) {
424
465
  this.logger.info(`[waker] ${sub.id}: seeded ${seen.size} seen message(s) from persisted state`);
425
466
  }
426
- // `opening` is the result the subscription holds when it opens (`proxy.result`): `onResult`
427
- // only reports later changes, so this is the one chance to see what was written meanwhile.
428
467
  // `of`: the query the result is from, for the log (a mention subscription has two).
429
- const handleResult = async (result, opening = false, of = "") => {
468
+ // `opening` marks the result the query holds when it opens (`proxy.result`): `onResult`
469
+ // only reports later changes, so this is the one chance to see what was written meanwhile.
470
+ // A mention subscription reads it as `"history"` (recorded as seen, no wake) or `"news"`
471
+ // (wakes on what is not seen yet: written while the waker was down).
472
+ const handleResult = async (result, of, opening) => {
473
+ if (this.isStale(sub.id, token))
474
+ return;
430
475
  this.logger.info(`[waker] ${sub.id}: ${opening ? "opening result" : "onResult fired"}${of} — type=${typeof result}, isArray=${Array.isArray(result)}, value=${String(JSON.stringify(result)).substring(0, 500)}`);
431
476
  // A model subscription delivers `{ instances }`, SPARQL an array of
432
477
  // rows. Anything else (e.g. `false` on a disconnect/reconnect) is
@@ -461,8 +506,8 @@ export class WakerSubscriptionManager {
461
506
  this.logger.info(`[waker] ${sub.id}: no new mention among ${rows.length} items, skipping`);
462
507
  return;
463
508
  }
464
- if (opening && !restored) {
465
- // A new subscription: what it opens on is history, readable on demand, not news.
509
+ if (opening === "history") {
510
+ // What it opens on is history, readable on demand, not news.
466
511
  this.seenMessages.set(sub.id, currentSeen);
467
512
  const done = this.delivered.get(sub.id) ?? new Set();
468
513
  for (const address of newMessages)
@@ -482,6 +527,10 @@ export class WakerSubscriptionManager {
482
527
  (ancestors.length ? `; ancestors: ${ancestors.join(", ")}` : ""));
483
528
  mentions.push({ address: msgAddr, parents, ancestors, ...provenance.get(msgAddr) });
484
529
  }
530
+ // Released, or replaced under the same id, during the lookups: the state under `sub.id`
531
+ // is no longer this subscription's, so write nothing and wake for nothing.
532
+ if (this.isStale(sub.id, token))
533
+ return;
485
534
  this.seenMessages.set(sub.id, currentSeen);
486
535
  const pending = this.undelivered.get(sub.id) ?? new Map();
487
536
  for (const mention of mentions)
@@ -505,29 +554,119 @@ export class WakerSubscriptionManager {
505
554
  }, this.debounceMs));
506
555
  }
507
556
  };
508
- proxy.onResult((result) => handleResult(result));
509
- mentionProxy?.onResult((result) => handleResult(result, false, " (mention query)"));
510
- for (const p of proxies) {
557
+ // Read `p`'s opening result. The mention query's is news only after a restart. The text
558
+ // query's is news only after a restart and once a text query of this subscription has read
559
+ // its history (`textHistoryRead`): it may have listened without it, so the seen set may not
560
+ // hold what the text query finds (#1735).
561
+ const readOpening = async (p, of) => {
562
+ if (p.result === undefined)
563
+ return;
564
+ const isText = p !== mentionProxy;
565
+ const news = restored && (!isText || sub.type !== "mention" || sub.textHistoryRead === true);
566
+ try {
567
+ await handleResult(p.result, of, news ? "news" : "history");
568
+ }
569
+ catch (e) {
570
+ this.logger.warn(`[waker] ${sub.id}: reading the opening result failed: ${e?.message ?? e}`);
571
+ }
572
+ const rows = sub.className ? p.result?.instances : p.result;
573
+ if (isText && sub.type === "mention" && Array.isArray(rows) && !this.isStale(sub.id, token)) {
574
+ sub.textHistoryRead = true;
575
+ }
576
+ };
577
+ const listen = (p, of) => {
578
+ p.onResult((result) => handleResult(result, of));
511
579
  p.onStatus?.((status) => this.onReopenStatus(sub, proxies, p, status));
512
- }
580
+ };
581
+ if (proxies.includes(proxy))
582
+ listen(proxy, "");
583
+ if (mentionProxy)
584
+ listen(mentionProxy, " (mention query)");
513
585
  if (this.isStale(sub.id, token)) {
514
586
  disposeProxies();
515
587
  return;
516
588
  }
517
589
  this.proxies.set(sub.id, proxies);
518
590
  this.activeSubscriptions.set(sub.id, sub);
591
+ if (textFailure !== undefined) {
592
+ // Re-attempt the text query alone, not the subscription: subscribing it
593
+ // again would re-seed its seen set from the persisted one, and wake again
594
+ // on mentions delivered since. Each failed attempt doubles the wait, up to
595
+ // `maxRetryPendingMs`, between half and all of it, as `scheduleRetry` does.
596
+ // The handshake budget doubles per failed attempt too: a scan that takes
597
+ // longer than `subscribeTimeoutMs` (#1735 measured over 30 s) would
598
+ // otherwise time out on every attempt. It is capped at `maxRetryPendingMs`
599
+ // (or the first budget, if longer): with one attempt in flight at a time,
600
+ // the executor then spends at most about as long on an attempt as the
601
+ // waker waits between two.
602
+ let ceiling = this.retryPendingMs;
603
+ let budgetMs = this.subscribeTimeoutMs;
604
+ const retryText = () => {
605
+ const delayMs = ceiling / 2 + Math.random() * (ceiling / 2);
606
+ ceiling = Math.min(ceiling * 2, this.maxRetryPendingMs);
607
+ const attemptBudgetMs = budgetMs;
608
+ budgetMs = Math.min(budgetMs * 2, Math.max(this.subscribeTimeoutMs, this.maxRetryPendingMs));
609
+ const timer = setTimeout(async () => {
610
+ if (this.textRetries.get(sub.id)?.timer !== timer || this.isStale(sub.id, token))
611
+ return;
612
+ const p = textProxy();
613
+ this.textRetries.set(sub.id, { timer: null, proxy: p });
614
+ // `release()` disposed it already when the entry no longer holds it.
615
+ const ours = () => this.textRetries.get(sub.id)?.proxy === p;
616
+ try {
617
+ await open(p, attemptBudgetMs);
618
+ }
619
+ catch (err) {
620
+ if (!ours())
621
+ return;
622
+ try {
623
+ p.dispose({ cancelOpening: true });
624
+ }
625
+ catch { }
626
+ if (this.isStale(sub.id, token)) {
627
+ this.textRetries.delete(sub.id);
628
+ return;
629
+ }
630
+ const nextMs = retryText();
631
+ this.logger.debug(`[waker] ${sub.id}: text query failed again (${err?.message ?? err}); re-attempting in ${Math.round(nextMs / 1000)}s`);
632
+ return;
633
+ }
634
+ if (!ours())
635
+ return;
636
+ this.textRetries.delete(sub.id);
637
+ if (this.isStale(sub.id, token) || this.proxies.get(sub.id) !== proxies) {
638
+ try {
639
+ p.dispose({ cancelOpening: true });
640
+ }
641
+ catch { }
642
+ return;
643
+ }
644
+ proxies.push(p);
645
+ listen(p, "");
646
+ this.logger.info(`[waker] ${sub.id}: text query opened; listening through both queries`);
647
+ // The seen set is the mention query's, so a record it already woke on does not wake
648
+ // again.
649
+ await readOpening(p, "");
650
+ if (!this.isStale(sub.id, token))
651
+ this.persist();
652
+ }, delayMs);
653
+ if (typeof timer.unref === "function")
654
+ timer.unref();
655
+ this.textRetries.set(sub.id, { timer, proxy: null });
656
+ return delayMs;
657
+ };
658
+ const firstMs = this.retryPendingMs > 0 ? retryText() : undefined;
659
+ this.logger.warn(`[waker] ${sub.id}: text query failed (${textFailure}); listening through the mention query only, ` +
660
+ (firstMs === undefined
661
+ ? "not re-attempting the text query (retryPendingMs is 0)"
662
+ : `re-attempting the text query in ${Math.round(firstMs / 1000)}s`));
663
+ }
519
664
  // After a restart this wakes on mentions written while the waker was down; on a new
520
665
  // subscription it records the existing ones as history. The mention query's first, so a
521
666
  // record both hold wakes through its mention link.
522
667
  for (const [p, of] of [[mentionProxy, " (mention query)"], [proxy, ""]]) {
523
- if (p?.result === undefined)
524
- continue;
525
- try {
526
- await handleResult(p.result, true, of);
527
- }
528
- catch (e) {
529
- this.logger.warn(`[waker] ${sub.id}: reading the opening result failed: ${e?.message ?? e}`);
530
- }
668
+ if (p && proxies.includes(p))
669
+ await readOpening(p, of);
531
670
  }
532
671
  this.persist();
533
672
  this.logger.info(`[waker] Subscription ${sub.id} active (type=${sub.type}, perspective=${sub.perspective})`);
@@ -653,6 +792,18 @@ export class WakerSubscriptionManager {
653
792
  }
654
793
  }
655
794
  this.proxies.delete(id);
795
+ const textRetry = this.textRetries.get(id);
796
+ if (textRetry) {
797
+ if (textRetry.timer)
798
+ clearTimeout(textRetry.timer);
799
+ try {
800
+ textRetry.proxy?.dispose({ cancelOpening: true });
801
+ }
802
+ catch {
803
+ /* ignore */
804
+ }
805
+ this.textRetries.delete(id);
806
+ }
656
807
  this.reopening.delete(id);
657
808
  const timer = this.debounceTimers.get(id);
658
809
  if (timer) {
@@ -1,14 +1,26 @@
1
1
  import { ApiClient, CallOptions } from '../apiClient';
2
2
  import { Perspective, PerspectiveExpression } from "../perspectives/Perspective";
3
3
  import { RuntimeInfo, SentMessage, NotificationInput, NotificationUpdate, Notification, ImportResult, UserStatistics } from "./RuntimeTypes";
4
- import type { HostRate, UnytVersionInfo } from "../generated/api";
4
+ import type { HostRate, LogTail, RuntimeConfig, SetConfigResult, UnytVersionInfo } from "../generated/api";
5
5
  import { LanguageMeta } from "../language/LanguageMeta";
6
6
  export declare class RuntimeClient {
7
7
  #private;
8
8
  constructor(baseUrl: string, token?: string, sharedApiClient?: ApiClient);
9
9
  info(): Promise<RuntimeInfo>;
10
10
  tlsDomain(): Promise<string | null>;
11
+ /** Stops the executor (exit 0). Only the operator on the executor's machine. */
11
12
  quit(): Promise<Boolean>;
13
+ /** Answers, then the executor exits 75 and its supervisor starts it again. */
14
+ restart(): Promise<boolean>;
15
+ /** The newest lines (at most 2000) of the executor's log file (`--log-dir`). */
16
+ logTail(lines: number): Promise<LogTail>;
17
+ /** The executor's config file: its values, every key with its class, and whether a write waits for a restart. */
18
+ config(): Promise<RuntimeConfig>;
19
+ /**
20
+ * Writes keys to the executor's config file (`--config`); they take effect at the next
21
+ * start. A `machine` key from a caller off the executor's machine is refused `local-only`.
22
+ */
23
+ setConfig(set?: Record<string, unknown>, unset?: string[]): Promise<SetConfigResult>;
12
24
  openLink(url: string): Promise<Boolean>;
13
25
  addTrustedAgents(agents: string[]): Promise<string[]>;
14
26
  deleteTrustedAgents(agents: string[]): Promise<string[]>;
@@ -23,9 +23,29 @@ export class RuntimeClient {
23
23
  async tlsDomain() {
24
24
  return __classPrivateFieldGet(this, _RuntimeClient_apiClient, "f").call('runtime.tlsDomain', {});
25
25
  }
26
+ /** Stops the executor (exit 0). Only the operator on the executor's machine. */
26
27
  async quit() {
27
28
  return __classPrivateFieldGet(this, _RuntimeClient_apiClient, "f").call('runtime.quit', {});
28
29
  }
30
+ /** Answers, then the executor exits 75 and its supervisor starts it again. */
31
+ async restart() {
32
+ return __classPrivateFieldGet(this, _RuntimeClient_apiClient, "f").call('runtime.restart', {});
33
+ }
34
+ /** The newest lines (at most 2000) of the executor's log file (`--log-dir`). */
35
+ async logTail(lines) {
36
+ return __classPrivateFieldGet(this, _RuntimeClient_apiClient, "f").call('runtime.logTail', { lines });
37
+ }
38
+ /** The executor's config file: its values, every key with its class, and whether a write waits for a restart. */
39
+ async config() {
40
+ return __classPrivateFieldGet(this, _RuntimeClient_apiClient, "f").call('runtime.config', {});
41
+ }
42
+ /**
43
+ * Writes keys to the executor's config file (`--config`); they take effect at the next
44
+ * start. A `machine` key from a caller off the executor's machine is refused `local-only`.
45
+ */
46
+ async setConfig(set, unset) {
47
+ return __classPrivateFieldGet(this, _RuntimeClient_apiClient, "f").call('runtime.setConfig', { set, unset });
48
+ }
29
49
  async openLink(url) {
30
50
  return __classPrivateFieldGet(this, _RuntimeClient_apiClient, "f").call('runtime.openLink', { url });
31
51
  }
@@ -199,7 +199,10 @@ export class SHACLShape {
199
199
  const statements = (source) => links
200
200
  .filter(l => l.source === source && l.predicate !== 'sh://property')
201
201
  .flatMap(l => l.predicate === 'sh://in'
202
- ? [`sh:in ( ${JSON.parse(l.target.slice(15)).map((v) => str(v.value)).join(' ')} )`, `ad4m:in ${obj(l)}`]
202
+ ? [`sh:in ( ${JSON.parse(l.target.slice(15)).map((v) => {
203
+ const value = v !== null && typeof v === 'object' && 'value' in v ? v.value : v;
204
+ return typeof value === 'string' ? str(value) : JSON.stringify(value);
205
+ }).join(' ')} )`, `ad4m:in ${obj(l)}`]
203
206
  : [`${pred(l.predicate)} ${obj(l)}`]);
204
207
  const properties = links
205
208
  .filter(l => l.source === this.nodeShapeUri && l.predicate === 'sh://property')
@@ -438,7 +441,8 @@ export class SHACLShape {
438
441
  target: prop.class
439
442
  });
440
443
  }
441
- if (prop.in && prop.in.length > 0) {
444
+ // `in: []` is a deny-all constraint, not the absence of one — store it.
445
+ if (prop.in !== undefined) {
442
446
  links.push({
443
447
  source: propShapeId,
444
448
  predicate: "sh://in",
package/package.json CHANGED
@@ -53,8 +53,8 @@
53
53
  "ws": "8.13.0"
54
54
  },
55
55
  "patchedDependencies": {},
56
- "version": "0.13.1-staging.11",
57
- "gitHead": "9c06d1bfe1e88a99fae93ad27cb27779eb3e3a65",
56
+ "version": "0.13.1-staging.13",
57
+ "gitHead": "3f800fc56a6b19a44a53b60b38b1ba2a7b809cf8",
58
58
  "scripts": {
59
59
  "build": "patch-package && tsc && pnpm run bundle",
60
60
  "bundle": "rollup -c rollup.config.js",
@@ -1,5 +1,5 @@
1
1
  import { Ad4mClient } from './Ad4mClient';
2
- import { ApiClient } from './apiClient';
2
+ import { ApiClient, RpcError } from './apiClient';
3
3
  import { Perspective } from './perspectives/Perspective';
4
4
  import { LinkQuery } from './perspectives/LinkQuery';
5
5
  import type { EventMap, EventName } from './generated/api/Events';
@@ -34,6 +34,9 @@ const originalWebSocket = (global as any).WebSocket;
34
34
 
35
35
  type RpcHandler = unknown | ((params: Record<string, unknown>) => unknown);
36
36
 
37
+ /** A handler result under this key is sent as the reply's `error` member instead of `result`. */
38
+ const RPC_ERROR = '__rpcError';
39
+
37
40
  const MOCK_RESPONSES: Record<string, RpcHandler> = {
38
41
  // ── Agent ──
39
42
  'agent.get': { did: 'did:test:123', perspective: new Perspective(), directMessageLanguage: 'lang://dm', identity: 'did:scid:coasys:1:QmTest' },
@@ -43,6 +46,8 @@ const MOCK_RESPONSES: Record<string, RpcHandler> = {
43
46
  'identity.claimOffer': (p: Record<string, unknown>) => ({ did: 'did:scid:coasys:1:QmTest', offerId: 'offer', matchCode: 'R7K Q2M', kind: 'node', expires: 1, echo: p }),
44
47
  'identity.log': (p: Record<string, unknown>) => ({ did: p.did, events: [], head: null, fork: null }),
45
48
  'identity.devices': [],
49
+ 'identity.rekey': { sign: 'did:key:z6MkNew', enc: 'z6LSNew' },
50
+ 'identity.custodyStatus': { sign: 'did:key:z6MkTest', enc: 'z6LSTest' },
46
51
  'identity.resolve': (p: Record<string, unknown>) => ({
47
52
  didDocument: { '@context': ['https://www.w3.org/ns/did/v1'], id: p.didUrl, controller: p.didUrl, verificationMethod: [], authentication: [], assertionMethod: [], keyAgreement: [], capabilityInvocation: [] },
48
53
  didDocumentMetadata: { versionId: '2', deactivated: false },
@@ -116,6 +121,27 @@ const MOCK_RESPONSES: Record<string, RpcHandler> = {
116
121
  'perspective.addSdna': true,
117
122
  'perspective.executeCommands': true,
118
123
  'perspective.createSubject': true,
124
+ // A `colour` property is refused as the executor refuses an unknown property: 422 with the
125
+ // InstanceError as data.
126
+ 'perspective.instanceCreate': (p: Record<string, unknown>) =>
127
+ (p.properties as Record<string, unknown> | undefined)?.colour !== undefined
128
+ ? { [RPC_ERROR]: {
129
+ code: 422,
130
+ message: "Validation failed for class 'Task': colour (unknownProperty)",
131
+ data: { kind: 'validation', className: 'Task', errors: [{
132
+ property: 'colour', problem: { kind: 'unknownProperty', class: 'Task', available: ['title'] },
133
+ expectedType: null, cardinality: null, allowedValues: null, received: 'red', item: null,
134
+ }] },
135
+ } }
136
+ : { className: p.className, baseUri: 'ad4m://obj/new', propertiesSet: Object.keys(p.properties as object), collectionsSet: [], parent: null },
137
+ 'perspective.instanceUpdate': (p: Record<string, unknown>) =>
138
+ ({ className: p.className, baseUri: p.baseUri, updatedProperties: Object.keys(p.properties as object) }),
139
+ 'perspective.instanceRemove': (p: Record<string, unknown>) =>
140
+ ({ className: p.className, baseUri: p.baseUri, linksRemoved: 3 }),
141
+ 'perspective.instanceAddToCollection': (p: Record<string, unknown>) =>
142
+ ({ className: p.className, baseUri: p.baseUri, collection: p.collection, itemUri: p.itemUri, linksAdded: 1, alreadyMember: false }),
143
+ 'perspective.instanceRemoveFromCollection': (p: Record<string, unknown>) =>
144
+ ({ className: p.className, baseUri: p.baseUri, collection: p.collection, itemUri: p.itemUri, linksRemoved: 1 }),
119
145
  'perspective.getSubjectData': '{"name":"test"}',
120
146
  'perspective.createBatch': 'batch-id-1',
121
147
  'perspective.commitBatch': { additions: [], removals: [] },
@@ -211,6 +237,10 @@ const MOCK_RESPONSES: Record<string, RpcHandler> = {
211
237
  'runtime.addHcAgentInfos': true,
212
238
  'runtime.networkMetrics': 'metrics-data',
213
239
  'runtime.restartHolochain': true,
240
+ 'runtime.restart': true,
241
+ 'runtime.logTail': (p: Record<string, unknown>) => ({ lines: [`asked ${p.lines}`] }),
242
+ 'runtime.config': { values: { mcp_port: 3001 }, keys: [{ key: 'mcp_port', class: 'restart' }, { key: 'port', class: 'machine', pinned: 'config' }], restartPending: false, file: '/data/adam/config.json' },
243
+ 'runtime.setConfig': (p: Record<string, unknown>) => ({ restartPending: true, refused: p.unset ? [{ key: 'port', reason: 'local-only' }] : [] }),
214
244
  'runtime.verifySignature': true,
215
245
  'runtime.exportData': true,
216
246
  'runtime.importData': { success: true, count: 5 },
@@ -336,7 +366,8 @@ class MockWebSocket {
336
366
  : handler;
337
367
 
338
368
  const reply = (value: unknown) => setTimeout(() => {
339
- this.onmessage?.({ data: JSON.stringify({ id, result: value }) });
369
+ const error = (value as Record<string, unknown> | null)?.[RPC_ERROR];
370
+ this.onmessage?.({ data: JSON.stringify(error ? { id, error } : { id, result: value }) });
340
371
  }, 0);
341
372
  if (result instanceof Promise) result.then(reply);
342
373
  else reply(result);
@@ -643,6 +674,52 @@ describe('PerspectiveClient', () => {
643
674
  expect(lastRpcCall!.params.batchId).toBe('batch-id-1');
644
675
  });
645
676
 
677
+ test('instanceCreate() sends the body next to uuid and returns the created instance', async () => {
678
+ const created = await ad4m.perspective.instanceCreate('uuid-1', {
679
+ className: 'Task', properties: { title: 'Write' }, batchId: 'batch-1',
680
+ });
681
+ expect(lastRpcCall!.type).toBe('perspective.instanceCreate');
682
+ expect(lastRpcCall!.params).toEqual({
683
+ uuid: 'uuid-1', className: 'Task', properties: { title: 'Write' }, batchId: 'batch-1',
684
+ });
685
+ expect(created.baseUri).toBe('ad4m://obj/new');
686
+ expect(created.propertiesSet).toEqual(['title']);
687
+ });
688
+
689
+ test('a refused instance write rejects with the validation errors as RpcError.data', async () => {
690
+ const error = await ad4m.perspective
691
+ .instanceCreate('uuid-1', { className: 'Task', properties: { title: 't', colour: 'red' } })
692
+ .then(() => null, (e: unknown) => e);
693
+ expect(error).toBeInstanceOf(RpcError);
694
+ const rpcError = error as RpcError;
695
+ expect(rpcError.status).toBe(422);
696
+ const data = rpcError.data as { kind: string; errors: { property: string; problem: { kind: string } }[] };
697
+ expect(data.kind).toBe('validation');
698
+ expect(data.errors[0].property).toBe('colour');
699
+ expect(data.errors[0].problem.kind).toBe('unknownProperty');
700
+ });
701
+
702
+ test('the other instance writes call their methods with the body', async () => {
703
+ const base = { className: 'Task', baseUri: 'ad4m://obj/t' };
704
+ const item = { ...base, collection: 'labels', itemUri: 'ad4m://label/x' };
705
+
706
+ const updated = await ad4m.perspective.instanceUpdate('uuid-1', { ...base, properties: { status: 'doing' } });
707
+ expect(lastRpcCall).toEqual({ type: 'perspective.instanceUpdate', params: { uuid: 'uuid-1', ...base, properties: { status: 'doing' } } });
708
+ expect(updated.updatedProperties).toEqual(['status']);
709
+
710
+ const removed = await ad4m.perspective.instanceRemove('uuid-1', { ...base, batchId: 'b' });
711
+ expect(lastRpcCall).toEqual({ type: 'perspective.instanceRemove', params: { uuid: 'uuid-1', ...base, batchId: 'b' } });
712
+ expect(removed.linksRemoved).toBe(3);
713
+
714
+ const added = await ad4m.perspective.instanceAddToCollection('uuid-1', item);
715
+ expect(lastRpcCall).toEqual({ type: 'perspective.instanceAddToCollection', params: { uuid: 'uuid-1', ...item } });
716
+ expect(added.linksAdded).toBe(1);
717
+
718
+ const taken = await ad4m.perspective.instanceRemoveFromCollection('uuid-1', item);
719
+ expect(lastRpcCall).toEqual({ type: 'perspective.instanceRemoveFromCollection', params: { uuid: 'uuid-1', ...item } });
720
+ expect(taken.linksRemoved).toBe(1);
721
+ });
722
+
646
723
  test('updateLink() updates a link', async () => {
647
724
  const link = await ad4m.perspective.updateLink('uuid-1',
648
725
  { author: 'a', timestamp: 't', data: { source: 's', predicate: 'p', target: 't' }, proof: { valid: true } } as any,
@@ -1245,6 +1322,33 @@ describe('RuntimeClient', () => {
1245
1322
  const result = await ad4m.runtime.restartHolochain();
1246
1323
  expect(result).toBe(true);
1247
1324
  });
1325
+
1326
+ test('restart() calls runtime.restart', async () => {
1327
+ expect(await ad4m.runtime.restart()).toBe(true);
1328
+ expect(lastRpcCall!.type).toBe('runtime.restart');
1329
+ });
1330
+
1331
+ test('logTail() sends the number of lines', async () => {
1332
+ const tail = await ad4m.runtime.logTail(20);
1333
+ expect(lastRpcCall!.params).toMatchObject({ lines: 20 });
1334
+ expect(tail.lines).toEqual(['asked 20']);
1335
+ });
1336
+
1337
+ test('config() returns the keys with their classes', async () => {
1338
+ const config = await ad4m.runtime.config();
1339
+ expect(lastRpcCall!.type).toBe('runtime.config');
1340
+ expect(config.keys.find(k => k.key === 'port')?.class).toBe('machine');
1341
+ expect(config.keys.find(k => k.key === 'port')?.pinned).toBe('config');
1342
+ expect(config.file).toBe('/data/adam/config.json');
1343
+ });
1344
+
1345
+ test('setConfig() sends set and unset and returns the refusals', async () => {
1346
+ const result = await ad4m.runtime.setConfig({ mcp_port: 3005 }, ['port']);
1347
+ expect(lastRpcCall!.type).toBe('runtime.setConfig');
1348
+ expect(lastRpcCall!.params).toMatchObject({ set: { mcp_port: 3005 }, unset: ['port'] });
1349
+ expect(result.restartPending).toBe(true);
1350
+ expect(result.refused).toEqual([{ key: 'port', reason: 'local-only' }]);
1351
+ });
1248
1352
  });
1249
1353
 
1250
1354
  // ===================== IDENTITY TESTS =====================
@@ -1288,6 +1392,18 @@ describe('IdentityClient', () => {
1288
1392
  expect(lastRpcCall!.params.fresh).toBeUndefined();
1289
1393
  });
1290
1394
 
1395
+ test('rekey() calls identity.rekey and returns the new device keys', async () => {
1396
+ const keys = await ad4m.identity.rekey();
1397
+ expect(lastRpcCall!.type).toBe('identity.rekey');
1398
+ expect(keys).toEqual({ sign: 'did:key:z6MkNew', enc: 'z6LSNew' });
1399
+ });
1400
+
1401
+ test('custodyStatus() calls identity.custodyStatus', async () => {
1402
+ const keys = await ad4m.identity.custodyStatus();
1403
+ expect(lastRpcCall!.type).toBe('identity.custodyStatus');
1404
+ expect(keys.enc).toBe('z6LSTest');
1405
+ });
1406
+
1291
1407
  test('agent.status() carries the identity beside the device did', async () => {
1292
1408
  const status = await ad4m.agent.status();
1293
1409
  expect(status.did).toBe('did:test:123');
package/src/apiClient.ts CHANGED
@@ -11,16 +11,22 @@ export interface WsEvent {
11
11
 
12
12
  /** Error thrown by ApiClient when an RPC call fails. */
13
13
  export class RpcError extends Error {
14
- /** Error code (maps to HTTP status semantics: 400, 401, 403, 404, 500). */
14
+ /** Error code (maps to HTTP status semantics: 400, 401, 403, 404, 422, 500). */
15
15
  readonly status: number
16
16
  /** Raw error message from server. */
17
17
  readonly body: string
18
+ /**
19
+ * Structured detail the executor attached (`error.data`), when it did: e.g. the
20
+ * `InstanceError` of a refused `perspective.instance*` write.
21
+ */
22
+ readonly data?: unknown
18
23
 
19
- constructor(status: number, body: string) {
24
+ constructor(status: number, body: string, data?: unknown) {
20
25
  super(`RPC error ${status}: ${body}`)
21
26
  this.name = "RpcError"
22
27
  this.status = status
23
28
  this.body = body
29
+ this.data = data
24
30
  }
25
31
  }
26
32
 
@@ -253,12 +259,12 @@ export class ApiClient {
253
259
  if (parsed.type === undefined) {
254
260
  const pending = this._pendingCalls.get(parsed.id as string)
255
261
  if (!pending) return // late reply to a timed-out or aborted call, or a cancel ack
256
- const error = parsed.error as { code?: number; message?: string } | undefined
262
+ const error = parsed.error as { code?: number; message?: string; data?: unknown } | undefined
257
263
  if (!error) {
258
264
  pending.resolve(parsed.result)
259
265
  return
260
266
  }
261
- const rpcError = new RpcError(error.code ?? 500, error.message ?? 'Unknown error')
267
+ const rpcError = new RpcError(error.code ?? 500, error.message ?? 'Unknown error', error.data)
262
268
  pending.reject(rpcError)
263
269
  // The executor answers 401 only when the token stopped working, then closes the socket.
264
270
  if (rpcError.status === 401) this._failAuth(rpcError.body)
@@ -13,9 +13,10 @@ seq: number, role: AISessionMessageRole,
13
13
  /**
14
14
  * The transcript entry: `{"text": ..}` for user and assistant turns;
15
15
  * `{"name", "arguments", "target"?, "writes", "result"? | "error"?}` for a
16
- * tool step. `writes` is the executor's own read of the call's side effect
17
- * (`agent_session::tool_writes`), so a client marking the steps that
18
- * changed something does not have to guess from the name.
16
+ * tool step. `writes` is the tool's declared intent
17
+ * (`agent_session::tool_writes`), recorded before the call runs. It does
18
+ * not say the call changed anything: a refused or failed write still has
19
+ * `writes: true`.
19
20
  */
20
21
  content: unknown,
21
22
  /**
@@ -9,8 +9,9 @@ import type { EndpointKind } from "./EndpointKind";
9
9
  export type AiEndpoint = { id: string, name: string, kind: EndpointKind, baseUrl: string, hasApiKey: boolean, capabilities: Array<AiCapability>, maxNumCtx?: number | null,
10
10
  /**
11
11
  * How long a request to this endpoint may take, queueing included. Unset: 300 s for
12
- * chat `/v1` forwards, 600 s for chat the executor answers (Anthropic, Ollama, tools as
13
- * text; not bounded here when streamed), 60 s for embeddings, 120 s for speech.
12
+ * chat `/v1` forwards, 600 s for chat the executor answers, 60 s for embeddings, 120 s
13
+ * for speech. An OpenAI-protocol chat client uses this value for a stream too. A value
14
+ * above 600 s is kept. A stream has no second timer in `within_endpoint_limits`.
14
15
  */
15
16
  requestTimeoutSecs?: number | null,
16
17
  /**