@coasys/ad4m 0.13.0-test-model-layer → 0.13.0-test-flows-1

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 (55) hide show
  1. package/lib/index.cjs +817 -65
  2. package/lib/index.js +814 -66
  3. package/lib/src/ai/AIClient.d.ts +13 -0
  4. package/lib/src/ai/AIClient.js +15 -0
  5. package/lib/src/ai/AITypes.d.ts +5 -0
  6. package/lib/src/index.js +2 -0
  7. package/lib/src/model/Ad4mModel.d.ts +6 -1
  8. package/lib/src/model/Ad4mModel.js +41 -6
  9. package/lib/src/model/ModelQueryBuilder.d.ts +47 -3
  10. package/lib/src/model/ModelQueryBuilder.js +97 -6
  11. package/lib/src/model/query-common.d.ts +10 -1
  12. package/lib/src/model/query-common.js +16 -0
  13. package/lib/src/model/query-sparql.d.ts +11 -0
  14. package/lib/src/model/query-sparql.js +93 -1
  15. package/lib/src/model/query-utils.js +16 -0
  16. package/lib/src/model/shacl-gen.js +12 -0
  17. package/lib/src/model/types.d.ts +320 -3
  18. package/lib/src/model/types.js +9 -0
  19. package/lib/src/perspectives/AutoProcessor.d.ts +8 -0
  20. package/lib/src/perspectives/FlowInstance.d.ts +176 -12
  21. package/lib/src/perspectives/FlowInstance.js +77 -13
  22. package/lib/src/perspectives/FlowModels.d.ts +40 -9
  23. package/lib/src/perspectives/FlowModels.js +59 -13
  24. package/lib/src/perspectives/PerspectiveClient.d.ts +18 -0
  25. package/lib/src/perspectives/PerspectiveClient.js +30 -0
  26. package/lib/src/perspectives/PerspectiveProxy.d.ts +69 -2
  27. package/lib/src/perspectives/PerspectiveProxy.js +157 -7
  28. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +55 -5
  29. package/lib/src/perspectives/WakerSubscriptionManager.js +183 -8
  30. package/lib/src/shacl/SHACLFlow.d.ts +43 -0
  31. package/package.json +1 -1
  32. package/src/ai/AIClient.ts +16 -0
  33. package/src/ai/AITypes.ts +5 -0
  34. package/src/index.ts +2 -0
  35. package/src/model/Ad4mModel.test.ts +442 -0
  36. package/src/model/Ad4mModel.ts +39 -7
  37. package/src/model/ModelQueryBuilder.ts +101 -10
  38. package/src/model/query-common.ts +20 -1
  39. package/src/model/query-sparql.test.ts +115 -0
  40. package/src/model/query-sparql.ts +97 -1
  41. package/src/model/query-utils.ts +18 -0
  42. package/src/model/relation-filtering.test.ts +7 -0
  43. package/src/model/shacl-gen.ts +12 -0
  44. package/src/model/shacl-roundtrip.test.ts +71 -0
  45. package/src/model/types-typed-query.test.ts +42 -0
  46. package/src/model/types.ts +316 -6
  47. package/src/perspectives/AutoProcessor.ts +8 -0
  48. package/src/perspectives/FlowInstance.ts +194 -13
  49. package/src/perspectives/FlowModels.ts +53 -13
  50. package/src/perspectives/PerspectiveClient.ts +62 -0
  51. package/src/perspectives/PerspectiveProxy.test.ts +272 -0
  52. package/src/perspectives/PerspectiveProxy.ts +163 -7
  53. package/src/perspectives/WakerSubscriptionManager.test.ts +199 -0
  54. package/src/perspectives/WakerSubscriptionManager.ts +197 -9
  55. package/src/shacl/SHACLFlow.ts +44 -0
@@ -1,15 +1,73 @@
1
1
  /**
2
2
  * WakerSubscriptionManager — manages live query subscriptions for the waker.
3
3
  *
4
- * Lives in core so it can be imported by both the plugin and integration tests
5
- * without ESM/CJS import issues.
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
- * NOTE: keep in sync with plugins/ad4m/wakerSubscriptionManager.ts
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
- await proxy.initialized;
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
- // Remove from active state so it doesn't get persisted/retried
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
- return; // Don't throw — caller should not crash
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() {
@@ -115,6 +115,49 @@ export interface ModelQuery {
115
115
  * §7.4). Ignored when the query is used as a state guard or context.
116
116
  */
