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

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 (43) hide show
  1. package/lib/index.cjs +387 -154
  2. package/lib/index.js +387 -155
  3. package/lib/src/generated/api/AgentMessage.d.ts +10 -0
  4. package/lib/src/generated/api/AgentMessage.js +2 -0
  5. package/lib/src/generated/api/AgentReply.d.ts +9 -0
  6. package/lib/src/generated/api/AgentReply.js +2 -0
  7. package/lib/src/generated/api/RpcMethods.d.ts +6 -0
  8. package/lib/src/generated/api/RpcMethods.js +1 -0
  9. package/lib/src/generated/api/RunAgentRequest.d.ts +26 -0
  10. package/lib/src/generated/api/RunAgentRequest.js +1 -0
  11. package/lib/src/generated/api/index.d.ts +3 -0
  12. package/lib/src/index.d.ts +1 -0
  13. package/lib/src/index.js +1 -0
  14. package/lib/src/model/types.d.ts +6 -0
  15. package/lib/src/neighbourhood/SfuManager.d.ts +15 -0
  16. package/lib/src/neighbourhood/SfuManager.js +39 -2
  17. package/lib/src/perspectives/Mentioning.d.ts +37 -0
  18. package/lib/src/perspectives/Mentioning.js +58 -0
  19. package/lib/src/perspectives/PerspectiveClient.d.ts +22 -0
  20. package/lib/src/perspectives/PerspectiveClient.js +13 -0
  21. package/lib/src/perspectives/PerspectiveProxy.d.ts +19 -0
  22. package/lib/src/perspectives/PerspectiveProxy.js +19 -0
  23. package/lib/src/perspectives/TextContent.d.ts +4 -0
  24. package/lib/src/perspectives/TextContent.js +4 -0
  25. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +69 -10
  26. package/lib/src/perspectives/WakerSubscriptionManager.js +160 -58
  27. package/package.json +2 -2
  28. package/src/generated/api/AgentMessage.ts +10 -0
  29. package/src/generated/api/AgentReply.ts +10 -0
  30. package/src/generated/api/RpcMethods.ts +4 -0
  31. package/src/generated/api/RunAgentRequest.ts +26 -0
  32. package/src/generated/api/index.ts +3 -0
  33. package/src/index.ts +1 -0
  34. package/src/model/types.ts +6 -0
  35. package/src/neighbourhood/SfuManager.test.ts +151 -2
  36. package/src/neighbourhood/SfuManager.ts +38 -1
  37. package/src/perspectives/Mentioning.test.ts +78 -0
  38. package/src/perspectives/Mentioning.ts +42 -0
  39. package/src/perspectives/PerspectiveClient.ts +30 -0
  40. package/src/perspectives/PerspectiveProxy.ts +26 -0
  41. package/src/perspectives/TextContent.ts +4 -0
  42. package/src/perspectives/WakerSubscriptionManager.test.ts +383 -151
  43. package/src/perspectives/WakerSubscriptionManager.ts +217 -58
@@ -6,6 +6,9 @@
6
6
  * module (`plugins/ad4m/wakerSubscriptionManager.ts`) rather than carrying its
7
7
  * own copy. Any behaviour change belongs here.
8
8
  */
9
+ /** The built-in `Container` (`Container.builtinUri`; not imported, so the
10
+ * plugin bundle does not pull in the model layer). */
11
+ const CONTAINER = "ad4m://Container";
9
12
  /** A letter, combining mark, digit or underscore: what a term must not touch. */
10
13
  const WORD_CHAR = "[\\p{L}\\p{M}\\p{N}_]";
11
14
  /**
@@ -35,14 +38,6 @@ const BREAKING_TAG = /^<\/?(?:p|div|br|hr|li|ul|ol|h[1-6]|blockquote|pre|tr|td|t
35
38
  */
36
39
  const ATTRIBUTES = new RegExp(ATTRIBUTE, "g");
