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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/lib/index.cjs +414 -160
  2. package/lib/index.js +414 -161
  3. package/lib/src/agent/AgentClient.d.ts +16 -1
  4. package/lib/src/agent/AgentClient.js +21 -2
  5. package/lib/src/ai/AITypes.d.ts +6 -2
  6. package/lib/src/apiClient.js +1 -1
  7. package/lib/src/generated/api/AgentMessage.d.ts +10 -0
  8. package/lib/src/generated/api/AgentReply.d.ts +9 -0
  9. package/{src/generated/api/PerspectiveRemovedWithOwner.ts → lib/src/generated/api/AgentReply.js} +1 -2
  10. package/lib/src/generated/api/Apps.d.ts +4 -0
  11. package/lib/src/generated/api/Events.d.ts +10 -12
  12. package/lib/src/generated/api/FlowStateChangedEvent.d.ts +3 -2
  13. package/lib/src/generated/api/Model.d.ts +4 -0
  14. package/lib/src/generated/api/ModelApi.d.ts +5 -1
  15. package/lib/src/generated/api/ModelApiInput.d.ts +7 -1
  16. package/lib/src/generated/api/Notification.d.ts +5 -1
  17. package/lib/src/generated/api/NotificationInput.d.ts +4 -0
  18. package/lib/src/generated/api/PerspectiveEvent.d.ts +8 -0
  19. package/lib/src/generated/api/{PerspectiveLinkWithOwner.d.ts → PerspectiveLinkEvent.d.ts} +4 -2
  20. package/lib/src/generated/api/{PerspectiveLinkUpdatedWithOwner.d.ts → PerspectiveLinkUpdatedEvent.d.ts} +4 -2
  21. package/lib/src/generated/api/PerspectiveRemovedEvent.d.ts +7 -0
  22. package/lib/src/generated/api/PerspectiveRemovedEvent.js +2 -0
  23. package/lib/src/generated/api/RequestCapabilityRequest.d.ts +1 -0
  24. package/lib/src/generated/api/RpcMethods.d.ts +16 -1
  25. package/lib/src/generated/api/RpcMethods.js +1 -0
  26. package/lib/src/generated/api/RunAgentRequest.d.ts +26 -0
  27. package/lib/src/generated/api/RuntimeUpdateNotificationParams.d.ts +6 -1
  28. package/lib/src/generated/api/UsersRevokeAllSessionsParams.d.ts +7 -0
  29. package/lib/src/generated/api/UsersRevokeAllSessionsParams.js +2 -0
  30. package/lib/src/generated/api/index.d.ts +3 -0
  31. package/lib/src/index.d.ts +1 -0
  32. package/lib/src/index.js +1 -0
  33. package/lib/src/model/types.d.ts +6 -0
  34. package/lib/src/neighbourhood/SfuManager.d.ts +15 -0
  35. package/lib/src/neighbourhood/SfuManager.js +39 -2
  36. package/lib/src/perspectives/Mentioning.d.ts +37 -0
  37. package/lib/src/perspectives/Mentioning.js +58 -0
  38. package/lib/src/perspectives/PerspectiveClient.d.ts +22 -0
  39. package/lib/src/perspectives/PerspectiveClient.js +13 -0
  40. package/lib/src/perspectives/PerspectiveProxy.d.ts +19 -0
  41. package/lib/src/perspectives/PerspectiveProxy.js +19 -0
  42. package/lib/src/perspectives/TextContent.d.ts +4 -0
  43. package/lib/src/perspectives/TextContent.js +4 -0
  44. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +69 -10
  45. package/lib/src/perspectives/WakerSubscriptionManager.js +163 -61
  46. package/lib/src/runtime/RuntimeClient.d.ts +6 -3
  47. package/lib/src/runtime/RuntimeClient.js +2 -0
  48. package/lib/src/runtime/RuntimeTypes.d.ts +5 -1
  49. package/package.json +2 -2
  50. package/src/Ad4mClient.test.ts +53 -18
  51. package/src/agent/AgentClient.ts +26 -2
  52. package/src/ai/AITypes.ts +6 -2
  53. package/src/apiClient.test.ts +2 -3
  54. package/src/apiClient.ts +1 -1
  55. package/src/generated/api/AgentMessage.ts +10 -0
  56. package/src/generated/api/AgentReply.ts +10 -0
  57. package/src/generated/api/Apps.ts +6 -1
  58. package/src/generated/api/Events.ts +10 -12
  59. package/src/generated/api/FlowStateChangedEvent.ts +3 -2
  60. package/src/generated/api/Model.ts +4 -0
  61. package/src/generated/api/ModelApi.ts +5 -1
  62. package/src/generated/api/ModelApiInput.ts +8 -1
  63. package/src/generated/api/Notification.ts +5 -1
  64. package/src/generated/api/NotificationInput.ts +6 -1
  65. package/src/generated/api/PerspectiveEvent.ts +7 -0
  66. package/src/generated/api/{PerspectiveLinkUpdatedWithOwner.ts → PerspectiveLinkEvent.ts} +4 -1
  67. package/src/generated/api/PerspectiveLinkUpdatedEvent.ts +7 -0
  68. package/src/generated/api/PerspectiveRemovedEvent.ts +6 -0
  69. package/src/generated/api/RequestCapabilityRequest.ts +1 -1
  70. package/src/generated/api/RpcMethods.ts +8 -1
  71. package/src/generated/api/RunAgentRequest.ts +26 -0
  72. package/src/generated/api/RuntimeUpdateNotificationParams.ts +7 -1
  73. package/src/generated/api/UsersRevokeAllSessionsParams.ts +8 -0
  74. package/src/generated/api/index.ts +3 -0
  75. package/src/index.ts +1 -0
  76. package/src/model/types.ts +6 -0
  77. package/src/neighbourhood/SfuManager.test.ts +151 -2
  78. package/src/neighbourhood/SfuManager.ts +38 -1
  79. package/src/perspectives/Mentioning.test.ts +78 -0
  80. package/src/perspectives/Mentioning.ts +42 -0
  81. package/src/perspectives/PerspectiveClient.ts +30 -0
  82. package/src/perspectives/PerspectiveProxy.ts +26 -0
  83. package/src/perspectives/TextContent.ts +4 -0
  84. package/src/perspectives/WakerSubscriptionManager.test.ts +383 -151
  85. package/src/perspectives/WakerSubscriptionManager.ts +220 -61
  86. package/src/perspectives/link-updated-type.test.ts +2 -2
  87. package/src/perspectives/listener-leaks.test.ts +3 -3
  88. package/src/runtime/RuntimeClient.ts +6 -3
  89. package/src/runtime/RuntimeTypes.ts +8 -1
  90. package/lib/src/generated/api/MessageReceivedEvent.d.ts +0 -7
  91. package/lib/src/generated/api/PerspectiveRemovedWithOwner.d.ts +0 -5
  92. package/lib/src/generated/api/PerspectiveWithOwner.d.ts +0 -6
  93. package/src/generated/api/MessageReceivedEvent.ts +0 -7
  94. package/src/generated/api/PerspectiveLinkWithOwner.ts +0 -4
  95. package/src/generated/api/PerspectiveWithOwner.ts +0 -4
  96. /package/lib/src/generated/api/{PerspectiveRemovedWithOwner.js → AgentMessage.js} +0 -0
  97. /package/lib/src/generated/api/{MessageReceivedEvent.js → PerspectiveEvent.js} +0 -0
  98. /package/lib/src/generated/api/{PerspectiveLinkUpdatedWithOwner.js → PerspectiveLinkEvent.js} +0 -0
  99. /package/lib/src/generated/api/{PerspectiveLinkWithOwner.js → PerspectiveLinkUpdatedEvent.js} +0 -0
  100. /package/lib/src/generated/api/{PerspectiveWithOwner.js → RunAgentRequest.js} +0 -0
