@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,78 @@
1
+ /**
2
+ * The SDK's Mentioning mirrors the executor's built-in
3
+ * (`hardwired_sdna/mentioning.json`), is read by its URI, and is never
4
+ * registered in a perspective.
5
+ */
6
+ import * as fs from "fs";
7
+ import * as path from "path";
8
+ import { Mentioning } from "./Mentioning";
9
+ import { Ad4mModel } from "../model/Ad4mModel";
10
+ import { HasMany, Model, Property } from "../model/decorators";
11
+
12
+ const SDNA = JSON.parse(
13
+ fs.readFileSync(
14
+ path.resolve(__dirname, "../../../rust-executor/src/perspectives/hardwired_sdna/mentioning.json"),
15
+ "utf-8",
16
+ ),
17
+ );
18
+
19
+ describe("Mentioning", () => {
20
+ it("matches the executor's built-in shape", () => {
21
+ const { shape } = (Mentioning as any).generateSHACL();
22
+ expect(shape.targetClass).toBe(SDNA.target_class);
23
+ expect(shape.isAbstract).toBe(SDNA.abstract);
24
+ expect(shape.properties.map((p: any) => [p.path, p.name])).toEqual(
25
+ SDNA.properties.map((p: any) => [p.path, p.name]),
26
+ );
27
+ });
28
+
29
+ it("is queried by its URI", () => {
30
+ expect((Mentioning as any).prepareModelQueryParams({}).className).toBe("ad4m://Mentioning");
31
+ });
32
+
33
+ it("is implemented by a relation named mentions, with text or without", () => {
34
+ expect(() => {
35
+ @Model({ name: "MentioningRoot", implements: [Mentioning] })
36
+ class MentioningRoot extends Ad4mModel {
37
+ @Property({ through: "we://title" })
38
+ title: string = "";
39
+
40
+ @HasMany({ through: "we://mention" })
41
+ mentions: string[] = [];
42
+ }
43
+ }).not.toThrow();
44
+ });
45
+
46
+ it("is implemented through an alias", () => {
47
+ @Model({ name: "CcNote", implements: [Mentioning] })
48
+ class CcNote extends Ad4mModel {
49
+ @HasMany({ through: "app://cc", alias: { Mentioning: "mentions" } })
50
+ cc: string[] = [];
51
+ }
52
+ // The executor finds the relation by the alias in the shape, not by `implements`.
53
+ const { shape } = (CcNote as any).generateSHACL();
54
+ const cc = shape.properties.find((p: any) => p.name === "cc");
55
+ expect([cc.path, cc.alias]).toEqual(["app://cc", { Mentioning: "mentions" }]);
56
+ });
57
+
58
+ it("is not implemented by a relation that answers to another name", () => {
59
+ expect(() => {
60
+ @Model({ name: "UnaliasedNote", implements: [Mentioning] })
61
+ class UnaliasedNote extends Ad4mModel {
62
+ @HasMany({ through: "app://cc" })
63
+ cc: string[] = [];
64
+ }
65
+ }).toThrow("UnaliasedNote implements Mentioning but has no relation or alias named `mentions`");
66
+ });
67
+
68
+ it("register() writes nothing", async () => {
69
+ const { PerspectiveProxy } = await import("./PerspectiveProxy");
70
+ const calls: string[] = [];
71
+ const proxy = Object.create(PerspectiveProxy.prototype);
72
+ Object.defineProperty(proxy, "addSdna", { value: () => { calls.push("addSdna"); } });
73
+ Object.defineProperty(proxy, "addSdnaAll", { value: () => { calls.push("addSdnaAll"); } });
74
+ await expect(proxy.ensureSubjectClasses([Mentioning])).resolves.toBeUndefined();
75
+ await expect(proxy.ensureSubjectClass(Mentioning)).resolves.toBeUndefined();
76
+ expect(calls).toEqual([]);
77
+ });
78
+ });
@@ -0,0 +1,42 @@
1
+ import { Ad4mModel } from "../model/Ad4mModel";
2
+ import { HasMany, Model } from "../model/decorators";
3
+
4
+ /**
5
+ * The built-in abstract class `Mentioning { mentions }`: a record that
6
+ * mentions agents — a post, a message, a block of a document. `mentions` is
7
+ * a relation to their DIDs.
8
+ *
9
+ * Querying it reads every class that has a relation named `mentions`, or one
10
+ * aliased to `mentions`, under any predicate, whether or not the class has
11
+ * text. A class whose relation has another name aliases it:
12
+ *
13
+ * ```typescript
14
+ * @Model({ name: "Note", implements: [Mentioning] })
15
+ * class Note extends Ad4mModel {
16
+ * @HasMany({ through: "app://cc", alias: { Mentioning: "mentions" } })
17
+ * cc: string[] = [];
18
+ * }
19
+ *
20
+ * const mentioningMe = await Mentioning.findAll(perspective, { where: { mentions: myDid } });
21
+ * ```
22
+ *
23
+ * The waker's mention subscription (`get_mention_waker_config`) reads it: a
24
+ * record whose `mentions` links the agent's DID, in a link another agent
25
+ * wrote, wakes the agent whatever its text says. Names in text it reads
26
+ * through {@link TextContent}.
27
+ *
28
+ * Built in: the executor declares it (mirrors
29
+ * `rust-executor/src/perspectives/hardwired_sdna/mentioning.json`) and reads
30
+ * it by its URI, `ad4m://Mentioning`, so a perspective never stores it and an
31
+ * app class named `Mentioning` does not replace it. `register()` on it writes
32
+ * nothing.
33
+ */
34
+ @Model({ name: "Mentioning", abstract: true })
35
+ export class Mentioning extends Ad4mModel {
36
+ /** The URI the executor reads it by. */
37
+ static readonly builtinUri = "ad4m://Mentioning";
38
+
39
+ /** The agents (DIDs) the record mentions. */
40
+ @HasMany({ through: "ad4m://mentions" })
41
+ mentions: string[] = [];
42
+ }
@@ -15,6 +15,8 @@ import { LinkStatus, PerspectiveProxy } from './PerspectiveProxy';
15
15
  import { AIClient } from "../ai/AIClient";