37
40
  const MENTION_TARGET = /^\s+(?:href|data-id|data-did)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))$/i;
38
- /**
39
- * How much of a record's text the word check reads. Dropping markup costs time
40
- * quadratic in a run of unclosed `<script>`, `<style>` or `<!--` openers, so a
41
- * very long text could hold the event loop for seconds, and a row that holds
42
- * no term is checked again on every result while it is in the window. A term
43
- * past this many characters does not wake.
44
- */
45
- export const MENTION_TEXT_LIMIT = 16384;
46
41
  const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
47
42
  function decodeEntities(s) {
48
43
  return s.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (whole, ref) => {
@@ -76,6 +71,14 @@ function readableParts(text) {
76
71
  });
77
72
  return { visible: decodeEntities(visible), targets };
78
73
  }
74
+ /**
75
+ * How much of a record's text the word check reads. Dropping markup costs time
76
+ * quadratic in a run of unclosed `<script>`, `<style>` or `<!--` openers, so a
77
+ * very long text could hold the event loop for seconds, and a row that holds
78
+ * no term is checked again on every result while it is in the window. A term
79
+ * past this many characters does not wake.
80
+ */
81
+ export const MENTION_TEXT_LIMIT = 16384;
79
82
  /**
80
83
  * Whether `text` holds one of `terms` as a whole word, case-insensitively:
81
84
  * "Data" is in "hi Data!", "@data" and "Data's turn", not in "metadata" or
@@ -90,7 +93,9 @@ function readableParts(text) {
90
93
  * is how a mention by DID is found when the DID is not in the visible text.
91
94
  *
92
95
  * The mention query's `contains` matches substrings (model query has no word
93
- * match); this is the check that keeps "data" from waking on "metadata".
96
+ * match); this is the check that keeps "data" from waking on "metadata" when
97
+ * a record is found through its text alone ({@link mentionOf}).
98
+ *
94
99
  * It reads the first {@link MENTION_TEXT_LIMIT} characters only.
95
100
  */
96
101
  export function holdsAWholeWordTerm(text, terms) {
@@ -104,9 +109,95 @@ export function holdsAWholeWordTerm(text, terms) {
104
109
  return new RegExp(`(?<!${WORD_CHAR})${escaped}(?!${WORD_CHAR})`, "iu").test(visible);
105
110
  });
106
111
  }