117
117
  or?: ModelQuery[];
118
+ /**
119
+ * When this query is used as a `ConsensusRule.fromRole`, require each
120
+ * matched instance to be a valid output of a completed run of another
121
+ * flow, and date the grant from that run's quorum instead of from an
122
+ * assignment link.
123
+ *
124
+ * The same name and the same check as the model-query filter
125
+ * `where: { producedByFlow }`: a receipt filed under `flow`'s index must
126
+ * verify against this replica's own flow definitions, be for `flow`, have
127
+ * settled into `state`, and name this instance (as this query's
128
+ * `className`) among its outputs. Each replica checks this against its
129
+ * own graph; the read-set carries only the resulting grant date.
130
+ *
131
+ * Two things to know before configuring one:
132
+ * - An instance no verified receipt produced is simply not a member.
133
+ * There is no fallback to the assignment link — if there were, writing
134
+ * that link would grant the role and this gate would be decorative.
135
+ * - **A granted role is not un-granted by undoing the flow.** Retracting
136
+ * a settling vote moves the live flow back; the receipt keeps
137
+ * verifying. The only un-grant is a new signed
138
+ * `ad4m://flow/role_grant_revoked` tombstone on the instance, from an
139
+ * author this query's own `where.author` accepts — so a query with no
140
+ * author condition can be revoked by anyone, and one naming an author
141
+ * who is not around cannot be revoked at all.
142
+ *
143
+ * Ignored when the query is used as a state guard (`requires`) or
144
+ * background `context`.
145
+ */
146
+ producedByFlow?: ProducedByFlow;
147
+ }
148
+ /**
149
+ * The granting-flow reference on a `fromRole` query's `producedByFlow`.
150
+ *
151
+ * The same shape as the model-query filter's `{ flow, state? }`, except
152
+ * that `state` is required here: without it, a run that settled into a
153
+ * flow's `rejected` state would grant what its `approved` state was meant
154
+ * to.
155
+ */
156
+ export interface ProducedByFlow {
157
+ /** The granting flow's URI — `{namespace}{name}Flow`. */
158
+ flow: string;
159
+ /** The state that run must have settled into. */
160
+ state: string;
118
161
  }
119
162
  /**
120
163
  * Consensus rule for a flow-state transition (or a top-level zero-state
package/package.json CHANGED
@@ -61,5 +61,5 @@
61
61
  "pako": "2.1.0"
62
62
  }
63
63
  },
64
- "version": "0.13.0-test-model-layer"
64
+ "version": "0.13.0-test-flows-1"
65
65
  }
@@ -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
  }
package/src/ai/AITypes.ts CHANGED
@@ -5,6 +5,9 @@ export class ModelApi {
5
5
  apiKey: string;
6
6
  model: string;
7
7
  apiType: String;
8
+ /** Optional ceiling for the provider's context window (tokens).
9
+ * Read by the Ollama provider to bound num_ctx / KV-cache VRAM. */
10
+ maxNumCtx?: number;
8
11
  }
9
12
 
10
13
  export class TokenizerSource {
@@ -35,6 +38,8 @@ export class ModelApiInput {
35
38
  apiKey: string;
36
39
  model: string;
37
40
  apiType: string;
41
+ /** Optional ceiling for the provider's context window (tokens). */
42
+ maxNumCtx?: number;
38
43
  }
39
44
 
40
45
  export class TokenizerSourceInput {
package/src/index.ts CHANGED
@@ -19,6 +19,8 @@ export * from "./perspectives/PerspectiveProxy";
19
19
  export * from "./perspectives/AutoProcessor";
20
20
  export * from "./perspectives/InterpretationModels";
21
21
  export * from "./perspectives/FlowModels";
22
+ // Also exports FlowFireOutcome / FlowProposeResult, the result shapes of the
23
+ // flow write API — they live beside the `proposeTransition()` surface.
22
24
  export * from "./perspectives/FlowInstance";
23
25
  export * from "./perspectives/SparqlBindings";
24
26
  export * from "./perspectives/WakerSubscriptionManager";