@coasys/ad4m 0.13.0-test-model-layer → 0.13.0-test-inverse-relations
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 +432 -46
- package/lib/index.js +430 -47
- package/lib/src/ai/AIClient.d.ts +13 -0
- package/lib/src/ai/AIClient.js +15 -0
- package/lib/src/model/Ad4mModel.js +14 -6
- package/lib/src/model/ModelQueryBuilder.js +13 -3
- package/lib/src/model/query-common.d.ts +10 -1
- package/lib/src/model/query-common.js +16 -0
- package/lib/src/model/query-sparql.js +25 -1
- package/lib/src/model/shacl-gen.js +12 -0
- package/lib/src/model/types.d.ts +91 -1
- package/lib/src/model/types.js +9 -0
- package/lib/src/perspectives/AutoProcessor.d.ts +8 -0
- package/lib/src/perspectives/FlowInstance.d.ts +30 -12
- package/lib/src/perspectives/FlowInstance.js +36 -13
- package/lib/src/perspectives/FlowModels.d.ts +7 -1
- package/lib/src/perspectives/FlowModels.js +8 -2
- package/lib/src/perspectives/PerspectiveClient.d.ts +16 -0
- package/lib/src/perspectives/PerspectiveClient.js +12 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +31 -3
- package/lib/src/perspectives/PerspectiveProxy.js +78 -2
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +55 -5
- package/lib/src/perspectives/WakerSubscriptionManager.js +183 -8
- package/package.json +1 -1
- package/src/ai/AIClient.ts +16 -0
- package/src/model/Ad4mModel.test.ts +79 -0
- package/src/model/Ad4mModel.ts +14 -6
- package/src/model/ModelQueryBuilder.ts +13 -3
- package/src/model/query-common.ts +20 -1
- package/src/model/query-sparql.ts +28 -1
- package/src/model/shacl-gen.ts +12 -0
- package/src/model/shacl-roundtrip.test.ts +71 -0
- package/src/model/types.ts +96 -1
- package/src/perspectives/AutoProcessor.ts +8 -0
- package/src/perspectives/FlowInstance.ts +39 -13
- package/src/perspectives/FlowModels.ts +8 -2
- package/src/perspectives/PerspectiveClient.ts +28 -0
- package/src/perspectives/PerspectiveProxy.test.ts +154 -0
- package/src/perspectives/PerspectiveProxy.ts +84 -5
- package/src/perspectives/WakerSubscriptionManager.test.ts +199 -0
- package/src/perspectives/WakerSubscriptionManager.ts +197 -9
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { LinkCallback, PerspectiveClient, SyncStateChangeCallback } from "./PerspectiveClient";
|
|
1
|
+
import { LinkCallback, PerspectiveClient, SyncStateChangeCallback, FlowFireOutcome } from "./PerspectiveClient";
|
|
2
2
|
import { CallOptions } from "../apiClient";
|
|
3
3
|
import { Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkMutations } from "../links/Links";
|
|
4
4
|
import { LinkQuery } from "./LinkQuery";
|
|
@@ -357,6 +357,9 @@ export declare class PerspectiveProxy {
|
|
|
357
357
|
* rejected `update` drops the overlay and keeps the real value.
|
|
358
358
|
*/
|
|
359
359
|
rejectInterpretation(base: string, property?: string): Promise<boolean>;
|
|
360
|
+
acceptFlowProposal(proposalUri: string): Promise<FlowFireOutcome[]>;
|
|
361
|
+
/** Withdraw our own links from a proposal; resolves to how many went. */
|
|
362
|
+
rejectFlowProposal(proposalUri: string): Promise<number>;
|
|
360
363
|
/** Subscribe to this perspective's auto-processor step signals. */
|
|
361
364
|
addAutoProcessorEventListener(cb: (event: AutoProcessorEvent) => void): Promise<void>;
|
|
362
365
|
/**
|
|
@@ -562,10 +565,18 @@ export declare class PerspectiveProxy {
|
|
|
562
565
|
/**
|
|
563
566
|
* Removes a link from the perspective.
|
|
564
567
|
*
|
|
565
|
-
*
|
|
568
|
+
* Accepts either a full `LinkExpressionInput` (as returned by `add`) or a bare
|
|
569
|
+
* `Link` (source/predicate/target only). When a bare Link is passed the method
|
|
570
|
+
* resolves it to the first stored `LinkExpression` whose source, predicate, and
|
|
571
|
+
* target match, then removes that expression. A bare Link without a predicate
|
|
572
|
+
* (or with the constructor's `""` stand-in) matches only stored links that
|
|
573
|
+
* themselves have no predicate. If no match is found an error is thrown
|
|
574
|
+
* naming the link so the caller knows what was expected.
|
|
575
|
+
*
|
|
576
|
+
* @param link - The link to remove (LinkExpressionInput or bare Link)
|
|
566
577
|
* @param batchId - Optional batch ID to group this operation with others
|
|
567
578
|
*/
|
|
568
|
-
remove(link: LinkExpressionInput, batchId?: string): Promise<boolean>;
|
|
579
|
+
remove(link: LinkExpressionInput | Link, batchId?: string): Promise<boolean>;
|
|
569
580
|
/** Creates a new batch for grouping operations */
|
|
570
581
|
createBatch(): Promise<string>;
|
|
571
582
|
/** Commits a batch of operations */
|
|
@@ -852,6 +863,23 @@ export declare class PerspectiveProxy {
|
|
|
852
863
|
* Uses SHACL-based lookup (Prolog-free implementation).
|
|
853
864
|
*/
|
|
854
865
|
subjectClasses(): Promise<string[]>;
|
|
866
|
+
/**
|
|
867
|
+
* Return the full target-class URIs of every registered SubjectClass.
|
|
868
|
+
*
|
|
869
|
+
* Unlike {@link subjectClasses}, which strips the namespace and returns bare
|
|
870
|
+
* names (`"Space"`, `"Channel"`), this method returns the complete URIs
|
|
871
|
+
* (`"we://Space"`, `"flux://Channel"`). The full URI is the key that
|
|
872
|
+
* `load_shape` resolves against, so it is the only collision-safe identifier
|
|
873
|
+
* — two apps can both declare a class called `"Template"` under different
|
|
874
|
+
* namespaces, and the bare name cannot distinguish them.
|
|
875
|
+
*
|
|
876
|
+
* Callers that need to check whether a *set* of models are already
|
|
877
|
+
* registered should call this once and test membership against the returned
|
|
878
|
+
* set, rather than issuing one `queryLinks` per model.
|
|
879
|
+
*
|
|
880
|
+
* One `queryLinks` round trip, no executor-side changes.
|
|
881
|
+
*/
|
|
882
|
+
subjectClassTargetClasses(): Promise<string[]>;
|
|
855
883
|
stringOrTemplateObjectToSubjectClassName<T>(subjectClass: T): Promise<string>;
|
|
856
884
|
/**
|
|
857
885
|
* Creates a new subject instance of the given subject class
|
|
@@ -742,6 +742,13 @@ export class PerspectiveProxy {
|
|
|
742
742
|
async rejectInterpretation(base, property) {
|
|
743
743
|
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").rejectInterpretation(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, base, property);
|
|
744
744
|
}
|
|
745
|
+
async acceptFlowProposal(proposalUri) {
|
|
746
|
+
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").acceptFlowProposal(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, proposalUri);
|
|
747
|
+
}
|
|
748
|
+
/** Withdraw our own links from a proposal; resolves to how many went. */
|
|
749
|
+
async rejectFlowProposal(proposalUri) {
|
|
750
|
+
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").rejectFlowProposal(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, proposalUri);
|
|
751
|
+
}
|
|
745
752
|
/** Subscribe to this perspective's auto-processor step signals. */
|
|
746
753
|
async addAutoProcessorEventListener(cb) {
|
|
747
754
|
return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").addAutoProcessorEventListener(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, cb);
|
|
@@ -986,11 +993,48 @@ export class PerspectiveProxy {
|
|
|
986
993
|
/**
|
|
987
994
|
* Removes a link from the perspective.
|
|
988
995
|
*
|
|
989
|
-
*
|
|
996
|
+
* Accepts either a full `LinkExpressionInput` (as returned by `add`) or a bare
|
|
997
|
+
* `Link` (source/predicate/target only). When a bare Link is passed the method
|
|
998
|
+
* resolves it to the first stored `LinkExpression` whose source, predicate, and
|
|
999
|
+
* target match, then removes that expression. A bare Link without a predicate
|
|
1000
|
+
* (or with the constructor's `""` stand-in) matches only stored links that
|
|
1001
|
+
* themselves have no predicate. If no match is found an error is thrown
|
|
1002
|
+
* naming the link so the caller knows what was expected.
|
|
1003
|
+
*
|
|
1004
|
+
* @param link - The link to remove (LinkExpressionInput or bare Link)
|
|
990
1005
|
* @param batchId - Optional batch ID to group this operation with others
|
|
991
1006
|
*/
|
|
992
1007
|
async remove(link, batchId) {
|
|
993
|
-
|
|
1008
|
+
let resolvedLink;
|
|
1009
|
+
if (!('data' in link) || link.data === undefined) {
|
|
1010
|
+
// bare Link — resolve to stored expression
|
|
1011
|
+
const bare = link;
|
|
1012
|
+
// The Link constructor coerces an absent predicate to "" and the
|
|
1013
|
+
// store reports predicate-less links as predicate null — so ""
|
|
1014
|
+
// and undefined both mean "no predicate" here, and neither may
|
|
1015
|
+
// widen the query: dropping the filter would resolve (and
|
|
1016
|
+
// remove!) an arbitrary source→target link under a *different*
|
|
1017
|
+
// predicate. LinkQuery cannot express "predicate is absent", so
|
|
1018
|
+
// in that case we query on source/target only and require the
|
|
1019
|
+
// absence ourselves.
|
|
1020
|
+
const predicateGiven = bare.predicate !== undefined && bare.predicate !== '';
|
|
1021
|
+
const candidates = await this.get(new LinkQuery({
|
|
1022
|
+
source: bare.source || undefined,
|
|
1023
|
+
predicate: predicateGiven ? bare.predicate : undefined,
|
|
1024
|
+
target: bare.target || undefined,
|
|
1025
|
+
}));
|
|
1026
|
+
const matches = predicateGiven
|
|
1027
|
+
? candidates
|
|
1028
|
+
: candidates.filter(m => !m.data.predicate);
|
|
1029
|
+
if (matches.length === 0) {
|
|
1030
|
+
throw new Error(`PerspectiveProxy.remove: no stored LinkExpression matches Link { source: "${bare.source}", predicate: "${bare.predicate}", target: "${bare.target}" }`);
|
|
1031
|
+
}
|
|
1032
|
+
resolvedLink = matches[0];
|
|
1033
|
+
}
|
|
1034
|
+
else {
|
|
1035
|
+
resolvedLink = link;
|
|
1036
|
+
}
|
|
1037
|
+
const result = await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").removeLink(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, resolvedLink, batchId);
|
|
994
1038
|
invalidatePerspectiveCache(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
|
|
995
1039
|
return result;
|
|
996
1040
|
}
|
|
@@ -1578,6 +1622,38 @@ export class PerspectiveProxy {
|
|
|
1578
1622
|
return [];
|
|
1579
1623
|
}
|
|
1580
1624
|
}
|
|
1625
|
+
/**
|
|
1626
|
+
* Return the full target-class URIs of every registered SubjectClass.
|
|
1627
|
+
*
|
|
1628
|
+
* Unlike {@link subjectClasses}, which strips the namespace and returns bare
|
|
1629
|
+
* names (`"Space"`, `"Channel"`), this method returns the complete URIs
|
|
1630
|
+
* (`"we://Space"`, `"flux://Channel"`). The full URI is the key that
|
|
1631
|
+
* `load_shape` resolves against, so it is the only collision-safe identifier
|
|
1632
|
+
* — two apps can both declare a class called `"Template"` under different
|
|
1633
|
+
* namespaces, and the bare name cannot distinguish them.
|
|
1634
|
+
*
|
|
1635
|
+
* Callers that need to check whether a *set* of models are already
|
|
1636
|
+
* registered should call this once and test membership against the returned
|
|
1637
|
+
* set, rather than issuing one `queryLinks` per model.
|
|
1638
|
+
*
|
|
1639
|
+
* One `queryLinks` round trip, no executor-side changes.
|
|
1640
|
+
*/
|
|
1641
|
+
async subjectClassTargetClasses() {
|
|
1642
|
+
try {
|
|
1643
|
+
const classLinks = await this.get(new LinkQuery({
|
|
1644
|
+
predicate: "rdf://type",
|
|
1645
|
+
target: "ad4m://SubjectClass"
|
|
1646
|
+
}));
|
|
1647
|
+
const uris = classLinks
|
|
1648
|
+
.map(l => l.data.source)
|
|
1649
|
+
.filter(source => source.length > 0);
|
|
1650
|
+
return [...new Set(uris)];
|
|
1651
|
+
}
|
|
1652
|
+
catch (e) {
|
|
1653
|
+
console.warn('subjectClassTargetClasses: lookup failed:', e);
|
|
1654
|
+
return [];
|
|
1655
|
+
}
|
|
1656
|
+
}
|
|
1581
1657
|
async stringOrTemplateObjectToSubjectClassName(subjectClass) {
|
|
1582
1658
|
if (typeof subjectClass === "string")
|
|
1583
1659
|
return subjectClass;
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* WakerSubscriptionManager — manages live query subscriptions for the waker.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
4
|
+
* This is the single implementation: it is exported from `@coasys/ad4m` and
|
|
5
|
+
* used by the integration tests, and the OpenClaw AD4M plugin re-exports this
|
|
6
|
+
* module (`plugins/ad4m/wakerSubscriptionManager.ts`) rather than carrying its
|
|
7
|
+
* own copy. Any behaviour change belongs here.
|
|
8
8
|
*/
|
|
9
9
|
export interface WakerSubscription {
|
|
10
10
|
id: string;
|
|
@@ -43,7 +43,25 @@ export interface WakerSubscriptionManagerOptions {
|
|
|
43
43
|
previousSeenMessages?: Record<string, string[]>;
|
|
44
44
|
/** Optional: provide QuerySubscriptionProxy class directly (avoids require("@coasys/ad4m") at runtime). */
|
|
45
45
|
QuerySubscriptionProxy?: any;
|
|
46
|
+
/** How long to wait before re-attempting a subscription the executor rejected
|
|
47
|
+
* (default 30000). 0 disables re-attempts. */
|
|
48
|
+
retryPendingMs?: number;
|
|
49
|
+
/**
|
|
50
|
+
* How long the executor gets to answer the subscribe handshake before the
|
|
51
|
+
* attempt is abandoned and queued for re-attempt (default 15000). 0 removes
|
|
52
|
+
* the bound. Covers both `proxy.subscribe()` and `proxy.initialized`: when
|
|
53
|
+
* the executor accepts the socket but never answers, neither settles, and
|
|
54
|
+
* without a deadline the subscription ended up neither active nor pending,
|
|
55
|
+
* so the re-attempt cycle never saw it (#1016).
|
|
56
|
+
*/
|
|
57
|
+
subscribeTimeoutMs?: number;
|
|
46
58
|
}
|
|
59
|
+
/**
|
|
60
|
+
* Add a short cause hint to known subscription failures.
|
|
61
|
+
* The executor needs its main key to register a live query; on a restarted
|
|
62
|
+
* executor whose wallet was never unlocked this surfaces as a bare 403.
|
|
63
|
+
*/
|
|
64
|
+
export declare function hintFor(msg: string): string;
|
|
47
65
|
export declare class WakerSubscriptionManager {
|
|
48
66
|
private perspectiveClient;
|
|
49
67
|
private logger;
|
|
@@ -52,24 +70,56 @@ export declare class WakerSubscriptionManager {
|
|
|
52
70
|
private onPersist?;
|
|
53
71
|
private QuerySubscriptionProxyCtor;
|
|
54
72
|
private previousSeenMessages;
|
|
73
|
+
private retryPendingMs;
|
|
74
|
+
private subscribeTimeoutMs;
|
|
55
75
|
private proxies;
|
|
56
76
|
private activeSubscriptions;
|
|
77
|
+
/** Subscriptions the executor rejected, waiting to be re-attempted. */
|
|
78
|
+
private pendingSubscriptions;
|
|
79
|
+
private retryTimer;
|
|
80
|
+
/**
|
|
81
|
+
* Cancellation tokens for in-flight `subscribe()` calls.
|
|
82
|
+
*
|
|
83
|
+
* `subscribe()` awaits `proxy.subscribe()` and `proxy.initialized`; a
|
|
84
|
+
* `dispose()` / `disposeAll()` landing during either await used to leave a
|
|
85
|
+
* live subscription behind, because nothing stopped the resumed call from
|
|
86
|
+
* registering the proxy in `proxies` / `activeSubscriptions` afterwards.
|
|
87
|
+
* `epoch` is bumped by `disposeAll()` (which cannot enumerate in-flight
|
|
88
|
+
* ids), `generations` per id by `dispose()` and by each new `subscribe()`.
|
|
89
|
+
*/
|
|
90
|
+
private epoch;
|
|
91
|
+
private generations;
|
|
57
92
|
private debounceTimers;
|
|
58
93
|
/** Per-subscription set of already-processed message addresses (for mention subs)
|
|
59
94
|
* or serialized result hash (for channel-messages subs). */
|
|
60
95
|
private seenMessages;
|
|
61
96
|
constructor(options: WakerSubscriptionManagerOptions);
|
|
97
|
+
/** A token identifying this attempt at subscribing `id`. */
|
|
98
|
+
private beginAttempt;
|
|
99
|
+
/** Whether this attempt has been superseded by a dispose or a newer one. */
|
|
100
|
+
private isStale;
|
|
62
101
|
/**
|
|
63
102
|
* Create a live SPARQL subscription.
|
|
64
103
|
* If a subscription with the same id already exists, it is disposed first.
|
|
65
104
|
*/
|
|
66
105
|
subscribe(sub: WakerSubscription): Promise<void>;
|
|
106
|
+
/** Arm the re-attempt timer if pending subscriptions are waiting. */
|
|
107
|
+
private scheduleRetry;
|
|
108
|
+
/**
|
|
109
|
+
* Re-attempt every subscription the executor rejected.
|
|
110
|
+
* Each attempt that fails puts itself back into the pending set and re-arms
|
|
111
|
+
* the timer, so an agent that asked to be subscribed ends up enrolled once
|
|
112
|
+
* the executor can accept the query.
|
|
113
|
+
*/
|
|
114
|
+
retryPending(): Promise<void>;
|
|
115
|
+
/** Subscriptions that were rejected and are waiting to be re-attempted. */
|
|
116
|
+
getPending(): WakerSubscription[];
|
|
67
117
|
/**
|
|
68
118
|
* Dispose a single subscription.
|
|
69
119
|
* @param persist — if false, skip calling onPersist (used during batch cleanup).
|
|
70
120
|
*/
|
|
71
121
|
dispose(id: string, persist?: boolean): void;
|
|
72
|
-
/** Dispose all active subscriptions. */
|
|
122
|
+
/** Dispose all active subscriptions and drop anything still pending. */
|
|
73
123
|
disposeAll(): void;
|
|
74
124
|
/** Get all active subscriptions. */
|
|
75
125
|
getActive(): WakerSubscription[];
|
|
@@ -1,15 +1,73 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* WakerSubscriptionManager — manages live query subscriptions for the waker.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
4
|
+
* This is the single implementation: it is exported from `@coasys/ad4m` and
|
|
5
|
+
* used by the integration tests, and the OpenClaw AD4M plugin re-exports this
|
|
6
|
+
* module (`plugins/ad4m/wakerSubscriptionManager.ts`) rather than carrying its
|
|
7
|
+
* own copy. Any behaviour change belongs here.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Add a short cause hint to known subscription failures.
|
|
11
|
+
* The executor needs its main key to register a live query; on a restarted
|
|
12
|
+
* executor whose wallet was never unlocked this surfaces as a bare 403.
|
|
13
|
+
*/
|
|
14
|
+
export function hintFor(msg) {
|
|
15
|
+
// "Executor is locked" is the current executor's message; "main key not
|
|
16
|
+
// found" is what older executors (and unrelated key lookups) say for the
|
|
17
|
+
// same locked state. Either way the caller cannot fix it themselves: keys
|
|
18
|
+
// live in memory only, so every restart locks the node again and only its
|
|
19
|
+
// operator can unlock it.
|
|
20
|
+
if (/executor is locked/i.test(msg) || /main key not found/i.test(msg)) {
|
|
21
|
+
return " — the executor is locked (its keys live in memory only, so every restart locks it again). Only the node's operator can unlock it: contact them and ask for unlockAgent, then subscribe again — a pending subscription re-attempts on its own once the node is unlocked";
|
|
22
|
+
}
|
|
23
|
+
if (/timed out after \d+ms/i.test(msg)) {
|
|
24
|
+
return " — the executor accepted the waker's connection but never answered; check that the waker is pointed at the right executor host and API port (executorUrl in the plugin config) and that the node is unlocked";
|
|
25
|
+
}
|
|
26
|
+
return "";
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Reject `promise` after `ms` instead of waiting forever.
|
|
6
30
|
*
|
|
7
|
-
*
|
|
31
|
+
* The pending set only catches rejections. A handshake that hangs — the
|
|
32
|
+
* executor accepted the socket but never answers — settles nothing, so the
|
|
33
|
+
* subscription was recorded nowhere and the caller's tool invocation died at
|
|
34
|
+
* the harness timeout instead (#1016). The underlying promise is left as is:
|
|
35
|
+
* the caller disposes the proxy, so a late answer backs out on its own.
|
|
8
36
|
*/
|
|
37
|
+
async function withTimeout(promise, ms, message) {
|
|
38
|
+
let timer;
|
|
39
|
+
try {
|
|
40
|
+
return await Promise.race([
|
|
41
|
+
promise,
|
|
42
|
+
new Promise((_resolve, reject) => {
|
|
43
|
+
timer = setTimeout(() => reject(new Error(message)), ms);
|
|
44
|
+
}),
|
|
45
|
+
]);
|
|
46
|
+
}
|
|
47
|
+
finally {
|
|
48
|
+
if (timer)
|
|
49
|
+
clearTimeout(timer);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
9
52
|
export class WakerSubscriptionManager {
|
|
10
53
|
constructor(options) {
|
|
11
54
|
this.proxies = new Map();
|
|
12
55
|
this.activeSubscriptions = new Map();
|
|
56
|
+
/** Subscriptions the executor rejected, waiting to be re-attempted. */
|
|
57
|
+
this.pendingSubscriptions = new Map();
|
|
58
|
+
this.retryTimer = null;
|
|
59
|
+
/**
|
|
60
|
+
* Cancellation tokens for in-flight `subscribe()` calls.
|
|
61
|
+
*
|
|
62
|
+
* `subscribe()` awaits `proxy.subscribe()` and `proxy.initialized`; a
|
|
63
|
+
* `dispose()` / `disposeAll()` landing during either await used to leave a
|
|
64
|
+
* live subscription behind, because nothing stopped the resumed call from
|
|
65
|
+
* registering the proxy in `proxies` / `activeSubscriptions` afterwards.
|
|
66
|
+
* `epoch` is bumped by `disposeAll()` (which cannot enumerate in-flight
|
|
67
|
+
* ids), `generations` per id by `dispose()` and by each new `subscribe()`.
|
|
68
|
+
*/
|
|
69
|
+
this.epoch = 0;
|
|
70
|
+
this.generations = new Map();
|
|
13
71
|
this.debounceTimers = new Map();
|
|
14
72
|
/** Per-subscription set of already-processed message addresses (for mention subs)
|
|
15
73
|
* or serialized result hash (for channel-messages subs). */
|
|
@@ -21,6 +79,18 @@ export class WakerSubscriptionManager {
|
|
|
21
79
|
this.onPersist = options.onPersist;
|
|
22
80
|
this.QuerySubscriptionProxyCtor = options.QuerySubscriptionProxy ?? null;
|
|
23
81
|
this.previousSeenMessages = options.previousSeenMessages ?? {};
|
|
82
|
+
this.retryPendingMs = options.retryPendingMs ?? 30000;
|
|
83
|
+
this.subscribeTimeoutMs = options.subscribeTimeoutMs ?? 15000;
|
|
84
|
+
}
|
|
85
|
+
/** A token identifying this attempt at subscribing `id`. */
|
|
86
|
+
beginAttempt(id) {
|
|
87
|
+
const gen = (this.generations.get(id) ?? 0) + 1;
|
|
88
|
+
this.generations.set(id, gen);
|
|
89
|
+
return { epoch: this.epoch, gen };
|
|
90
|
+
}
|
|
91
|
+
/** Whether this attempt has been superseded by a dispose or a newer one. */
|
|
92
|
+
isStale(id, token) {
|
|
93
|
+
return token.epoch !== this.epoch || this.generations.get(id) !== token.gen;
|
|
24
94
|
}
|
|
25
95
|
/**
|
|
26
96
|
* Create a live SPARQL subscription.
|
|
@@ -29,6 +99,7 @@ export class WakerSubscriptionManager {
|
|
|
29
99
|
async subscribe(sub) {
|
|
30
100
|
// Dispose existing subscription with same id if any
|
|
31
101
|
this.dispose(sub.id, false);
|
|
102
|
+
const token = this.beginAttempt(sub.id);
|
|
32
103
|
if (!this.QuerySubscriptionProxyCtor) {
|
|
33
104
|
throw new Error("WakerSubscriptionManager: QuerySubscriptionProxy must be provided via constructor options");
|
|
34
105
|
}
|
|
@@ -43,9 +114,24 @@ export class WakerSubscriptionManager {
|
|
|
43
114
|
if (proxy.initialized && typeof proxy.initialized.catch === "function") {
|
|
44
115
|
proxy.initialized.catch(() => { });
|
|
45
116
|
}
|
|
117
|
+
// One deadline for the whole handshake: `proxy.subscribe()` and the
|
|
118
|
+
// `initialized` promise it resolves share the budget, so a hang in either
|
|
119
|
+
// surfaces as the same loud-but-recoverable failure a rejection does.
|
|
120
|
+
const budgetMs = this.subscribeTimeoutMs;
|
|
121
|
+
const startedAt = Date.now();
|
|
122
|
+
const bounded = (step, what) => budgetMs > 0
|
|
123
|
+
? withTimeout(step, Math.max(0, budgetMs - (Date.now() - startedAt)), `${what} timed out after ${budgetMs}ms`)
|
|
124
|
+
: step;
|
|
46
125
|
try {
|
|
47
|
-
await proxy.subscribe();
|
|
48
|
-
|
|
126
|
+
await bounded(proxy.subscribe(), "subscribe handshake");
|
|
127
|
+
if (this.isStale(sub.id, token)) {
|
|
128
|
+
try {
|
|
129
|
+
proxy.dispose();
|
|
130
|
+
}
|
|
131
|
+
catch { }
|
|
132
|
+
return;
|
|
133
|
+
}
|
|
134
|
+
await bounded(proxy.initialized, "subscription initialization");
|
|
49
135
|
}
|
|
50
136
|
catch (err) {
|
|
51
137
|
const msg = err?.message ?? String(err);
|
|
@@ -54,12 +140,36 @@ export class WakerSubscriptionManager {
|
|
|
54
140
|
proxy.dispose();
|
|
55
141
|
}
|
|
56
142
|
catch { }
|
|
57
|
-
//
|
|
143
|
+
// A dispose that landed mid-attempt wins: don't re-queue something the
|
|
144
|
+
// caller has since asked us to forget.
|
|
145
|
+
if (this.isStale(sub.id, token))
|
|
146
|
+
return;
|
|
147
|
+
// Remove from active state — it is not listening, so it must not be
|
|
148
|
+
// reported as active or persisted as if it were.
|
|
58
149
|
this.activeSubscriptions.delete(sub.id);
|
|
59
150
|
this.seenMessages.delete(sub.id);
|
|
60
151
|
this.persist();
|
|
61
|
-
|
|
152
|
+
// Keep it pending and re-attempt: the usual cause (locked wallet, executor
|
|
153
|
+
// mid-restart, a handshake the executor never answered) clears on its
|
|
154
|
+
// own, and the caller asked to be enrolled.
|
|
155
|
+
this.pendingSubscriptions.set(sub.id, sub);
|
|
156
|
+
this.scheduleRetry();
|
|
157
|
+
// Throw so callers can report the real outcome. Background callers
|
|
158
|
+
// (auto-subscribe, restore-on-start) catch and log; the subscribe tools
|
|
159
|
+
// turn this into an error result instead of a false "Subscribed" reply.
|
|
160
|
+
throw new Error(`Waker subscription ${sub.id} failed: ${msg}${hintFor(msg)}` +
|
|
161
|
+
(this.retryPendingMs > 0
|
|
162
|
+
? `. Not listening yet — re-attempting every ${Math.round(this.retryPendingMs / 1000)}s; check ad4m_list_waker_subscriptions.`
|
|
163
|
+
: ""));
|
|
164
|
+
}
|
|
165
|
+
if (this.isStale(sub.id, token)) {
|
|
166
|
+
try {
|
|
167
|
+
proxy.dispose();
|
|
168
|
+
}
|
|
169
|
+
catch { }
|
|
170
|
+
return;
|
|
62
171
|
}
|
|
172
|
+
this.pendingSubscriptions.delete(sub.id);
|
|
63
173
|
this.logger.info(`[waker] ${sub.id}: subscription initialized successfully`);
|
|
64
174
|
// Seed from persisted seen messages so we don't re-wake after restart
|
|
65
175
|
const seen = new Set(this.previousSeenMessages[sub.id] ?? []);
|
|
@@ -140,16 +250,72 @@ export class WakerSubscriptionManager {
|
|
|
140
250
|
}, this.debounceMs));
|
|
141
251
|
}
|
|
142
252
|
});
|
|
253
|
+
if (this.isStale(sub.id, token)) {
|
|
254
|
+
try {
|
|
255
|
+
proxy.dispose();
|
|
256
|
+
}
|
|
257
|
+
catch { }
|
|
258
|
+
return;
|
|
259
|
+
}
|
|
143
260
|
this.proxies.set(sub.id, proxy);
|
|
144
261
|
this.activeSubscriptions.set(sub.id, sub);
|
|
145
262
|
this.persist();
|
|
146
263
|
this.logger.info(`[waker] Subscription ${sub.id} active (type=${sub.type}, perspective=${sub.perspective})`);
|
|
147
264
|
}
|
|
265
|
+
/** Arm the re-attempt timer if pending subscriptions are waiting. */
|
|
266
|
+
scheduleRetry() {
|
|
267
|
+
if (this.retryPendingMs <= 0)
|
|
268
|
+
return;
|
|
269
|
+
if (this.retryTimer || this.pendingSubscriptions.size === 0)
|
|
270
|
+
return;
|
|
271
|
+
this.retryTimer = setTimeout(() => {
|
|
272
|
+
this.retryTimer = null;
|
|
273
|
+
void this.retryPending();
|
|
274
|
+
}, this.retryPendingMs);
|
|
275
|
+
if (typeof this.retryTimer.unref === "function")
|
|
276
|
+
this.retryTimer.unref();
|
|
277
|
+
}
|
|
278
|
+
/**
|
|
279
|
+
* Re-attempt every subscription the executor rejected.
|
|
280
|
+
* Each attempt that fails puts itself back into the pending set and re-arms
|
|
281
|
+
* the timer, so an agent that asked to be subscribed ends up enrolled once
|
|
282
|
+
* the executor can accept the query.
|
|
283
|
+
*/
|
|
284
|
+
async retryPending() {
|
|
285
|
+
const waiting = Array.from(this.pendingSubscriptions.values());
|
|
286
|
+
if (waiting.length === 0)
|
|
287
|
+
return;
|
|
288
|
+
this.logger.info(`[waker] re-attempting ${waiting.length} pending subscription(s)`);
|
|
289
|
+
const epoch = this.epoch;
|
|
290
|
+
for (const sub of waiting) {
|
|
291
|
+
// A disposeAll() between two awaits must stop the whole sweep, and a
|
|
292
|
+
// dispose() of this id must skip just it.
|
|
293
|
+
if (epoch !== this.epoch)
|
|
294
|
+
return;
|
|
295
|
+
if (!this.pendingSubscriptions.has(sub.id))
|
|
296
|
+
continue;
|
|
297
|
+
this.pendingSubscriptions.delete(sub.id);
|
|
298
|
+
try {
|
|
299
|
+
await this.subscribe(sub);
|
|
300
|
+
this.logger.info(`[waker] ${sub.id}: enrolled on re-attempt`);
|
|
301
|
+
}
|
|
302
|
+
catch (err) {
|
|
303
|
+
// subscribe() already logged, re-queued and re-armed the timer.
|
|
304
|
+
this.logger.debug(`[waker] ${sub.id}: still pending — ${err?.message ?? err}`);
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
/** Subscriptions that were rejected and are waiting to be re-attempted. */
|
|
309
|
+
getPending() {
|
|
310
|
+
return Array.from(this.pendingSubscriptions.values());
|
|
311
|
+
}
|
|
148
312
|
/**
|
|
149
313
|
* Dispose a single subscription.
|
|
150
314
|
* @param persist — if false, skip calling onPersist (used during batch cleanup).
|
|
151
315
|
*/
|
|
152
316
|
dispose(id, persist = true) {
|
|
317
|
+
// Invalidate any subscribe() for this id that is still awaiting.
|
|
318
|
+
this.generations.set(id, (this.generations.get(id) ?? 0) + 1);
|
|
153
319
|
const proxy = this.proxies.get(id);
|
|
154
320
|
if (proxy) {
|
|
155
321
|
try {
|
|
@@ -166,15 +332,24 @@ export class WakerSubscriptionManager {
|
|
|
166
332
|
this.debounceTimers.delete(id);
|
|
167
333
|
}
|
|
168
334
|
this.activeSubscriptions.delete(id);
|
|
335
|
+
this.pendingSubscriptions.delete(id);
|
|
169
336
|
this.seenMessages.delete(id);
|
|
170
337
|
if (persist)
|
|
171
338
|
this.persist();
|
|
172
339
|
}
|
|
173
|
-
/** Dispose all active subscriptions. */
|
|
340
|
+
/** Dispose all active subscriptions and drop anything still pending. */
|
|
174
341
|
disposeAll() {
|
|
342
|
+
// Bump the epoch first: in-flight subscribe() calls have no proxy in the
|
|
343
|
+
// map yet, so per-id invalidation alone cannot reach them.
|
|
344
|
+
this.epoch++;
|
|
175
345
|
for (const [id] of this.proxies) {
|
|
176
346
|
this.dispose(id, false);
|
|
177
347
|
}
|
|
348
|
+
this.pendingSubscriptions.clear();
|
|
349
|
+
if (this.retryTimer) {
|
|
350
|
+
clearTimeout(this.retryTimer);
|
|
351
|
+
this.retryTimer = null;
|
|
352
|
+
}
|
|
178
353
|
}
|
|
179
354
|
/** Get all active subscriptions. */
|
|
180
355
|
getActive() {
|
package/package.json
CHANGED
package/src/ai/AIClient.ts
CHANGED
|
@@ -26,6 +26,22 @@ export class AIClient {
|
|
|
26
26
|
return this.#apiClient.call<Model[]>('ai.models');
|
|
27
27
|
}
|
|
28
28
|
|
|
29
|
+
/**
|
|
30
|
+
* Ask a remote endpoint which models it serves, before adding one.
|
|
31
|
+
*
|
|
32
|
+
* Takes the credentials of a model that does not exist yet — a settings
|
|
33
|
+
* form is being filled in and wants the list to pick from. Rejects when
|
|
34
|
+
* the endpoint is unreachable or the key is refused, which makes this the
|
|
35
|
+
* credential check too: without it a bad key surfaces later as a failed
|
|
36
|
+
* completion carrying an error from a different layer.
|
|
37
|
+
*
|
|
38
|
+
* `apiType` defaults to the OpenAI shape, which is what every endpoint
|
|
39
|
+
* that is not Anthropic speaks.
|
|
40
|
+
*/
|
|
41
|
+
async discoverModels(baseUrl: string, apiKey?: string, apiType?: string): Promise<string[]> {
|
|
42
|
+
return this.#apiClient.call<string[]>('ai.discoverModels', { baseUrl, apiKey, apiType });
|
|
43
|
+
}
|
|
44
|
+
|
|
29
45
|
async addModel(model: ModelInput): Promise<string> {
|
|
30
46
|
return this.#apiClient.call<string>('ai.addModel', { model: this.serializeModelInput(model) });
|
|
31
47
|
}
|
|
@@ -1448,6 +1448,85 @@ describe("ModelQueryBuilder paginateSubscribe", () => {
|
|
|
1448
1448
|
expect(callArg).toHaveProperty("pageSize", 10);
|
|
1449
1449
|
expect(callArg).toHaveProperty("pageNumber", 1);
|
|
1450
1450
|
});
|
|
1451
|
+
|
|
1452
|
+
it("paginateSubscribe must not deliver a stale re-fetch over a newer one", async () => {
|
|
1453
|
+
// Two server dispatches each trigger a re-fetch, and the executor can
|
|
1454
|
+
// answer them out of order: the re-fetch dispatched before a save
|
|
1455
|
+
// committed (1 result) resolves AFTER the one that saw the save
|
|
1456
|
+
// (2 results). Without ordering, the consumer's last page silently rolls
|
|
1457
|
+
// back to the stale state and no later dispatch corrects it — the exact
|
|
1458
|
+
// shape of the flaky "Paginate callback did not see second model save"
|
|
1459
|
+
// failure in tests/js prolog-and-literals.
|
|
1460
|
+
const mockSubscriptionId = "paginate-stale-sub";
|
|
1461
|
+
let capturedCallback: ((result: any) => void) | null = null;
|
|
1462
|
+
|
|
1463
|
+
const mockClient = {
|
|
1464
|
+
modelSubscribe: jest.fn().mockResolvedValue({
|
|
1465
|
+
subscriptionId: mockSubscriptionId,
|
|
1466
|
+
result: { instances: [], totalCount: 0 },
|
|
1467
|
+
}),
|
|
1468
|
+
subscribeToQueryUpdates: jest.fn().mockImplementation((_id: string, cb: any) => {
|
|
1469
|
+
capturedCallback = cb;
|
|
1470
|
+
return () => {};
|
|
1471
|
+
}),
|
|
1472
|
+
keepAliveQuery: jest.fn().mockResolvedValue(true),
|
|
1473
|
+
disposeQuerySubscription: jest.fn().mockResolvedValue(true),
|
|
1474
|
+
};
|
|
1475
|
+
|
|
1476
|
+
// First call is the initial fetch (resolves immediately, empty). The two
|
|
1477
|
+
// update-triggered re-fetches get manually controlled promises so the
|
|
1478
|
+
// test can resolve them in reverse order.
|
|
1479
|
+
const deferred: Array<(v: any) => void> = [];
|
|
1480
|
+
let call = 0;
|
|
1481
|
+
const mockPerspective = {
|
|
1482
|
+
uuid: "test-uuid",
|
|
1483
|
+
client: mockClient,
|
|
1484
|
+
modelSubscribe: jest.fn().mockImplementation(async (className: string, queryJson: string) => {
|
|
1485
|
+
return mockClient.modelSubscribe("test-uuid", className, queryJson);
|
|
1486
|
+
}),
|
|
1487
|
+
modelQuery: jest.fn().mockImplementation(() => {
|
|
1488
|
+
call++;
|
|
1489
|
+
if (call === 1) return Promise.resolve({ instances: [], totalCount: 0 });
|
|
1490
|
+
return new Promise(resolve => { deferred.push(resolve); });
|
|
1491
|
+
}),
|
|
1492
|
+
} as any;
|
|
1493
|
+
|
|
1494
|
+
const { Ad4mModel, Model, Flag, Property } = require("./index");
|
|
1495
|
+
|
|
1496
|
+
@Model({ name: "StaleTest" })
|
|
1497
|
+
class StaleTest extends Ad4mModel {
|
|
1498
|
+
@Flag({ through: "test://type", value: "test://stale" })
|
|
1499
|
+
type: string = "test://stale";
|
|
1500
|
+
@Property({ through: "test://name" })
|
|
1501
|
+
name: string = "";
|
|
1502
|
+
}
|
|
1503
|
+
|
|
1504
|
+
const userCallback = jest.fn();
|
|
1505
|
+
const builder = StaleTest.query(mockPerspective);
|
|
1506
|
+
await builder.paginateSubscribe(10, 1, userCallback);
|
|
1507
|
+
|
|
1508
|
+
// Two dispatches arrive back to back; both re-fetches are now in flight.
|
|
1509
|
+
capturedCallback!({});
|
|
1510
|
+
capturedCallback!({});
|
|
1511
|
+
await new Promise(r => setTimeout(r, 10));
|
|
1512
|
+
expect(deferred.length).toBe(2);
|
|
1513
|
+
|
|
1514
|
+
// The NEWER re-fetch resolves first, with both models…
|
|
1515
|
+
deferred[1]({ instances: [{ id: "m1" }, { id: "m2" }], totalCount: 2 });
|
|
1516
|
+
await new Promise(r => setTimeout(r, 10));
|
|
1517
|
+
// …then the STALE one resolves, with only the first model.
|
|
1518
|
+
deferred[0]({ instances: [{ id: "m1" }], totalCount: 1 });
|
|
1519
|
+
await new Promise(r => setTimeout(r, 10));
|
|
1520
|
+
|
|
1521
|
+
// The stale result must have been dropped: last delivered page is the
|
|
1522
|
+
// 2-model one, and it was delivered exactly once.
|
|
1523
|
+
expect(userCallback).toHaveBeenCalledTimes(1);
|
|
1524
|
+
const lastArg = userCallback.mock.calls[userCallback.mock.calls.length - 1][0];
|
|
1525
|
+
expect(lastArg.totalCount).toBe(2);
|
|
1526
|
+
expect(lastArg.results.length).toBe(2);
|
|
1527
|
+
|
|
1528
|
+
builder.dispose();
|
|
1529
|
+
});
|
|
1451
1530
|
});
|
|
1452
1531
|
|
|
1453
1532
|
// ============================================================================
|