@coasys/ad4m 0.13.1-staging.4 → 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 (43) hide show
  1. package/lib/index.cjs +387 -154
  2. package/lib/index.js +387 -155
  3. package/lib/src/generated/api/AgentMessage.d.ts +10 -0
  4. package/lib/src/generated/api/AgentMessage.js +2 -0
  5. package/lib/src/generated/api/AgentReply.d.ts +9 -0
  6. package/lib/src/generated/api/AgentReply.js +2 -0
  7. package/lib/src/generated/api/RpcMethods.d.ts +6 -0
  8. package/lib/src/generated/api/RpcMethods.js +1 -0
  9. package/lib/src/generated/api/RunAgentRequest.d.ts +26 -0
  10. package/lib/src/generated/api/RunAgentRequest.js +1 -0
  11. package/lib/src/generated/api/index.d.ts +3 -0
  12. package/lib/src/index.d.ts +1 -0
  13. package/lib/src/index.js +1 -0
  14. package/lib/src/model/types.d.ts +6 -0
  15. package/lib/src/neighbourhood/SfuManager.d.ts +15 -0
  16. package/lib/src/neighbourhood/SfuManager.js +39 -2
  17. package/lib/src/perspectives/Mentioning.d.ts +37 -0
  18. package/lib/src/perspectives/Mentioning.js +58 -0
  19. package/lib/src/perspectives/PerspectiveClient.d.ts +22 -0
  20. package/lib/src/perspectives/PerspectiveClient.js +13 -0
  21. package/lib/src/perspectives/PerspectiveProxy.d.ts +19 -0
  22. package/lib/src/perspectives/PerspectiveProxy.js +19 -0
  23. package/lib/src/perspectives/TextContent.d.ts +4 -0
  24. package/lib/src/perspectives/TextContent.js +4 -0
  25. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +69 -10
  26. package/lib/src/perspectives/WakerSubscriptionManager.js +160 -58
  27. package/package.json +2 -2
  28. package/src/generated/api/AgentMessage.ts +10 -0
  29. package/src/generated/api/AgentReply.ts +10 -0
  30. package/src/generated/api/RpcMethods.ts +4 -0
  31. package/src/generated/api/RunAgentRequest.ts +26 -0
  32. package/src/generated/api/index.ts +3 -0
  33. package/src/index.ts +1 -0
  34. package/src/model/types.ts +6 -0
  35. package/src/neighbourhood/SfuManager.test.ts +151 -2
  36. package/src/neighbourhood/SfuManager.ts +38 -1
  37. package/src/perspectives/Mentioning.test.ts +78 -0
  38. package/src/perspectives/Mentioning.ts +42 -0
  39. package/src/perspectives/PerspectiveClient.ts +30 -0
  40. package/src/perspectives/PerspectiveProxy.ts +26 -0
  41. package/src/perspectives/TextContent.ts +4 -0
  42. package/src/perspectives/WakerSubscriptionManager.test.ts +383 -151
  43. package/src/perspectives/WakerSubscriptionManager.ts +217 -58
@@ -0,0 +1,10 @@
1
+ /**
2
+ * One turn of the conversation, as the caller holds it.
3
+ */
4
+ export type AgentMessage = {
5
+ /**
6
+ * `user` or `assistant`.
7
+ */
8
+ role: string;
9
+ content: string;
10
+ };
@@ -0,0 +1,2 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ export {};
@@ -0,0 +1,9 @@
1
+ /**
2
+ * How a session ended.
3
+ */
4
+ export type AgentReply = {
5
+ /**
6
+ * What the model said last: its answer to the person.
7
+ */
8
+ text: string;
9
+ };
@@ -0,0 +1,2 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ export {};
@@ -5,6 +5,7 @@ import type { Agent } from "./Agent";
5
5
  import type { AgentAddEntanglementProofsParams } from "./AgentAddEntanglementProofsParams";
6
6
  import type { AgentByDidParams } from "./AgentByDidParams";
7
7
  import type { AgentRemoveAppParams } from "./AgentRemoveAppParams";
8
+ import type { AgentReply } from "./AgentReply";
8
9
  import type { AgentRevokeTokenParams } from "./AgentRevokeTokenParams";
9
10
  import type { AgentSignature } from "./AgentSignature";