@@ -0,0 +1,58 @@
1
+ var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
2
+ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
3
+ if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
4
+ else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
5
+ return c > 3 && r && Object.defineProperty(target, key, r), r;
6
+ };
7
+ var __metadata = (this && this.__metadata) || function (k, v) {
8
+ if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
9
+ };
10
+ import { Ad4mModel } from "../model/Ad4mModel";
11
+ import { HasMany, Model } from "../model/decorators";
12
+ /**
13
+ * The built-in abstract class `Mentioning { mentions }`: a record that
14
+ * mentions agents — a post, a message, a block of a document. `mentions` is
15
+ * a relation to their DIDs.
16
+ *
17
+ * Querying it reads every class that has a relation named `mentions`, or one
18
+ * aliased to `mentions`, under any predicate, whether or not the class has
19
+ * text. A class whose relation has another name aliases it:
20
+ *
21
+ * ```typescript
22
+ * @Model({ name: "Note", implements: [Mentioning] })
23
+ * class Note extends Ad4mModel {
24
+ * @HasMany({ through: "app://cc", alias: { Mentioning: "mentions" } })
25
+ * cc: string[] = [];
26
+ * }
27
+ *
28
+ * const mentioningMe = await Mentioning.findAll(perspective, { where: { mentions: myDid } });
29
+ * ```
30
+ *
31
+ * The waker's mention subscription (`get_mention_waker_config`) reads it: a
32
+ * record whose `mentions` links the agent's DID, in a link another agent
33
+ * wrote, wakes the agent whatever its text says. Names in text it reads
34
+ * through {@link TextContent}.
35
+ *
36
+ * Built in: the executor declares it (mirrors
37
+ * `rust-executor/src/perspectives/hardwired_sdna/mentioning.json`) and reads
38
+ * it by its URI, `ad4m://Mentioning`, so a perspective never stores it and an
39
+ * app class named `Mentioning` does not replace it. `register()` on it writes
40
+ * nothing.
41
+ */
42
+ let Mentioning = class Mentioning extends Ad4mModel {
43
+ constructor() {
44
+ super(...arguments);
45
+ /** The agents (DIDs) the record mentions. */
46
+ this.mentions = [];
47
+ }
48
+ };
49
+ /** The URI the executor reads it by. */
50
+ Mentioning.builtinUri = "ad4m://Mentioning";
51
+ __decorate([
52
+ HasMany({ through: "ad4m://mentions" }),
53
+ __metadata("design:type", Array)
54
+ ], Mentioning.prototype, "mentions", void 0);
55
+ Mentioning = __decorate([
56
+ Model({ name: "Mentioning", abstract: true })
57
+ ], Mentioning);
58
+ export { Mentioning };
@@ -11,6 +11,8 @@ import { LinkStatus, PerspectiveProxy } from './PerspectiveProxy';
11
11
  import { AIClient } from "../ai/AIClient";