16
16
  import type { QueryLagged, QueryUpdate, Subscribed } from "./LiveQuery";
17
17
  import type { TranscriptTurn } from "../generated/api";
18
+ import type { AgentMessage } from "../generated/api/AgentMessage";
19
+ import type { AgentReply } from "../generated/api/AgentReply";
18
20
  import type { PerspectiveQueryLinksParams } from "../generated/api/PerspectiveQueryLinksParams";
19
21
  import type { JsonValue } from "../generated/api/serde_json/JsonValue";
20
22
  import type { AddAutoProcessorConfig, InterpretationOverlayInfo, RawScope, RunInterpretationObserveOptions } from "./AutoProcessor";
@@ -295,6 +297,34 @@ export class PerspectiveClient {
295
297
  )
296
298
  }
297
299
 
300
+ /**
301
+ * A conversation with a model in this perspective, using the executor's own tools: the tools
302
+ * that read this perspective, and only the writing tools named in `writeTools`. Every tool a
303
+ * session offers acts on this perspective alone, so tools about other perspectives, the agent
304
+ * or the node (listing or publishing perspectives, the profile) are not available. Runs as the
305
+ * caller, with the caller's capabilities, and answers with the model's final reply.
306
+ *
307
+ * Defaults to {@link LONG_TIMEOUT_MS}: an agent may read documentation and make many tool
308
+ * calls before it answers.
309
+ */
310
+ async runAgent(
311
+ uuid: string,
312
+ messages: AgentMessage[],
313
+ settings?: {
314
+ /** What the person is looking at, as a hint for the model (`{ recordId }`). */
315
+ context?: Record<string, unknown>,
316
+ /** Tools that write which the model may call. Absent: the session only reads. */
317
+ writeTools?: string[],
318
+ /** A model id; the node's default language model when absent. */
319
+ model?: string,
320
+ /** How many tool calls before the model must answer. Default 20. */
321
+ maxToolCalls?: number,
322
+ },
323
+ options?: CallOptions,
324
+ ): Promise<AgentReply> {
325
+ return this.#apiClient.call('perspective.runAgent', { uuid, messages, ...settings }, options)
326
+ }
327
+
298
328
  /**
299
329
  * Register a neighbourhood auto-processor on this perspective. The executor's
300
330
  * watch loop then runs interpretation automatically over new source items
@@ -20,6 +20,8 @@ import { getCachedResult, setCachedResult, invalidatePerspectiveCache } from "..
20
20
  import { AllInstancesResult } from "../model/types";
21
21
  import { LiveQuery, Subscribed } from "./LiveQuery";
22
22
  import type { TranscriptTurn } from "../generated/api";
23
+ import type { AgentMessage } from "../generated/api/AgentMessage";
24
+ import type { AgentReply } from "../generated/api/AgentReply";
23
25
  import type { JsonValue } from "../generated/api/serde_json/JsonValue";
24
26
 
25
27
  import { SHACLShape } from "../shacl/SHACLShape";
@@ -435,6 +437,24 @@ export class PerspectiveProxy {
435
437
  )
436
438
  }
437
439
 
440
+ /**
441
+ * Ask a model something about this perspective, or ask it to change something, with the
442
+ * executor's own tools — including the tools apps install for their records. It reads freely;
443
+ * it writes only with the tools named in `settings.writeTools`, as you. Answers with the
444
+ * model's final reply.
445
+ *
446
+ * @param messages the conversation so far, the person's request last
447
+ * @param settings `context` (what the person is looking at), `writeTools`, `model`, `maxToolCalls`
448
+ * @param options `signal` / `timeoutMs` (default {@link LONG_TIMEOUT_MS})
449
+ */
450
+ async runAgent(
451
+ messages: AgentMessage[],
452
+ settings?: Parameters<PerspectiveClient['runAgent']>[2],
453
+ options?: CallOptions,
454
+ ): Promise<AgentReply> {
455
+ return await this.#client.runAgent(this.#handle.uuid, messages, settings, options)
456
+ }
457
+
438
458
  /**
439
459
  * Register a neighbourhood auto-processor on this perspective. The executor
440
460
  * then runs interpretation automatically over new source items (like Flux
@@ -833,6 +853,12 @@ export class PerspectiveProxy {
833
853
 
834
854
  /**
835
855
  * Adds a pre-signed LinkExpression to the perspective.
856
+ *
857
+ * The executor checks the signature against `link.author` and stores the
858
+ * verdict as `proof.valid`. If the same link (author, source, predicate,
859
+ * target and timestamp) is already stored with a signature that verifies,
860
+ * its stored proof is kept. The expression passed here is still returned
861
+ * and, when Shared, committed to the neighbourhood as given.
836
862
  *
837
863
  * @param link - The signed LinkExpression to add
838
864
  * @param status - Whether the link should be shared
@@ -24,6 +24,10 @@ import { Model, Property } from "../model/decorators";
24
24
  * reads it by its URI, `ad4m://TextContent`, so a perspective never stores it
25
25
  * and an app class named `TextContent` does not replace it. `register()` on
26
26
  * it writes nothing.
27
+ *
28
+ * The waker's mention subscription (`get_mention_waker_config`) reads it for
29
+ * the agent's names in the text. Mention links it reads through
30
+ * {@link Mentioning}, with text or without.
27
31
  */
28
32
  @Model({ name: "TextContent", abstract: true })
29
33
  export class TextContent extends Ad4mModel {