107
- /** The built-in `Container` (`Container.builtinUri`; not imported, so the
108
- * plugin bundle does not pull in the model layer). */
109
- const CONTAINER = "ad4m://Container";
112
+ /** The provenance {@link MentionMessage} carries, from one link. */
113
+ function provenanceOf(link, via) {
114
+ const provenance = {
115
+ verified: link?.proof?.valid === true,
116
+ via,
117
+ };
118
+ if (typeof link?.author === "string")
119
+ provenance.author = link.author;
120
+ if (typeof link?.timestamp === "string")
121
+ provenance.timestamp = link.timestamp;
122
+ return provenance;
123
+ }
124
+ /** The links a model row carries for `key` under `__links`, oldest first. */
125
+ function rowLinks(row, key) {
126
+ const links = row?.__links?.[key];
127
+ return Array.isArray(links) ? links : [];
128
+ }
129
+ /** `uri` URI-decoded, or as it is when it is not valid percent-encoding. */
130
+ function decoded(uri) {
131
+ try {
132
+ return decodeURIComponent(uri);
133
+ }
134
+ catch {
135
+ return uri;
136
+ }
137
+ }
138
+ /**
139
+ * The text a link's target holds, read as the executor reads a string property
140
+ * (`parse_literal_value`): `literal:string:` decoded, `literal:json:` parsed (a signed
141
+ * expression to its `data`), any other URI as it is. `undefined` when that is not a string.
142
+ */
143
+ function textOf(target) {
144
+ if (typeof target !== "string")
145
+ return undefined;
146
+ if (!target.startsWith("literal:"))
147
+ return target;
148
+ const body = target.slice("literal:".length);
149
+ if (body.startsWith("string:"))
150
+ return decoded(body.slice("string:".length));
151
+ if (body.startsWith("json:")) {
152
+ const json = decoded(body.slice("json:".length));
153
+ let value;
154
+ try {
155
+ value = JSON.parse(json);
156
+ }
157
+ catch {
158
+ return json;
159
+ }
160
+ if (value && typeof value === "object" && "data" in value && "author" in value && "proof" in value) {
161
+ value = value.data;
162
+ }
163
+ return typeof value === "string" ? value : undefined;
164
+ }
165
+ if (/^(?:number|boolean):/.test(body))
166
+ return undefined;
167
+ return target;
168
+ }
169
+ /**
170
+ * Whether a row of one of the mention subscription's two model queries mentions the
171
+ * subscription's agent, and the provenance of the link it does so in; `null` when it does not.
172
+ *
173
+ * - A row of the query over Mentioning: a verified link to the agent's DID that another agent
174
+ * wrote, in the row's `__links.mentions`. It wakes whatever the record's text says, or
175
+ * whether it has any: WE's chip label may run into the next word ("@Datai have…"), and a WE
176
+ * post's mention sits on its root, which has no text. Its provenance is that link's (the
177
+ * newest such).
178
+ * - A row of the query over TextContent: the query matched a substring, so the text must hold
179
+ * a term as a whole word ({@link holdsAWholeWordTerm}), and so must the text of a verified
180
+ * link another agent wrote, in `__links.text`. Its provenance is that link's (the newest
181
+ * such). The row's `text` is the newest text link's, whoever wrote it, so it does not say
182
+ * whose words they are.
183
+ *
184
+ * `via` says which it was. A record both queries find wakes once, through the query that
185
+ * reports it first ({@link WakerSubscriptionManager}).
186
+ */
187
+ export function mentionOf(row, sub) {
188
+ const did = sub.did;
189
+ const byOthers = (links) => links.filter((l) => typeof l.author === "string" && l.author !== did);
190
+ const linked = byOthers(rowLinks(row, "mentions")).filter((l) => l.data?.target === did && l.proof?.valid === true);
191
+ if (did && linked.length)
192
+ return provenanceOf(linked[linked.length - 1], "mentions");
193
+ const terms = sub.terms ?? [];
194
+ const names = (text) => typeof text === "string" && holdsAWholeWordTerm(text, terms);
195
+ const text = Array.isArray(row?.text) ? row.text.join(" ") : row?.text;
196
+ if (!names(text))
197
+ return null;
198
+ const naming = byOthers(rowLinks(row, "text")).filter((l) => l.proof?.valid === true && names(textOf(l.data?.target)));
199
+ return naming.length ? provenanceOf(naming[naming.length - 1], "text") : null;
200
+ }
110
201
  /**
111
202
  * Add a short cause hint to known subscription failures.
112
203
  * The executor needs its main key to register a live query; on a restarted
@@ -152,6 +243,7 @@ async function withTimeout(promise, ms, message) {
152
243
  }
153
244
  export class WakerSubscriptionManager {
154
245
  constructor(options) {
246
+ /** Per subscription its proxies: one, or a mention subscription's text and mention queries. */
155
247
  this.proxies = new Map();
156
248
  this.activeSubscriptions = new Map();
157
249
  /** Subscriptions the executor rejected, waiting to be re-attempted. */
@@ -221,21 +313,40 @@ export class WakerSubscriptionManager {
221
313
  throw new Error("WakerSubscriptionManager: QuerySubscriptionProxy must be provided via constructor options");
222
314
  }
223
315
  const QuerySubscriptionProxy = this.QuerySubscriptionProxyCtor;