10
11
  import type { AgentStatus } from "./AgentStatus";
@@ -125,6 +126,7 @@ import type { PublishLanguageRequest } from "./PublishLanguageRequest";
125
126
  import type { PublishNeighbourhoodRequest } from "./PublishNeighbourhoodRequest";
126
127
  import type { RequestCapabilityRequest } from "./RequestCapabilityRequest";
127
128
  import type { RequestPaymentRequest } from "./RequestPaymentRequest";
129
+ import type { RunAgentRequest } from "./RunAgentRequest";
128
130
  import type { RunInterpretationRequest } from "./RunInterpretationRequest";
129
131
  import type { RunInterpretationWithHarnessRequest } from "./RunInterpretationWithHarnessRequest";
130
132
  import type { RuntimeComputeLogParams } from "./RuntimeComputeLogParams";
@@ -636,6 +638,10 @@ export interface RpcMethods {
636
638
  params: PerspectiveSubscriptionParams;
637
639
  result: PerspectiveResynced;
638
640
  };
641
+ "perspective.runAgent": {
642
+ params: RunAgentRequest;
643
+ result: AgentReply;
644
+ };
639
645
  "perspective.runInterpretation": {
640
646
  params: RunInterpretationRequest;
641
647
  result: Array<string>;
@@ -92,6 +92,7 @@ export const LONG_METHODS = new Set([
92
92
  "language.publish",
93
93
  "neighbourhood.join",
94
94
  "neighbourhood.publish",
95
+ "perspective.runAgent",
95
96
  "perspective.runInterpretation",
96
97
  "perspective.runInterpretationWithHarness",
97
98
  "runtime.restartHolochain",
@@ -0,0 +1,26 @@
1
+ import type { AgentMessage } from "./AgentMessage";
2
+ export type RunAgentRequest = {
3
+ uuid: string;
4
+ /**
5
+ * The conversation so far, the person's request last.
6
+ */
7
+ messages: Array<AgentMessage>;
8
+ /**
9
+ * What the person is looking at, as a hint for the model (`{ "recordId": "…" }`).
10
+ */
11
+ context?: Record<string, unknown>;
12
+ /**
13
+ * Tools that write which the model may call — `instance_update`, `template_update`; only
14
+ * tools that write inside the perspective (`agent_session::SESSION_WRITES`). None means a
15
+ * session that only reads.
16
+ */
17
+ writeTools?: Array<string>;
18
+ /**
19
+ * A model id; the node's default language model when absent.
20
+ */
21
+ model?: string;
22
+ /**
23
+ * How many tool calls the model may make before it must answer. Default 20.
24
+ */
25
+ maxToolCalls?: number;
26
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -2,6 +2,8 @@ export type { AddLinkExpressionRequest } from "./AddLinkExpressionRequest";
2
2
  export type { AddLinkRequest } from "./AddLinkRequest";
3
3
  export type { AddLinksBulkRequest } from "./AddLinksBulkRequest";
4
4
  export type { AddSdnaRequest } from "./AddSdnaRequest";
5
+ export type { AgentMessage } from "./AgentMessage";
6
+ export type { AgentReply } from "./AgentReply";
5
7
  export type { AgentsByDidsRequest } from "./AgentsByDidsRequest";
6
8
  export type { ApplyTemplateRequest } from "./ApplyTemplateRequest";
7
9
  export type { CommitBatchRequest } from "./CommitBatchRequest";
@@ -33,6 +35,7 @@ export type { QueryRequest } from "./QueryRequest";
33
35
  export type { RemoveLinkRequest } from "./RemoveLinkRequest";
34
36
  export type { RemoveLinksBulkRequest } from "./RemoveLinksBulkRequest";
35
37
  export type { ResyncSubscriptionRequest } from "./ResyncSubscriptionRequest";
38
+ export type { RunAgentRequest } from "./RunAgentRequest";
36
39
  export type { RunInterpretationRequest } from "./RunInterpretationRequest";
37
40
  export type { SetDefaultModelRequest } from "./SetDefaultModelRequest";
38
41
  export type { SetFreeHostingEnabledRequest } from "./SetFreeHostingEnabledRequest";
@@ -21,6 +21,7 @@ export * from "./perspectives/AutoProcessor";
21
21
  export * from "./perspectives/InterpretationModels";
22
22
  export * from "./perspectives/FlowModels";
23
23
  export * from "./perspectives/TextContent";
24
+ export * from "./perspectives/Mentioning";
24
25
  export * from "./perspectives/Container";
25
26
  export * from "./perspectives/FlowInstance";
26
27
  export * from "./perspectives/SparqlBindings";
package/lib/src/index.js CHANGED
@@ -21,6 +21,7 @@ export * from "./perspectives/AutoProcessor";
21
21
  export * from "./perspectives/InterpretationModels";
22
22
  export * from "./perspectives/FlowModels";
23
23
  export * from "./perspectives/TextContent";
24
+ export * from "./perspectives/Mentioning";
24
25
  export * from "./perspectives/Container";
25
26
  // Also exports FlowFireOutcome / FlowProposeResult, the result shapes of the
26
27
  // flow write API — they live beside the `proposeTransition()` surface.
@@ -484,6 +484,12 @@ export interface LinkRow {
484
484
  valid: boolean;
485
485
  invalid: boolean;
486
486
  };
487
+ /**
488
+ * Where this executor holds the link, spelled as `perspective.get()` spells
489
+ * it. Absent only when the store recorded none. Not signed: it says nothing
490
+ * about who wrote the link.
491
+ */
492
+ status?: "SHARED" | "LOCAL";
487
493
  }
488
494
  /** `instance.__links`: requested entry (spelled as requested) → its rows, oldest first. */
489
495
  export type LinksMap = Record<string, LinkRow[]>;
@@ -101,6 +101,10 @@ export declare class SfuManager {
101
101
  private rosterUnsubscribe;
102
102
  private dataChannelUnsubscribe;
103
103
  private disconnectedTimer;
104
+ /** Running while the room's roster leaves this agent out: see `noticeRoster`. */
105
+ private unlistedTimer;
106
+ /** How long the roster may leave this agent out before the call is rebuilt. */
107
+ private static readonly UNLISTED_GRACE_MS;
104
108
  constructor(neighbourhood: SfuNeighbourhoodApi, roomId: string, agentDid: string, neighbourhoodUrl?: string, iceConfig?: SfuIceConfig, sfuConfig?: SfuConfig);
105
109
  /**
106
110
  * Rebuild the call after its connection failed: leave, then join again
@@ -121,6 +125,17 @@ export declare class SfuManager {
121
125
  join(localStream: MediaStream): Promise<void>;
122
126
  /** Drop the server-event subscriptions of the current join. */
123
127
  private releaseServerEvents;
128
+ private clearUnlistedTimer;
129
+ /**
130
+ * The room's roster no longer lists this agent while `pc` is the call's:
131
+ * the server has dropped this session, and ICE may not say so. In E6
132
+ * (CI job 53158) one of six sessions never started a rebuild after a
133
+ * 20 s outage the server had dropped it for. Rebuild once the roster has
134
+ * left this agent out for `UNLISTED_GRACE_MS`; a roster that lists it
135
+ * again in that time cancels, since one published just before this
136
+ * join landed can arrive after it.
137
+ */
138
+ private noticeRoster;
124
139
  /** Undo a join that failed part way: its subscription and its connection. */
125
140
  private abandon;
126
141
  /**
@@ -82,6 +82,8 @@ export class SfuManager {
82
82
  this.rosterUnsubscribe = null;
83
83
  this.dataChannelUnsubscribe = null;
84
84
  this.disconnectedTimer = null;
85
+ /** Running while the room's roster leaves this agent out: see `noticeRoster`. */
86
+ this.unlistedTimer = null;
85
87
  this.neighbourhood = neighbourhood;
86
88
  this.neighbourhoodUrl = neighbourhoodUrl || "";
87
89
  this.roomId = roomId;
@@ -368,6 +370,37 @@ export class SfuManager {
368
370
  this.renegotiationUnsubscribe = null;
369
371
  this.rosterUnsubscribe?.();
370
372
  this.rosterUnsubscribe = null;
373
+ this.clearUnlistedTimer();
374
+ }
375
+ clearUnlistedTimer() {
376
+ if (this.unlistedTimer) {
377
+ clearTimeout(this.unlistedTimer);
378
+ this.unlistedTimer = null;
379
+ }
380
+ }
381
+ /**
382
+ * The room's roster no longer lists this agent while `pc` is the call's:
383
+ * the server has dropped this session, and ICE may not say so. In E6
384
+ * (CI job 53158) one of six sessions never started a rebuild after a
385
+ * 20 s outage the server had dropped it for. Rebuild once the roster has
386
+ * left this agent out for `UNLISTED_GRACE_MS`; a roster that lists it
387
+ * again in that time cancels, since one published just before this
388
+ * join landed can arrive after it.
389
+ */
390
+ noticeRoster(pc, dids) {
391
+ if (dids.includes(this.agentDid)) {
392
+ this.clearUnlistedTimer();
393
+ return;
394
+ }
395
+ if (this.unlistedTimer)
396
+ return;
397
+ this.unlistedTimer = setTimeout(() => {
398
+ this.unlistedTimer = null;
399
+ if (this.state.peerConnection !== pc)
400
+ return;
401
+ console.info("SFU: the room no longer lists this session, rebuilding the call");
402
+ void this.reconnect();
403
+ }, SfuManager.UNLISTED_GRACE_MS);
371
404
  }
372
405
  /** Undo a join that failed part way: its subscription and its connection. */
373
406
  abandon(pc) {
@@ -402,8 +435,10 @@ export class SfuManager {
402
435
  if (!ours(roster) || this.state.peerConnection !== pc)
403
436
  return;
404
437
  void joined.then(() => {
405
- if (this.state.peerConnection === pc)
406
- this.applyRoster(roster.participants, true);
438
+ if (this.state.peerConnection !== pc)
439
+ return;
440
+ this.applyRoster(roster.participants, true);
441
+ this.noticeRoster(pc, roster.participants);
407
442
  });
408
443
  });
409
444
  for (const unsubscribe of previous)
@@ -617,3 +652,5 @@ SfuManager.MAX_RECONNECTS = 3;
617
652
  SfuManager.REJOIN_WINDOW_MS = 120000;
618
653
  /** How long ICE may stay disconnected before a rebuild: the executor's `ICE_DISCONNECT_GRACE`. */
619
654
  SfuManager.DISCONNECT_GRACE_MS = 10000;
655
+ /** How long the roster may leave this agent out before the call is rebuilt. */
656
+ SfuManager.UNLISTED_GRACE_MS = 3000;
@@ -0,0 +1,37 @@
1
+ import { Ad4mModel } from "../model/Ad4mModel";
2
+ /**
3
+ * The built-in abstract class `Mentioning { mentions }`: a record that
4
+ * mentions agents — a post, a message, a block of a document. `mentions` is
5
+ * a relation to their DIDs.
6
+ *
7
+ * Querying it reads every class that has a relation named `mentions`, or one
8
+ * aliased to `mentions`, under any predicate, whether or not the class has
9
+ * text. A class whose relation has another name aliases it:
10
+ *
11
+ * ```typescript
12
+ * @Model({ name: "Note", implements: [Mentioning] })
13
+ * class Note extends Ad4mModel {
14
+ * @HasMany({ through: "app://cc", alias: { Mentioning: "mentions" } })
15
+ * cc: string[] = [];
16
+ * }
17
+ *
18
+ * const mentioningMe = await Mentioning.findAll(perspective, { where: { mentions: myDid } });
19
+ * ```
20
+ *
21
+ * The waker's mention subscription (`get_mention_waker_config`) reads it: a
22
+ * record whose `mentions` links the agent's DID, in a link another agent
23
+ * wrote, wakes the agent whatever its text says. Names in text it reads
24
+ * through {@link TextContent}.
25
+ *
26
+ * Built in: the executor declares it (mirrors
27
+ * `rust-executor/src/perspectives/hardwired_sdna/mentioning.json`) and reads
28
+ * it by its URI, `ad4m://Mentioning`, so a perspective never stores it and an
29
+ * app class named `Mentioning` does not replace it. `register()` on it writes
30
+ * nothing.
31
+ */
32
+ export declare class Mentioning extends Ad4mModel {
33
+ /** The URI the executor reads it by. */
34
+ static readonly builtinUri = "ad4m://Mentioning";
35
+ /** The agents (DIDs) the record mentions. */
36
+ mentions: string[];
37
+ }
@@ -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 {};