@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
@@ -90,8 +90,9 @@ export class PerspectiveClient {
90
90
  return JSON.parse(result);
91
91
  }
92
92
  /** Open a live SPARQL query. Updates arrive through {@link onQueryUpdate}. */
93
- async subscribeQuery(uuid, query) {
94
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.subscribeQuery', { uuid, query });
93
+ /** `options.signal` cancels the call, and the executor stops computing the first result. */
94
+ async subscribeQuery(uuid, query, options) {
95
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.subscribeQuery', { uuid, query }, options);
95
96
  }
96
97
  /** Every `query-subscription-update` event on this client's socket. */
97
98
  onQueryUpdate(cb) {
@@ -124,8 +125,9 @@ export class PerspectiveClient {
124
125
  return JSON.parse(resultJson);
125
126
  }
126
127
  /** Open a live model query over one class or several. Updates arrive through {@link onQueryUpdate}. */
127
- async modelSubscribe(uuid, className, queryJson) {
128
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.modelSubscribe', { uuid, ...classParams(className), query_json: queryJson });
128
+ /** `options.signal` cancels the call, and the executor stops computing the first result. */
129
+ async modelSubscribe(uuid, className, queryJson, options) {
130
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.modelSubscribe', { uuid, ...classParams(className), query_json: queryJson }, options);
129
131
  }
130
132
  async add(name) {
131
133
  const handle = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.create', { name });
@@ -211,6 +213,19 @@ export class PerspectiveClient {
211
213
  emitDebugEvents,
212
214
  }, options);
213
215
  }
216
+ /**
217
+ * A conversation with a model in this perspective, using the executor's own tools: the tools
218
+ * that read this perspective, and only the writing tools named in `writeTools`. Every tool a
219
+ * session offers acts on this perspective alone, so tools about other perspectives, the agent
220
+ * or the node (listing or publishing perspectives, the profile) are not available. Runs as the
221
+ * caller, with the caller's capabilities, and answers with the model's final reply.
222
+ *
223
+ * Defaults to {@link LONG_TIMEOUT_MS}: an agent may read documentation and make many tool
224
+ * calls before it answers.
225
+ */
226
+ async runAgent(uuid, messages, settings, options) {
227
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runAgent', { uuid, messages, ...settings }, options);
228
+ }
214
229
  /**
215
230
  * Register a neighbourhood auto-processor on this perspective. The executor's
216
231
  * watch loop then runs interpretation automatically over new source items
@@ -11,8 +11,10 @@ import { NeighbourhoodProxy } from "../neighbourhood/NeighbourhoodProxy";
11
11
  import { NeighbourhoodExpression } from "../neighbourhood/Neighbourhood";
12
12
  import { AIClient } from "../ai/AIClient";
13
13
  import { AllInstancesResult } from "../model/types";
14
- import { Subscribed } from "./LiveQuery";
14
+ import { LiveQueryStatus, Subscribed } from "./LiveQuery";
15
15
  import type { TranscriptTurn } from "../generated/api";
16
+ import type { AgentMessage } from "../generated/api/AgentMessage";
17
+ import type { AgentReply } from "../generated/api/AgentReply";
16
18
  import type { JsonValue } from "../generated/api/serde_json/JsonValue";
17
19
  import { SHACLShape } from "../shacl/SHACLShape";
18
20
  import { SHACLFlow } from "../shacl/SHACLFlow";
@@ -47,8 +49,20 @@ export declare class QuerySubscriptionProxy {
47
49
  get result(): AllInstancesResult;
48
50
  /** Call `callback` with every later result. Returns a remover. */
49
51
  onResult(callback: QueryCallback): () => void;
50
- /** End the subscription on the executor and drop all callbacks. */
51
- dispose(): void;
52
+ /** Whether the query lost its subscription (a reconnect, a failed
53
+ * resync), could not open it again yet and is retrying: `result` is then
54
+ * not live. */
55
+ get reopening(): boolean;
56
+ /** Call `listener` on each failed re-open of the subscription and when a
57
+ * re-open succeeds after one failed (see {@link LiveQueryStatus}).
58
+ * Returns a remover. */
59
+ onStatus(listener: (status: LiveQueryStatus) => void): () => void;
60
+ /** End the subscription on the executor and drop all callbacks. With
61
+ * `cancelOpening`, a `subscribe()` still waiting on the executor is
62
+ * cancelled too, and rejects. */
63
+ dispose(options?: {
64
+ cancelOpening?: boolean;
65
+ }): void;
52
66
  }
53
67
  /** Link status argument. The executor accepts either case and returns links
54
68
  * with the upper-case form (`LinkExpression.status`). */
@@ -252,6 +266,17 @@ export declare class PerspectiveProxy {
252
266
  * @param options `signal` / `timeoutMs` (default {@link LONG_TIMEOUT_MS})
253
267
  */
254
268
  runInterpretationWithHarness(transcript: TranscriptTurn[], basePrefix: string, maxToolCalls: number, classes?: string[], modelOverride?: string, observationId?: string, emitDebugEvents?: boolean, options?: CallOptions): Promise<string[]>;
269
+ /**
270
+ * Ask a model something about this perspective, or ask it to change something, with the
271
+ * executor's own tools — including the tools apps install for their records. It reads freely;
272
+ * it writes only with the tools named in `settings.writeTools`, as you. Answers with the
273
+ * model's final reply.
274
+ *
275
+ * @param messages the conversation so far, the person's request last
276
+ * @param settings `context` (what the person is looking at), `writeTools`, `model`, `maxToolCalls`
277
+ * @param options `signal` / `timeoutMs` (default {@link LONG_TIMEOUT_MS})
278
+ */
279
+ runAgent(messages: AgentMessage[], settings?: Parameters<PerspectiveClient['runAgent']>[2], options?: CallOptions): Promise<AgentReply>;
255
280
  /**
256
281
  * Register a neighbourhood auto-processor on this perspective. The executor
257
282
  * then runs interpretation automatically over new source items (like Flux
@@ -542,6 +567,12 @@ export declare class PerspectiveProxy {
542
567
  /**
543
568
  * Adds a pre-signed LinkExpression to the perspective.
544
569
  *
570
+ * The executor checks the signature against `link.author` and stores the
571
+ * verdict as `proof.valid`. If the same link (author, source, predicate,
572
+ * target and timestamp) is already stored with a signature that verifies,
573
+ * its stored proof is kept. The expression passed here is still returned
574
+ * and, when Shared, committed to the neighbourhood as given.
575
+ *
545
576
  * @param link - The signed LinkExpression to add
546
577
  * @param status - Whether the link should be shared
547
578
  * @param batchId - Optional batch ID to group this operation with others
@@ -56,8 +56,8 @@ export class QuerySubscriptionProxy {
56
56
  _QuerySubscriptionProxy_initResolve.set(this, void 0);
57
57
  _QuerySubscriptionProxy_initReject.set(this, void 0);
58
58
  const open = className === undefined
59
- ? () => client.subscribeQuery(uuid, query)
60
- : () => client.modelSubscribe(uuid, className, query);
59
+ ? (signal) => client.subscribeQuery(uuid, query, { signal })
60
+ : (signal) => client.modelSubscribe(uuid, className, query, { signal });
61
61
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_live, new LiveQuery(client, uuid, open, result => __classPrivateFieldGet(this, _QuerySubscriptionProxy_instances, "m", _QuerySubscriptionProxy_deliver).call(this, result)), "f");
62
62
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_initialized, new Promise((resolve, reject) => {
63
63
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_initResolve, resolve, "f");
@@ -95,9 +95,23 @@ export class QuerySubscriptionProxy {
95
95
  __classPrivateFieldGet(this, _QuerySubscriptionProxy_callbacks, "f").add(callback);
96
96
  return () => __classPrivateFieldGet(this, _QuerySubscriptionProxy_callbacks, "f").delete(callback);
97
97
  }
98
- /** End the subscription on the executor and drop all callbacks. */
99
- dispose() {
100
- __classPrivateFieldGet(this, _QuerySubscriptionProxy_live, "f").dispose();
98
+ /** Whether the query lost its subscription (a reconnect, a failed
99
+ * resync), could not open it again yet and is retrying: `result` is then
100
+ * not live. */
101
+ get reopening() {
102
+ return __classPrivateFieldGet(this, _QuerySubscriptionProxy_live, "f").reopening;
103
+ }
104
+ /** Call `listener` on each failed re-open of the subscription and when a
105
+ * re-open succeeds after one failed (see {@link LiveQueryStatus}).
106
+ * Returns a remover. */
107
+ onStatus(listener) {
108
+ return __classPrivateFieldGet(this, _QuerySubscriptionProxy_live, "f").onStatus(listener);
109
+ }
110
+ /** End the subscription on the executor and drop all callbacks. With
111
+ * `cancelOpening`, a `subscribe()` still waiting on the executor is
112
+ * cancelled too, and rejects. */
113
+ dispose(options = {}) {
114
+ __classPrivateFieldGet(this, _QuerySubscriptionProxy_live, "f").dispose(options);
101
115
  __classPrivateFieldGet(this, _QuerySubscriptionProxy_callbacks, "f").clear();
102
116
  }
103
117
  }
@@ -349,6 +363,19 @@ export class PerspectiveProxy {
349
363
  observationId, emitDebugEvents, options) {
350
364
  return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").runInterpretationWithHarness(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, transcript, basePrefix, maxToolCalls, classes, modelOverride, undefined, observationId, emitDebugEvents, options);
351
365
  }
366
+ /**
367
+ * Ask a model something about this perspective, or ask it to change something, with the
368
+ * executor's own tools — including the tools apps install for their records. It reads freely;
369
+ * it writes only with the tools named in `settings.writeTools`, as you. Answers with the
370
+ * model's final reply.
371
+ *
372
+ * @param messages the conversation so far, the person's request last
373
+ * @param settings `context` (what the person is looking at), `writeTools`, `model`, `maxToolCalls`
374
+ * @param options `signal` / `timeoutMs` (default {@link LONG_TIMEOUT_MS})
375
+ */
376
+ async runAgent(messages, settings, options) {
377
+ return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").runAgent(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, messages, settings, options);
378
+ }
352
379
  /**
353
380
  * Register a neighbourhood auto-processor on this perspective. The executor
354
381
  * then runs interpretation automatically over new source items (like Flux
@@ -723,6 +750,12 @@ export class PerspectiveProxy {
723
750
  /**
724
751
  * Adds a pre-signed LinkExpression to the perspective.
725
752
  *
753
+ * The executor checks the signature against `link.author` and stores the
754
+ * verdict as `proof.valid`. If the same link (author, source, predicate,
755
+ * target and timestamp) is already stored with a signature that verifies,
756
+ * its stored proof is kept. The expression passed here is still returned
757
+ * and, when Shared, committed to the neighbourhood as given.
758
+ *
726
759
  * @param link - The signed LinkExpression to add
727
760
  * @param status - Whether the link should be shared
728
761
  * @param batchId - Optional batch ID to group this operation with others
@@ -1351,16 +1384,11 @@ export class PerspectiveProxy {
1351
1384
  async stringOrTemplateObjectToSubjectClassName(subjectClass) {
1352
1385
  if (typeof subjectClass === "string")
1353
1386
  return subjectClass;
1354
- else {
1355
- let subjectClasses = await this.subjectClassesByTemplate(subjectClass);
1356
- if (subjectClasses[0]) {
1357
- return subjectClasses[0];
1358
- }
1359
- else {
1360
- //@ts-ignore
1361
- return subjectClass.className;
1362
- }
1363
- }
1387
+ // The @Model decorator names the class, as in createSubject: no lookup.
1388
+ // Only an undecorated object is matched by its properties.
1389
+ const obj = subjectClass;
1390
+ return obj.className || obj.constructor?.className || obj.constructor?.prototype?.className
1391
+ || (await this.subjectClassesByTemplate(obj))[0];
1364
1392
  }
1365
1393
  /**
1366
1394
  * Creates a new subject instance of the given subject class
@@ -2029,7 +2057,15 @@ export class PerspectiveProxy {
2029
2057
  * refuses a Prolog query (400): Prolog live queries are not supported. */
2030
2058
  async subscribeQuery(query) {
2031
2059
  const subscription = new QuerySubscriptionProxy(this.uuid, query, __classPrivateFieldGet(this, _PerspectiveProxy_client, "f"));
2032
- await subscription.subscribe();
2060
+ try {
2061
+ await subscription.subscribe();
2062
+ }
2063
+ catch (e) {
2064
+ // Nobody gets the proxy, so nobody can dispose it: left as is, it
2065
+ // would re-open on every reconnect and retry for good (#1595).
2066
+ subscription.dispose({ cancelOpening: true });
2067
+ throw e;
2068
+ }
2033
2069
  return subscription;
2034
2070
  }
2035
2071
  }
@@ -22,6 +22,10 @@ import { Ad4mModel } from "../model/Ad4mModel";
22
22
  * reads it by its URI, `ad4m://TextContent`, so a perspective never stores it
23
23
  * and an app class named `TextContent` does not replace it. `register()` on
24
24
  * it writes nothing.
25
+ *
26
+ * The waker's mention subscription (`get_mention_waker_config`) reads it for
27
+ * the agent's names in the text. Mention links it reads through
28
+ * {@link Mentioning}, with text or without.
25
29
  */
26
30
  export declare class TextContent extends Ad4mModel {
27
31
  /** The URI the executor reads it by. */
@@ -32,6 +32,10 @@ import { Model, Property } from "../model/decorators";
32
32
  * reads it by its URI, `ad4m://TextContent`, so a perspective never stores it
33
33
  * and an app class named `TextContent` does not replace it. `register()` on
34
34
  * it writes nothing.
35
+ *
36
+ * The waker's mention subscription (`get_mention_waker_config`) reads it for
37
+ * the agent's names in the text. Mention links it reads through
38
+ * {@link Mentioning}, with text or without.
35
39
  */
36
40
  let TextContent = class TextContent extends Ad4mModel {
37
41
  constructor() {
@@ -14,21 +14,35 @@ export interface WakerSubscription {
14
14
  /** SPARQL, or with `className` a model query (JSON) over that class. */
15
15
  query: string;
16
16
  /**
17
- * The class `query` reads, as a model query. A mention subscription has
18
- * one, from the executor's `get_mention_waker_config`: the built-in
19
- * `ad4m://TextContent`; a children subscription has the built-in
20
- * `ad4m://Container`, from `generate_waker_query` (#1446). Without it
21
- * `query` is SPARQL.
17
+ * The class `query` reads, as a model query. A mention subscription has the
18
+ * built-in `ad4m://TextContent`, from the executor's `get_mention_waker_config`;
19
+ * a children subscription the built-in `ad4m://Container`, from
20
+ * `generate_waker_query` (#1446). Without it `query` is SPARQL.
22
21
  */
23
22
  className?: string;
24
23
  /**
25
24
  * A mention subscription's terms (profile names and the DID), from
26
- * `get_mention_waker_config`. The query matches substrings, so a record
27
- * wakes only when its text holds one of these as a whole word
28
- * ({@link holdsAWholeWordTerm}); without them a mention subscription is
29
- * refused.
25
+ * `get_mention_waker_config`. The text query matches by substring, so a
26
+ * record found through its text wakes only when the text holds one of
27
+ * these as a whole word ({@link holdsAWholeWordTerm}).
30
28
  */
31
29
  terms?: string[];
30
+ /**
31
+ * A mention subscription's agent DID, from `get_mention_waker_config`. A
32
+ * record whose `mentions` links it, in a verified link another agent wrote,
33
+ * wakes whatever its text says ({@link mentionOf}).
34
+ */
35
+ did?: string;
36
+ /**
37
+ * A mention subscription's second query, a model query (JSON) over
38
+ * `mentionClass`, from `get_mention_waker_config`: every record whose
39
+ * `mentions` relation links the agent's DID, with text or without (a WE
40
+ * post's root). It runs beside `query` under the same id, so a record both
41
+ * find wakes once, through the query that reports it first.
42
+ */
43
+ mentionQuery?: string;
44
+ /** The class `mentionQuery` reads: the built-in `ad4m://Mentioning`. */
45
+ mentionClass?: string;
32
46
  neighbourhood?: string;
33
47
  }
34
48
  /**
@@ -53,7 +67,9 @@ export declare const MENTION_TEXT_LIMIT = 16384;
53
67
  * is how a mention by DID is found when the DID is not in the visible text.
54
68
  *
55
69
  * The mention query's `contains` matches substrings (model query has no word
56
- * match); this is the check that keeps "data" from waking on "metadata".
70
+ * match); this is the check that keeps "data" from waking on "metadata" when
71
+ * a record is found through its text alone ({@link mentionOf}).
72
+ *
57
73
  * It reads the first {@link MENTION_TEXT_LIMIT} characters only.
58
74
  */
59
75
  export declare function holdsAWholeWordTerm(text: string, terms: string[]): boolean;
@@ -73,7 +89,48 @@ export interface MentionMessage {
73
89
  * parents have none, or the walk could not be made.
74
90
  */
75
91
  ancestors: string[];
92
+ /**
93
+ * The DID that signed the link of the path that woke the agent (`via`): the mention link to
94
+ * its DID, or the text link whose own text names it. Only that link is theirs; the record's
95
+ * other links may be someone else's.
96
+ */
97
+ author?: string;
98
+ /** That link's timestamp, ISO 8601. */
99
+ timestamp?: string;
100
+ /**
101
+ * Whether that link's signature verified for `author`. A mention is only taken from a link
102
+ * that verified, so a wake's mention is `true`.
103
+ */
104
+ verified: boolean;
105
+ /**
106
+ * The query that reported the record first: `"mentions"`, a mention link to the agent's DID
107
+ * (Mentioning's `mentions`); `"text"`, its name or DID as a whole word in the text (a mention
108
+ * link may also exist). A text match is the agent's name used as a word, which need not
109
+ * address it ("the data shows" for an agent named Data).
110
+ */
111
+ via?: "mentions" | "text";
76
112
  }
113
+ /** What {@link mentionOf} finds about a mention: how it was made, and the provenance of its link. */
114
+ type MentionProvenance = Pick<MentionMessage, "author" | "timestamp" | "verified" | "via">;
115
+ /**
116
+ * Whether a row of one of the mention subscription's two model queries mentions the
117
+ * subscription's agent, and the provenance of the link it does so in; `null` when it does not.
118
+ *
119
+ * - A row of the query over Mentioning: a verified link to the agent's DID that another agent
120
+ * wrote, in the row's `__links.mentions`. It wakes whatever the record's text says, or
121
+ * whether it has any: WE's chip label may run into the next word ("@Datai have…"), and a WE
122
+ * post's mention sits on its root, which has no text. Its provenance is that link's (the
123
+ * newest such).
124
+ * - A row of the query over TextContent: the query matched a substring, so the text must hold
125
+ * a term as a whole word ({@link holdsAWholeWordTerm}), and so must the text of a verified
126
+ * link another agent wrote, in `__links.text`. Its provenance is that link's (the newest
127
+ * such). The row's `text` is the newest text link's, whoever wrote it, so it does not say
128
+ * whose words they are.
129
+ *
130
+ * `via` says which it was. A record both queries find wakes once, through the query that
131
+ * reports it first ({@link WakerSubscriptionManager}).
132
+ */
133
+ export declare function mentionOf(row: any, sub: Pick<WakerSubscription, "did" | "terms">): MentionProvenance | null;
77
134
  export interface WakerLogger {
78
135
  info(msg: string): void;
79
136
  warn(msg: string): void;
@@ -107,8 +164,11 @@ export interface WakerSubscriptionManagerOptions {
107
164
  /** Optional: provide QuerySubscriptionProxy class directly (avoids require("@coasys/ad4m") at runtime). */
108
165
  QuerySubscriptionProxy?: any;
109
166
  /** How long to wait before re-attempting a subscription the executor rejected
110
- * (default 30000). 0 disables re-attempts. */
167
+ * (default 30000). 0 disables re-attempts. Each re-attempt round that still
168
+ * leaves something pending doubles the wait, up to `maxRetryPendingMs`. */
111
169
  retryPendingMs?: number;
170
+ /** Longest wait between two re-attempt rounds (default 300000). */
171
+ maxRetryPendingMs?: number;
112
172
  /**
113
173
  * How long the executor gets to answer the subscribe handshake before the
114
174
  * attempt is abandoned and queued for re-attempt (default 15000). 0 removes
@@ -140,11 +200,24 @@ export declare class WakerSubscriptionManager {
140
200
  private retryPendingMs;
141
201
  private subscribeTimeoutMs;
142
202
  private retryWakeMs;
203
+ /** Per subscription its proxies: one, or a mention subscription's text and mention queries. */
143
204
  private proxies;
144
205
  private activeSubscriptions;
145
206
  /** Subscriptions the executor rejected, waiting to be re-attempted. */
146
207
  private pendingSubscriptions;
147
208
  private retryTimer;
209
+ private maxRetryPendingMs;
210
+ /** Re-attempt rounds in a row that left something pending, for the backoff. */
211
+ private retryRounds;
212
+ /**
213
+ * Subscriptions that were active until one of their live queries lost its
214
+ * executor subscription (a reconnect, a failed resync) and failed to open it
215
+ * again, with the proxies still re-opening. The query retries on its own,
216
+ * with backoff, so the manager does not subscribe them again; it reports
217
+ * them as pending instead of active until every proxy is open again, and
218
+ * keeps persisting them so a restart restores them (#1595).
219
+ */
220
+ private reopening;
148
221
  /**
149
222
  * Cancellation tokens for in-flight `subscribe()` calls.
150
223
  *
@@ -185,6 +258,19 @@ export declare class WakerSubscriptionManager {
185
258
  * If a subscription with the same id already exists, it is disposed first.
186
259
  */
187
260
  subscribe(sub: WakerSubscription): Promise<void>;
261
+ /**
262
+ * A proxy of `sub` failed to re-open its live query, or re-opened it after
263
+ * failing. `sub` counts as active again once none of its proxies is still
264
+ * re-opening. `proxies` tells a status of a replaced subscription apart.
265
+ */
266
+ private onReopenStatus;
267
+ /** The wait before the next re-attempt round: `retryPendingMs` doubled per
268
+ * round in a row that left something pending, capped at
269
+ * `maxRetryPendingMs`, and between half and all of that, so wakers of a
270
+ * restarted executor do not all retry at once. */
271
+ private nextRetryDelay;
272
+ /** The longest the next re-attempt round waits. */
273
+ private retryCeiling;
188
274
  /** Arm the re-attempt timer if pending subscriptions are waiting. */
189
275
  private scheduleRetry;
190
276
  /**
@@ -194,13 +280,18 @@ export declare class WakerSubscriptionManager {
194
280
  * the executor can accept the query.
195
281
  */
196
282
  retryPending(): Promise<void>;
197
- /** Subscriptions that were rejected and are waiting to be re-attempted. */
283
+ /** Subscriptions that are not listening and are being re-attempted: the
284
+ * ones the executor rejected, and active ones whose live query is
285
+ * re-opening after a reconnect. */
198
286
  getPending(): WakerSubscription[];
199
287
  /**
200
288
  * Dispose a single subscription.
201
289
  * @param persist — if false, skip calling onPersist (used during batch cleanup).
202
290
  */
203
291
  dispose(id: string, persist?: boolean): void;
292
+ /** Drop everything held for `id`, as `dispose()` does, but leave the
293
+ * re-attempt backoff as it is. */
294
+ private release;
204
295
  /** (Re)start the timer that offers `sub`'s undelivered mentions to `onWake` after `delayMs`. */
205
296
  private scheduleMentionWake;
206
297
  /**
@@ -232,3 +323,4 @@ export declare class WakerSubscriptionManager {
232
323
  private containers;
233
324
  private persist;
234
325
  }
326
+ export {};