@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.
- package/lib/index.cjs +807 -275
- package/lib/index.js +804 -276
- package/lib/src/Ad4mClient.d.ts +6 -0
- package/lib/src/Ad4mClient.js +8 -0
- package/lib/src/apiClient.d.ts +32 -0
- package/lib/src/apiClient.js +132 -13
- package/lib/src/generated/api/AgentMessage.d.ts +10 -0
- package/lib/src/generated/api/AgentMessage.js +2 -0
- package/lib/src/generated/api/AgentReply.d.ts +9 -0
- package/lib/src/generated/api/AgentReply.js +2 -0
- package/lib/src/generated/api/RpcMethods.d.ts +6 -0
- package/lib/src/generated/api/RpcMethods.js +1 -0
- package/lib/src/generated/api/RunAgentRequest.d.ts +26 -0
- package/lib/src/generated/api/RunAgentRequest.js +1 -0
- package/lib/src/generated/api/index.d.ts +3 -0
- package/lib/src/index.d.ts +1 -0
- package/lib/src/index.js +1 -0
- package/lib/src/model/Ad4mModel.d.ts +7 -0
- package/lib/src/model/Ad4mModel.js +16 -13
- package/lib/src/model/ModelQueryBuilder.d.ts +2 -0
- package/lib/src/model/ModelQueryBuilder.js +36 -57
- package/lib/src/model/types.d.ts +6 -0
- package/lib/src/neighbourhood/SfuManager.d.ts +15 -0
- package/lib/src/neighbourhood/SfuManager.js +39 -2
- package/lib/src/perspectives/LiveQuery.d.ts +40 -4
- package/lib/src/perspectives/LiveQuery.js +94 -10
- package/lib/src/perspectives/Mentioning.d.ts +37 -0
- package/lib/src/perspectives/Mentioning.js +58 -0
- package/lib/src/perspectives/PerspectiveClient.d.ts +26 -2
- package/lib/src/perspectives/PerspectiveClient.js +19 -4
- package/lib/src/perspectives/PerspectiveProxy.d.ts +34 -3
- package/lib/src/perspectives/PerspectiveProxy.js +52 -16
- package/lib/src/perspectives/TextContent.d.ts +4 -0
- package/lib/src/perspectives/TextContent.js +4 -0
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +104 -12
- package/lib/src/perspectives/WakerSubscriptionManager.js +252 -66
- package/package.json +2 -2
- package/src/Ad4mClient.ts +9 -0
- package/src/apiClient.test.ts +467 -3
- package/src/apiClient.ts +133 -13
- package/src/generated/api/AgentMessage.ts +10 -0
- package/src/generated/api/AgentReply.ts +10 -0
- package/src/generated/api/RpcMethods.ts +4 -0
- package/src/generated/api/RunAgentRequest.ts +26 -0
- package/src/generated/api/index.ts +3 -0
- package/src/index.ts +1 -0
- package/src/model/Ad4mModel.test.ts +128 -364
- package/src/model/Ad4mModel.ts +16 -17
- package/src/model/ModelQueryBuilder.ts +39 -59
- package/src/model/types.ts +6 -0
- package/src/model/write-round-trips.test.ts +215 -0
- package/src/neighbourhood/SfuManager.test.ts +151 -2
- package/src/neighbourhood/SfuManager.ts +38 -1
- package/src/perspectives/LiveQuery.test.ts +173 -1
- package/src/perspectives/LiveQuery.ts +110 -10
- package/src/perspectives/Mentioning.test.ts +78 -0
- package/src/perspectives/Mentioning.ts +42 -0
- package/src/perspectives/PerspectiveClient.ts +36 -4
- package/src/perspectives/PerspectiveProxy.test.ts +24 -2
- package/src/perspectives/PerspectiveProxy.ts +61 -16
- package/src/perspectives/TextContent.ts +4 -0
- package/src/perspectives/WakerSubscriptionManager.test.ts +608 -152
- 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
|
-
|
|
94
|
-
|
|
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
|
-
|
|
128
|
-
|
|
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
|
-
/**
|
|
51
|
-
|
|
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
|
-
/**
|
|
99
|
-
|
|
100
|
-
|
|
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
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
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
|
-
|
|
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
|
-
*
|
|
19
|
-
*
|
|
20
|
-
* `
|
|
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
|
|
27
|
-
* wakes only when
|
|
28
|
-
* ({@link holdsAWholeWordTerm})
|
|
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
|
|
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 {};
|