12
12
  import type { QueryLagged, QueryUpdate, Subscribed } from "./LiveQuery";
13
13
  import type { TranscriptTurn } from "../generated/api";
14
+ import type { AgentMessage } from "../generated/api/AgentMessage";
15
+ import type { AgentReply } from "../generated/api/AgentReply";
14
16
  import type { JsonValue } from "../generated/api/serde_json/JsonValue";
15
17
  import type { AddAutoProcessorConfig, InterpretationOverlayInfo, RawScope, RunInterpretationObserveOptions } from "./AutoProcessor";
16
18
  import type { FlowFireOutcome, FlowMintedReceipt, FlowOutputRef, FlowProposeResult, FlowReceiptVerdict, FlowStateEntry, FlowValidOutput } from "./FlowInstance";
@@ -86,6 +88,26 @@ export declare class PerspectiveClient {
86
88
  * Defaults to {@link LONG_TIMEOUT_MS}, like the single-shot path.
87
89
  */
88
90
  runInterpretationWithHarness(uuid: string, transcript: TranscriptTurn[], basePrefix: string, maxToolCalls: number, classes?: string[], modelOverride?: string, existingScope?: RawScope, observationId?: string, emitDebugEvents?: boolean, options?: CallOptions): Promise<string[]>;
91
+ /**
92
+ * A conversation with a model in this perspective, using the executor's own tools: the tools
93
+ * that read this perspective, and only the writing tools named in `writeTools`. Every tool a
94
+ * session offers acts on this perspective alone, so tools about other perspectives, the agent
95
+ * or the node (listing or publishing perspectives, the profile) are not available. Runs as the
96
+ * caller, with the caller's capabilities, and answers with the model's final reply.
97
+ *
98
+ * Defaults to {@link LONG_TIMEOUT_MS}: an agent may read documentation and make many tool
99
+ * calls before it answers.
100
+ */
101
+ runAgent(uuid: string, messages: AgentMessage[], settings?: {
102
+ /** What the person is looking at, as a hint for the model (`{ recordId }`). */
103
+ context?: Record<string, unknown>;
104
+ /** Tools that write which the model may call. Absent: the session only reads. */
105
+ writeTools?: string[];
106
+ /** A model id; the node's default language model when absent. */
107
+ model?: string;
108
+ /** How many tool calls before the model must answer. Default 20. */
109
+ maxToolCalls?: number;
110
+ }, options?: CallOptions): Promise<AgentReply>;
89
111
  /**
90
112
  * Register a neighbourhood auto-processor on this perspective. The executor's
91
113
  * watch loop then runs interpretation automatically over new source items
@@ -211,6 +211,19 @@ export class PerspectiveClient {
211
211
  emitDebugEvents,
212
212
  }, options);
213
213
  }
214
+ /**
215
+ * A conversation with a model in this perspective, using the executor's own tools: the tools
216
+ * that read this perspective, and only the writing tools named in `writeTools`. Every tool a
217
+ * session offers acts on this perspective alone, so tools about other perspectives, the agent
218
+ * or the node (listing or publishing perspectives, the profile) are not available. Runs as the
219
+ * caller, with the caller's capabilities, and answers with the model's final reply.
220
+ *
221
+ * Defaults to {@link LONG_TIMEOUT_MS}: an agent may read documentation and make many tool
222
+ * calls before it answers.
223
+ */
224
+ async runAgent(uuid, messages, settings, options) {
225
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runAgent', { uuid, messages, ...settings }, options);
226
+ }
214
227
  /**
215
228
  * Register a neighbourhood auto-processor on this perspective. The executor's
216
229
  * watch loop then runs interpretation automatically over new source items
@@ -13,6 +13,8 @@ import { AIClient } from "../ai/AIClient";
13
13
  import { AllInstancesResult } from "../model/types";
14
14
  import { 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";
@@ -252,6 +254,17 @@ export declare class PerspectiveProxy {
252
254
  * @param options `signal` / `timeoutMs` (default {@link LONG_TIMEOUT_MS})
253
255
  */
254
256
  runInterpretationWithHarness(transcript: TranscriptTurn[], basePrefix: string, maxToolCalls: number, classes?: string[], modelOverride?: string, observationId?: string, emitDebugEvents?: boolean, options?: CallOptions): Promise<string[]>;
257
+ /**
258
+ * Ask a model something about this perspective, or ask it to change something, with the
259
+ * executor's own tools — including the tools apps install for their records. It reads freely;
260
+ * it writes only with the tools named in `settings.writeTools`, as you. Answers with the
261
+ * model's final reply.
262
+ *
263
+ * @param messages the conversation so far, the person's request last
264
+ * @param settings `context` (what the person is looking at), `writeTools`, `model`, `maxToolCalls`
265
+ * @param options `signal` / `timeoutMs` (default {@link LONG_TIMEOUT_MS})
266
+ */
267
+ runAgent(messages: AgentMessage[], settings?: Parameters<PerspectiveClient['runAgent']>[2], options?: CallOptions): Promise<AgentReply>;
255
268
  /**
256
269
  * Register a neighbourhood auto-processor on this perspective. The executor
257
270
  * then runs interpretation automatically over new source items (like Flux
@@ -542,6 +555,12 @@ export declare class PerspectiveProxy {
542
555
  /**
543
556
  * Adds a pre-signed LinkExpression to the perspective.
544
557
  *
558
+ * The executor checks the signature against `link.author` and stores the
559
+ * verdict as `proof.valid`. If the same link (author, source, predicate,
560
+ * target and timestamp) is already stored with a signature that verifies,
561
+ * its stored proof is kept. The expression passed here is still returned
562
+ * and, when Shared, committed to the neighbourhood as given.
563
+ *
545
564
  * @param link - The signed LinkExpression to add
546
565
  * @param status - Whether the link should be shared
547
566
  * @param batchId - Optional batch ID to group this operation with others
@@ -349,6 +349,19 @@ export class PerspectiveProxy {
349
349
  observationId, emitDebugEvents, options) {
350
350
  return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").runInterpretationWithHarness(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, transcript, basePrefix, maxToolCalls, classes, modelOverride, undefined, observationId, emitDebugEvents, options);
351
351
  }
352
+ /**
353
+ * Ask a model something about this perspective, or ask it to change something, with the
354
+ * executor's own tools — including the tools apps install for their records. It reads freely;
355
+ * it writes only with the tools named in `settings.writeTools`, as you. Answers with the
356
+ * model's final reply.
357
+ *
358
+ * @param messages the conversation so far, the person's request last
359
+ * @param settings `context` (what the person is looking at), `writeTools`, `model`, `maxToolCalls`
360
+ * @param options `signal` / `timeoutMs` (default {@link LONG_TIMEOUT_MS})
361
+ */
362
+ async runAgent(messages, settings, options) {
363
+ return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").runAgent(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, messages, settings, options);
364
+ }
352
365
  /**
353
366
  * Register a neighbourhood auto-processor on this perspective. The executor
354
367
  * then runs interpretation automatically over new source items (like Flux
@@ -723,6 +736,12 @@ export class PerspectiveProxy {
723
736
  /**
724
737
  * Adds a pre-signed LinkExpression to the perspective.
725
738
  *
739
+ * The executor checks the signature against `link.author` and stores the
740
+ * verdict as `proof.valid`. If the same link (author, source, predicate,
741
+ * target and timestamp) is already stored with a signature that verifies,
742
+ * its stored proof is kept. The expression passed here is still returned
743
+ * and, when Shared, committed to the neighbourhood as given.
744
+ *
726
745
  * @param link - The signed LinkExpression to add
727
746
  * @param status - Whether the link should be shared
728
747
  * @param batchId - Optional batch ID to group this operation with others
@@ -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;
@@ -140,6 +197,7 @@ export declare class WakerSubscriptionManager {
140
197
  private retryPendingMs;
141
198
  private subscribeTimeoutMs;
142
199
  private retryWakeMs;
200
+ /** Per subscription its proxies: one, or a mention subscription's text and mention queries. */
143
201
  private proxies;
144
202
  private activeSubscriptions;
145
203
  /** Subscriptions the executor rejected, waiting to be re-attempted. */
@@ -232,3 +290,4 @@ export declare class WakerSubscriptionManager {
232
290
  private containers;
233
291
  private persist;
234
292
  }
293
+ export {};