224
- if (sub.type === "mention" && sub.className && !sub.terms?.length) {
225
- // Without terms the whole-word check cannot run, and every substring
226
- // ("metadata" for "data") would wake the agent.
227
- throw new Error(`Waker subscription ${sub.id}: a mention subscription needs its terms (get_mention_waker_config returns them)`);
316
+ if (sub.type === "mention" &&
317
+ (!sub.className || !sub.terms?.length || !sub.did || !sub.mentionQuery || !sub.mentionClass)) {
318
+ // Without terms the whole-word check cannot run, so every substring
319
+ // ("metadata" for "data") would wake the agent; without the DID no link
320
+ // can be told to be someone else's; without the mention query a mention
321
+ // link on a record with no text (a WE post's root) never wakes it.
322
+ throw new Error(`Waker subscription ${sub.id}: a mention subscription needs its TextContent class, terms, DID and Mentioning query (get_mention_waker_config returns them)`);
228
323
  }
229
324
  this.logger.info(`[waker] ${sub.id}: creating subscription (perspective=${sub.perspective}, type=${sub.type})`);
230
325
  this.logger.info(`[waker] ${sub.id}: ${sub.className ? `model query over ${sub.className}` : "SPARQL query"}:\n${sub.query}`);
326
+ if (sub.mentionQuery) {
327
+ this.logger.info(`[waker] ${sub.id}: model query over ${sub.mentionClass}:\n${sub.mentionQuery}`);
328
+ }
231
329
  const proxy = sub.className
232
330
  ? new QuerySubscriptionProxy(sub.perspective, sub.query, this.perspectiveClient, sub.className)
233
331
  : new QuerySubscriptionProxy(sub.perspective, sub.query, this.perspectiveClient);
332
+ const mentionProxy = sub.mentionQuery
333
+ ? new QuerySubscriptionProxy(sub.perspective, sub.mentionQuery, this.perspectiveClient, sub.mentionClass)
334
+ : undefined;
335
+ const proxies = mentionProxy ? [proxy, mentionProxy] : [proxy];
336
+ const disposeProxies = () => {
337
+ for (const p of proxies) {
338
+ try {
339
+ p.dispose();
340
+ }
341
+ catch { }
342
+ }
343
+ };
234
344
  // Suppress unhandled rejection from proxy.initialized — QuerySubscriptionProxy
235
345
  // rejects this promise internally when subscribe() fails, and if nobody catches
236
346
  // it before the next microtask it crashes the process.
237
- if (proxy.initialized && typeof proxy.initialized.catch === "function") {
238
- proxy.initialized.catch(() => { });
347
+ for (const p of proxies) {
348
+ if (p.initialized && typeof p.initialized.catch === "function")
349
+ p.initialized.catch(() => { });
239
350
  }
240
351
  // One deadline for the whole handshake: `proxy.subscribe()` and the
241
352
  // `initialized` promise it resolves share the budget, so a hang in either
@@ -246,23 +357,17 @@ export class WakerSubscriptionManager {
246
357
  ? withTimeout(step, Math.max(0, budgetMs - (Date.now() - startedAt)), `${what} timed out after ${budgetMs}ms`)
247
358
  : step;
248
359
  try {
249
- await bounded(proxy.subscribe(), "subscribe handshake");
360
+ await bounded(Promise.all(proxies.map((p) => p.subscribe())), "subscribe handshake");
250
361
  if (this.isStale(sub.id, token)) {
251
- try {
252
- proxy.dispose();
253
- }
254
- catch { }
362
+ disposeProxies();
255
363
  return;
256
364
  }
257
- await bounded(proxy.initialized, "subscription initialization");
365
+ await bounded(Promise.all(proxies.map((p) => p.initialized)), "subscription initialization");
258
366
  }
259
367
  catch (err) {
260
368
  const msg = err?.message ?? String(err);
261
369
  this.logger.warn(`[waker] ${sub.id}: subscription failed — ${msg}`);
262
- try {
263
- proxy.dispose();
264
- }
265
- catch { }
370
+ disposeProxies();
266
371
  // A dispose that landed mid-attempt wins: don't re-queue something the
267
372
  // caller has since asked us to forget.
268
373
  if (this.isStale(sub.id, token))
@@ -287,10 +392,7 @@ export class WakerSubscriptionManager {
287
392
  : ""));
288
393
  }
289
394
  if (this.isStale(sub.id, token)) {
290
- try {
291
- proxy.dispose();
292
- }
293
- catch { }
395
+ disposeProxies();
294
396
  return;
295
397
  }
296
398
  this.pendingSubscriptions.delete(sub.id);
@@ -305,8 +407,9 @@ export class WakerSubscriptionManager {
305
407
  }
306
408
  // `opening` is the result the subscription holds when it opens (`proxy.result`): `onResult`
307
409
  // only reports later changes, so this is the one chance to see what was written meanwhile.
308
- const handleResult = async (result, opening = false) => {
309
- this.logger.info(`[waker] ${sub.id}: ${opening ? "opening result" : "onResult fired"} — type=${typeof result}, isArray=${Array.isArray(result)}, value=${String(JSON.stringify(result)).substring(0, 500)}`);
410
+ // `of`: the query the result is from, for the log (a mention subscription has two).
411
+ const handleResult = async (result, opening = false, of = "") => {
412
+ 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)}`);
310
413
  // A model subscription delivers `{ instances }`, SPARQL an array of
311
414
  // rows. Anything else (e.g. `false` on a disconnect/reconnect) is
312
415
  // ignored.
@@ -316,26 +419,25 @@ export class WakerSubscriptionManager {
316
419
  return;
317
420
  }
318
421
  if (sub.type === "mention") {
319
- // For mention subscriptions: track seen record ids.
320
- // Only wake for records we haven't seen before.
422
+ // For mention subscriptions: track seen record ids, across both queries, and wake only
423
+ // for records not seen before, so a record both find wakes once, through the query that
424
+ // reports it first.
321
425
  const currentSeen = this.seenMessages.get(sub.id) ?? new Set();
322
426
  const newMessages = [];
323
- const terms = sub.terms ?? [];
427
+ const provenance = new Map();
324
428
  for (const item of rows) {
325
- // A SPARQL row names the record as `source`, a model row as `id`.
326
- const address = sub.className ? item?.id : item?.source;
429
+ const address = item?.id;
327
430
  if (typeof address !== "string" || !address || currentSeen.has(address))
328
431
  continue;
329
- if (terms.length) {
330
- // The mention query matched a substring; wake only on a whole word.
331
- const text = Array.isArray(item.text) ? item.text.join(" ") : item.text;
332
- if (typeof text !== "string" || !holdsAWholeWordTerm(text, terms)) {
333
- this.logger.debug(`[waker] ${sub.id}: ${address} holds no term as a whole word, skipping`);
334
- continue;
335
- }
432
+ // A mention link as it is; the text, a whole word only.
433
+ const mention = mentionOf(item, sub);
434
+ if (!mention) {
435
+ this.logger.debug(`[waker] ${sub.id}: ${address} has no verified mention link and no term as a whole word, skipping`);
436
+ continue;
336
437
  }
337
438
  currentSeen.add(address);
338
439
  newMessages.push(address);
440
+ provenance.set(address, mention);
339
441
  }
340
442
  if (newMessages.length === 0) {
341
443
  this.logger.info(`[waker] ${sub.id}: no new mention among ${rows.length} items, skipping`);
@@ -360,7 +462,7 @@ export class WakerSubscriptionManager {
360
462
  const ancestors = await this.ancestorsOf(sub, msgAddr, parents);
361
463
  this.logger.info(`[waker] ${sub.id}: message ${msgAddr} has ${parents.length} parent(s): ${parents.join(", ")}` +
362
464
  (ancestors.length ? `; ancestors: ${ancestors.join(", ")}` : ""));
363
- mentions.push({ address: msgAddr, parents, ancestors });
465
+ mentions.push({ address: msgAddr, parents, ancestors, ...provenance.get(msgAddr) });
364
466
  }
365
467
  this.seenMessages.set(sub.id, currentSeen);
366
468
  const pending = this.undelivered.get(sub.id) ?? new Map();
@@ -386,20 +488,21 @@ export class WakerSubscriptionManager {
386
488
  }
387
489
  };
388
490
  proxy.onResult((result) => handleResult(result));
491
+ mentionProxy?.onResult((result) => handleResult(result, false, " (mention query)"));
389
492
  if (this.isStale(sub.id, token)) {
390
- try {
391
- proxy.dispose();
392
- }
393
- catch { }
493
+ disposeProxies();
394
494
  return;
395
495
  }
396
- this.proxies.set(sub.id, proxy);
496
+ this.proxies.set(sub.id, proxies);
397
497
  this.activeSubscriptions.set(sub.id, sub);
398
498
  // After a restart this wakes on mentions written while the waker was down; on a new
399
- // subscription it records the existing ones as history.
400
- if (proxy.result !== undefined) {
499
+ // subscription it records the existing ones as history. The mention query's first, so a
500
+ // record both hold wakes through its mention link.
501
+ for (const [p, of] of [[mentionProxy, " (mention query)"], [proxy, ""]]) {
502
+ if (p?.result === undefined)
503
+ continue;
401
504
  try {
402
- await handleResult(proxy.result, true);
505
+ await handleResult(p.result, true, of);
403
506
  }
404
507
  catch (e) {
405
508
  this.logger.warn(`[waker] ${sub.id}: reading the opening result failed: ${e?.message ?? e}`);
@@ -462,16 +565,15 @@ export class WakerSubscriptionManager {
462
565
  dispose(id, persist = true) {
463
566
  // Invalidate any subscribe() for this id that is still awaiting.
464
567
  this.generations.set(id, (this.generations.get(id) ?? 0) + 1);
465
- const proxy = this.proxies.get(id);
466
- if (proxy) {
568
+ for (const proxy of this.proxies.get(id) ?? []) {
467
569
  try {
468
570
  proxy.dispose();
469
571
  }
470
572
  catch {
471
573
  /* ignore */
472
574
  }
473
- this.proxies.delete(id);
474
575
  }
576
+ this.proxies.delete(id);
475
577
  const timer = this.debounceTimers.get(id);
476
578
  if (timer) {
477
579
  clearTimeout(timer);
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.4",
57
- "gitHead": "e5b5e7c4b565c7d7bdafe6913c1e15ac4428de99",
56
+ "version": "0.13.1-staging.5",
57
+ "gitHead": "5e32fa503b2f4011d9214d405809b085c9ccd462",
58
58
  "scripts": {
59
59
  "build": "patch-package && tsc && pnpm run bundle",
60
60
  "bundle": "rollup -c rollup.config.js",
@@ -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.
@@ -509,6 +509,12 @@ export interface LinkRow {
509
509
  timestamp: string;
510
510
  data: { source: string; predicate: string; target: string };
511
511
  proof: { key: string; signature: string; valid: boolean; invalid: boolean };
512
+ /**
513
+ * Where this executor holds the link, spelled as `perspective.get()` spells
514
+ * it. Absent only when the store recorded none. Not signed: it says nothing
515
+ * about who wrote the link.
516
+ */
517
+ status?: "SHARED" | "LOCAL";
512
518
  }
513
519
 
514
520
  /** `instance.__links`: requested entry (spelled as requested) → its rows, oldest first. */
@@ -136,8 +136,14 @@ function mapped(mid: string, agentDid: string, mediaKind: "audio" | "video"): Tr
136
136
  return { mid, agentDid, mediaKind }
137
137
  }
138
138
 
139
- function roster(participants: string[], overrides: Partial<SfuRoomRoster> = {}): SfuRoomRoster {
140
- return { neighbourhoodUrl: URL, roomName: ROOM, participants, ...overrides }
139
+ /** The room's roster as the executor publishes it: this agent is in it, unless `withoutMe`. */
140
+ function roster(
141
+ participants: string[],
142
+ overrides: Partial<SfuRoomRoster> = {},
143
+ { withoutMe = false } = {},
144
+ ): SfuRoomRoster {
145
+ const listed = withoutMe || participants.includes(ME) ? participants : [...participants, ME]
146
+ return { neighbourhoodUrl: URL, roomName: ROOM, participants: listed, ...overrides }
141
147
  }
142
148
 
143
149
  function deferred<T>() {
@@ -555,6 +561,149 @@ test("a failed connection leaves, then joins this executor again", async () => {
555
561
  expect(FakePeerConnection.instances).toHaveLength(2)
556
562
  })
557
563
 
564
+ test("a roster that leaves this agent out rebuilds the call after the grace", async () => {
565
+ // The server dropped this session; ICE never said so (E6, CI job 53158).
566
+ jest.useFakeTimers({ doNotFake: ["queueMicrotask", "nextTick", "setImmediate"] })
567
+ try {
568
+ const api = fakeApi()
569
+ const manager = new SfuManager(api, ROOM, ME, URL)
570
+ await manager.join(fakeStream())
571
+ const dropped = currentPc()
572
+ api.log.length = 0
573
+
574
+ api.emitRoster(roster([ALICE], {}, { withoutMe: true }))
575
+ await flush()
576
+ await jest.advanceTimersByTimeAsync(2_999)
577
+ expect(api.log).toEqual([])
578
+
579
+ await jest.advanceTimersByTimeAsync(1)
580
+ expect(dropped.closed).toBe(true)
581
+ expect(api.log).toEqual([
582
+ "unsubscribe-offer",
583
+ "unsubscribe-roster",
584
+ "sfuCallLeave",
585
+ "subscribe-offer",
586
+ "subscribe-roster",
587
+ "sfuCallJoin",
588
+ ])
589
+ } finally {
590
+ jest.useRealTimers()
591
+ }
592
+ })
593
+
594
+ test("a roster that lists this agent again within the grace cancels the rebuild", async () => {
595
+ // A roster published just before this join landed can arrive after it.
596
+ jest.useFakeTimers({ doNotFake: ["queueMicrotask", "nextTick", "setImmediate"] })
597
+ try {
598
+ const api = fakeApi()
599
+ const manager = new SfuManager(api, ROOM, ME, URL)
600
+ await manager.join(fakeStream())
601
+ api.log.length = 0
602
+
603
+ api.emitRoster(roster([ALICE], {}, { withoutMe: true }))
604
+ await flush()
605
+ await jest.advanceTimersByTimeAsync(1_000)
606
+ api.emitRoster(roster([ALICE, ME]))
607
+ await flush()
608
+ await jest.advanceTimersByTimeAsync(10_000)
609
+
610
+ expect(api.log).toEqual([])
611
+ expect(currentPc().closed).toBe(false)
612
+ } finally {
613
+ jest.useRealTimers()
614
+ }
615
+ })
616
+
617
+ test("leaving stops a pending rebuild for an unlisted session", async () => {
618
+ jest.useFakeTimers({ doNotFake: ["queueMicrotask", "nextTick", "setImmediate"] })
619
+ try {
620
+ const api = fakeApi()
621
+ const manager = new SfuManager(api, ROOM, ME, URL)
622
+ await manager.join(fakeStream())
623
+ api.emitRoster(roster([ALICE], {}, { withoutMe: true }))
624
+ await flush()
625
+
626
+ await manager.leave()
627
+ await jest.advanceTimersByTimeAsync(10_000)
628
+
629
+ expect(api.sfuCallJoin).toHaveBeenCalledTimes(1)
630
+ } finally {
631
+ jest.useRealTimers()
632
+ }
633
+ })
634
+
635
+ test("after a cancelled grace, a later roster without this agent starts a new one", async () => {
636
+ jest.useFakeTimers({ doNotFake: ["queueMicrotask", "nextTick", "setImmediate"] })
637
+ try {
638
+ const api = fakeApi()
639
+ const manager = new SfuManager(api, ROOM, ME, URL)
640
+ await manager.join(fakeStream())
641
+
642
+ api.emitRoster(roster([ALICE], {}, { withoutMe: true }))
643
+ await flush()
644
+ api.emitRoster(roster([ALICE, ME]))
645
+ await flush()
646
+ await jest.advanceTimersByTimeAsync(10_000)
647
+ expect(api.sfuCallJoin).toHaveBeenCalledTimes(1)
648
+
649
+ api.emitRoster(roster([ALICE], {}, { withoutMe: true }))
650
+ await flush()
651
+ await jest.advanceTimersByTimeAsync(3_000)
652
+ expect(api.sfuCallJoin).toHaveBeenCalledTimes(2)
653
+ } finally {
654
+ jest.useRealTimers()
655
+ }
656
+ })
657
+
658
+ test("a second roster without this agent keeps the first grace, and one listing it cancels both", async () => {
659
+ // Others leaving while this session is unlisted publish more rosters without it.
660
+ jest.useFakeTimers({ doNotFake: ["queueMicrotask", "nextTick", "setImmediate"] })
661
+ try {
662
+ const api = fakeApi()
663
+ const manager = new SfuManager(api, ROOM, ME, URL)
664
+ await manager.join(fakeStream())
665
+
666
+ api.emitRoster(roster([ALICE, BOB], {}, { withoutMe: true }))
667
+ await flush()
668
+ await jest.advanceTimersByTimeAsync(1_000)
669
+ api.emitRoster(roster([ALICE], {}, { withoutMe: true }))
670
+ await flush()
671
+ await jest.advanceTimersByTimeAsync(1_000)
672
+ api.emitRoster(roster([ALICE, ME]))
673
+ await flush()
674
+ await jest.advanceTimersByTimeAsync(10_000)
675
+
676
+ expect(api.sfuCallJoin).toHaveBeenCalledTimes(1)
677
+ expect(currentPc().closed).toBe(false)
678
+ } finally {
679
+ jest.useRealTimers()
680
+ }
681
+ })
682
+
683
+ test("a rebuild for ICE ends the old grace, and the new connection gets its own", async () => {
684
+ jest.useFakeTimers({ doNotFake: ["queueMicrotask", "nextTick", "setImmediate"] })
685
+ try {
686
+ const api = fakeApi()
687
+ const manager = new SfuManager(api, ROOM, ME, URL)
688
+ await manager.join(fakeStream())
689
+
690
+ api.emitRoster(roster([ALICE], {}, { withoutMe: true }))
691
+ await flush()
692
+ await jest.advanceTimersByTimeAsync(1_000)
693
+ await iceState("failed")
694
+ expect(FakePeerConnection.instances).toHaveLength(2)
695
+
696
+ api.emitRoster(roster([ALICE], {}, { withoutMe: true }))
697
+ await flush()
698
+ await jest.advanceTimersByTimeAsync(2_999)
699
+ expect(FakePeerConnection.instances).toHaveLength(2)
700
+ await jest.advanceTimersByTimeAsync(1)
701
+ expect(FakePeerConnection.instances).toHaveLength(3)
702
+ } finally {
703
+ jest.useRealTimers()
704
+ }
705
+ })
706
+
558
707
  test("a rejoin the executor cannot take yet is retried, and succeeds once it can", async () => {
559
708
  // A restart or an outage: the executor refuses for a while, then is back.
560
709
  jest.useFakeTimers({ doNotFake: ["queueMicrotask", "nextTick", "setImmediate"] })