@coasys/ad4m 0.13.1-staging.2 → 0.13.1-staging.4

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 (97) hide show
  1. package/lib/index.cjs +610 -208
  2. package/lib/index.js +607 -209
  3. package/lib/src/Ad4mClient.d.ts +7 -0
  4. package/lib/src/Ad4mClient.js +9 -0
  5. package/lib/src/agent/AgentClient.d.ts +16 -1
  6. package/lib/src/agent/AgentClient.js +21 -2
  7. package/lib/src/ai/AITypes.d.ts +6 -2
  8. package/lib/src/apiClient.d.ts +13 -0
  9. package/lib/src/apiClient.js +67 -12
  10. package/lib/src/generated/api/Apps.d.ts +4 -0
  11. package/lib/src/generated/api/AuthInfo.d.ts +4 -0
  12. package/lib/src/generated/api/Events.d.ts +10 -12
  13. package/lib/src/generated/api/FlowStateChangedEvent.d.ts +3 -2
  14. package/lib/src/generated/api/Model.d.ts +4 -0
  15. package/lib/src/generated/api/ModelApi.d.ts +5 -1
  16. package/lib/src/generated/api/ModelApiInput.d.ts +7 -1
  17. package/lib/src/generated/api/Notification.d.ts +5 -1
  18. package/lib/src/generated/api/NotificationInput.d.ts +4 -0
  19. package/lib/src/generated/api/PerspectiveEvent.d.ts +8 -0
  20. package/lib/src/generated/api/{PerspectiveLinkWithOwner.d.ts → PerspectiveLinkEvent.d.ts} +4 -2
  21. package/lib/src/generated/api/{PerspectiveLinkUpdatedWithOwner.d.ts → PerspectiveLinkUpdatedEvent.d.ts} +4 -2
  22. package/lib/src/generated/api/PerspectiveRemovedEvent.d.ts +7 -0
  23. package/lib/src/generated/api/RequestCapabilityRequest.d.ts +1 -0
  24. package/lib/src/generated/api/RpcMethods.d.ts +10 -1
  25. package/lib/src/generated/api/RuntimeInfo.d.ts +5 -0
  26. package/lib/src/generated/api/RuntimeUpdateNotificationParams.d.ts +6 -1
  27. package/lib/src/generated/api/UsersRevokeAllSessionsParams.d.ts +7 -0
  28. package/{src/generated/api/PerspectiveRemovedWithOwner.ts → lib/src/generated/api/UsersRevokeAllSessionsParams.js} +1 -2
  29. package/lib/src/index.d.ts +1 -0
  30. package/lib/src/index.js +1 -0
  31. package/lib/src/model/Ad4mModel.js +45 -18
  32. package/lib/src/model/ModelQueryBuilder.d.ts +7 -3
  33. package/lib/src/model/ModelQueryBuilder.js +9 -4
  34. package/lib/src/model/query-common.js +7 -1
  35. package/lib/src/model/types.d.ts +45 -2
  36. package/lib/src/model/types.js +8 -0
  37. package/lib/src/perspectives/Container.d.ts +41 -0
  38. package/lib/src/perspectives/Container.js +62 -0
  39. package/lib/src/perspectives/PerspectiveProxy.d.ts +6 -3
  40. package/lib/src/perspectives/PerspectiveProxy.js +10 -4
  41. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +94 -12
  42. package/lib/src/perspectives/WakerSubscriptionManager.js +276 -75
  43. package/lib/src/runtime/RuntimeClient.d.ts +6 -3
  44. package/lib/src/runtime/RuntimeClient.js +2 -0
  45. package/lib/src/runtime/RuntimeTypes.d.ts +7 -1
  46. package/package.json +2 -2
  47. package/src/Ad4mClient.test.ts +54 -19
  48. package/src/Ad4mClient.ts +10 -0
  49. package/src/agent/AgentClient.ts +26 -2
  50. package/src/ai/AITypes.ts +6 -2
  51. package/src/apiClient.test.ts +128 -3
  52. package/src/apiClient.ts +64 -11
  53. package/src/generated/api/Apps.ts +6 -1
  54. package/src/generated/api/AuthInfo.ts +6 -1
  55. package/src/generated/api/Events.ts +10 -12
  56. package/src/generated/api/FlowStateChangedEvent.ts +3 -2
  57. package/src/generated/api/Model.ts +4 -0
  58. package/src/generated/api/ModelApi.ts +5 -1
  59. package/src/generated/api/ModelApiInput.ts +8 -1
  60. package/src/generated/api/Notification.ts +5 -1
  61. package/src/generated/api/NotificationInput.ts +6 -1
  62. package/src/generated/api/PerspectiveEvent.ts +7 -0
  63. package/src/generated/api/{PerspectiveLinkUpdatedWithOwner.ts → PerspectiveLinkEvent.ts} +4 -1
  64. package/src/generated/api/PerspectiveLinkUpdatedEvent.ts +7 -0
  65. package/src/generated/api/PerspectiveRemovedEvent.ts +6 -0
  66. package/src/generated/api/RequestCapabilityRequest.ts +1 -1
  67. package/src/generated/api/RpcMethods.ts +4 -1
  68. package/src/generated/api/RuntimeInfo.ts +6 -1
  69. package/src/generated/api/RuntimeUpdateNotificationParams.ts +7 -1
  70. package/src/generated/api/UsersRevokeAllSessionsParams.ts +8 -0
  71. package/src/index.ts +1 -0
  72. package/src/model/Ad4mModel.ts +51 -19
  73. package/src/model/ModelQueryBuilder.ts +9 -6
  74. package/src/model/containment-scope.test.ts +104 -0
  75. package/src/model/query-common.ts +10 -1
  76. package/src/model/types.ts +56 -2
  77. package/src/perspectives/Container.test.ts +65 -0
  78. package/src/perspectives/Container.ts +46 -0
  79. package/src/perspectives/PerspectiveProxy.test.ts +11 -0
  80. package/src/perspectives/PerspectiveProxy.ts +10 -4
  81. package/src/perspectives/WakerSubscriptionManager.test.ts +400 -82
  82. package/src/perspectives/WakerSubscriptionManager.ts +321 -85
  83. package/src/perspectives/link-updated-type.test.ts +2 -2
  84. package/src/perspectives/listener-leaks.test.ts +3 -3
  85. package/src/runtime/RuntimeClient.ts +6 -3
  86. package/src/runtime/RuntimeTypes.ts +10 -1
  87. package/lib/src/generated/api/MessageReceivedEvent.d.ts +0 -7
  88. package/lib/src/generated/api/PerspectiveRemovedWithOwner.d.ts +0 -5
  89. package/lib/src/generated/api/PerspectiveWithOwner.d.ts +0 -6
  90. package/lib/src/generated/api/PerspectiveWithOwner.js +0 -1
  91. package/src/generated/api/MessageReceivedEvent.ts +0 -7
  92. package/src/generated/api/PerspectiveLinkWithOwner.ts +0 -4
  93. package/src/generated/api/PerspectiveWithOwner.ts +0 -4
  94. /package/lib/src/generated/api/{MessageReceivedEvent.js → PerspectiveEvent.js} +0 -0
  95. /package/lib/src/generated/api/{PerspectiveLinkUpdatedWithOwner.js → PerspectiveLinkEvent.js} +0 -0
  96. /package/lib/src/generated/api/{PerspectiveLinkWithOwner.js → PerspectiveLinkUpdatedEvent.js} +0 -0
  97. /package/lib/src/generated/api/{PerspectiveRemovedWithOwner.js → PerspectiveRemovedEvent.js} +0 -0
@@ -38,6 +38,13 @@ export declare class Ad4mClient {
38
38
  * handler.
39
39
  */
40
40
  on<K extends EventName>(type: K, handler: (event: EventMap[K]) => void, filter?: EventFilter): () => void;
41
+ /**
42
+ * Call `callback` once when the executor refuses this client's token
43
+ * (expired, revoked, or no session). Every call then fails with a 401
44
+ * `RpcError` and the client stops reconnecting: log in again and build a
45
+ * new client. Returns a function that removes the callback.
46
+ */
47
+ onAuthFailed(callback: (reason: string) => void): () => void;
41
48
  /** Close all event connections and clear in-memory caches */
42
49
  close(): void;
43
50
  }
@@ -95,6 +95,15 @@ export class Ad4mClient {
95
95
  on(type, handler, filter) {
96
96
  return __classPrivateFieldGet(this, _Ad4mClient_apiClient, "f").on(type, handler, filter);
97
97
  }
98
+ /**
99
+ * Call `callback` once when the executor refuses this client's token
100
+ * (expired, revoked, or no session). Every call then fails with a 401
101
+ * `RpcError` and the client stops reconnecting: log in again and build a
102
+ * new client. Returns a function that removes the callback.
103
+ */
104
+ onAuthFailed(callback) {
105
+ return __classPrivateFieldGet(this, _Ad4mClient_apiClient, "f").onAuthFailed(callback);
106
+ }
98
107
  /** Close all event connections and clear in-memory caches */
99
108
  close() {
100
109
  __classPrivateFieldGet(this, _Ad4mClient_agentClient, "f").clearByDidCache();
@@ -48,7 +48,14 @@ export declare class AgentClient {
48
48
  deleteEntanglementProofs(proofs: EntanglementProofInput[]): Promise<EntanglementProof[]>;
49
49
  getEntanglementProofs(): Promise<EntanglementProof[]>;
50
50
  entanglementProofPreFlight(deviceKey: string, deviceKeyType: string): Promise<EntanglementProof>;
51
- requestCapability(authInfo: AuthInfoInput): Promise<string>;
51
+ /**
52
+ * Asks the executor for a capability token. `agent` names the agent the token will act
53
+ * as: a managed user's email or an agent's DID; absent, the executor's main agent. That
54
+ * agent's owner approves the request (the operator for the main agent, the user for
55
+ * theirs). Returns the request id that {@link generateJwt} redeems with the approver's
56
+ * six-digit code.
57
+ */
58
+ requestCapability(authInfo: AuthInfoInput, agent?: string): Promise<string>;
52
59
  permitCapability(auth: string): Promise<string>;
53
60
  generateJwt(requestId: string, rand: string): Promise<string>;
54
61
  getApps(): Promise<Apps[]>;
@@ -60,6 +67,14 @@ export declare class AgentClient {
60
67
  loginUser(email: string, password: string): Promise<string>;
61
68
  requestLoginVerification(email: string, appInfo?: AuthInfoInput): Promise<VerificationRequestResult>;
62
69
  verifyEmailCode(email: string, code: string, verificationType: string): Promise<string>;
70
+ /** Revokes this client's user token. The executor then closes the client's sockets. */
71
+ logout(): Promise<boolean>;
72
+ /**
73
+ * Revokes every token of a user issued up to now, this client's own included, and closes
74
+ * their sockets. A user leaves out `email` (or names themselves); the operator names the
75
+ * user. Needs AGENT_UPDATE, which a login holds. Tokens from a later login work.
76
+ */
77
+ revokeAllSessions(email?: string): Promise<boolean>;
63
78
  hostingUserInfo(): Promise<HostingUserInfo>;
64
79
  computeLog(since?: string, limit?: number, userEmail?: string): Promise<ComputeLogEntry[]>;
65
80
  setHotWalletAddress(address: string): Promise<boolean>;
@@ -163,8 +163,15 @@ export class AgentClient {
163
163
  async entanglementProofPreFlight(deviceKey, deviceKeyType) {
164
164
  return __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.entanglementProofPreflight', { deviceKey, deviceKeyType });
165
165
  }
166
- async requestCapability(authInfo) {
167
- return __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.requestCapability', { authInfo });
166
+ /**
167
+ * Asks the executor for a capability token. `agent` names the agent the token will act
168
+ * as: a managed user's email or an agent's DID; absent, the executor's main agent. That
169
+ * agent's owner approves the request (the operator for the main agent, the user for
170
+ * theirs). Returns the request id that {@link generateJwt} redeems with the approver's
171
+ * six-digit code.
172
+ */
173
+ async requestCapability(authInfo, agent) {
174
+ return __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.requestCapability', agent === undefined ? { authInfo } : { authInfo, agent });
168
175
  }
169
176
  async permitCapability(auth) {
170
177
  return __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.permitCapability', { auth });
@@ -200,6 +207,18 @@ export class AgentClient {
200
207
  async verifyEmailCode(email, code, verificationType) {
201
208
  return __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('user.verifyEmail', { email, code, verificationType });
202
209
  }
210
+ /** Revokes this client's user token. The executor then closes the client's sockets. */
211
+ async logout() {
212
+ return __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('user.logout', {});
213
+ }
214
+ /**
215
+ * Revokes every token of a user issued up to now, this client's own included, and closes
216
+ * their sockets. A user leaves out `email` (or names themselves); the operator names the
217
+ * user. Needs AGENT_UPDATE, which a login holds. Tokens from a later login work.
218
+ */
219
+ async revokeAllSessions(email) {
220
+ return __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('user.revokeAllSessions', email === undefined ? {} : { email });
221
+ }
203
222
  // Hosting methods
204
223
  async hostingUserInfo() {
205
224
  const info = (await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('hosting.info', {})).userInfo ?? {
@@ -1,6 +1,7 @@
1
1
  export declare class ModelApi {
2
2
  baseUrl: string;
3
- apiKey: string;
3
+ /** Whether the model has a provider key. The executor never returns the key itself. */
4
+ hasApiKey: boolean;
4
5
  model: string;
5
6
  apiType: String;
6
7
  /** Optional ceiling for the provider's context window (tokens).
@@ -28,7 +29,10 @@ export declare class Model {
28
29
  }
29
30
  export declare class ModelApiInput {
30
31
  baseUrl: string;
31
- apiKey: string;
32
+ /** The provider key. Empty or left out on `addModel`: no key. Left out on
33
+ * `updateModel`: the stored key stays, and the update is refused if `baseUrl`
34
+ * changes too. Empty on `updateModel`: the stored key is removed. */
35
+ apiKey?: string;
32
36
  model: string;
33
37
  apiType: string;
34
38
  /** Optional ceiling for the provider's context window (tokens). */
@@ -47,6 +47,10 @@ export declare class ApiClient {
47
47
  /** `on()` handlers by event type; a type with none has no entry. */
48
48
  private _handlers;
49
49
  private _reconnectCallbacks;
50
+ private _authFailedCallbacks;
51
+ /** Set once the executor refused the token: the reason. The client then
52
+ * never connects again; a new token needs a new client. */
53
+ private _authFailed;
50
54
  private _hasConnectedOnce;
51
55
  private _pendingCalls;
52
56
  private _wsReconnectTimer;
@@ -61,7 +65,11 @@ export declare class ApiClient {
61
65
  private _getWsUrl;
62
66
  private _ensureWs;
63
67
  private _onOpen;
68
+ /** `reason` is set when the executor asked to try again later; calls that fail carry it. */
64
69
  private _onClose;
70
+ /** The executor refused the token: fail every call with 401, stop
71
+ * reconnecting and tell the `onAuthFailed` callbacks, once. */
72
+ private _failAuth;
65
73
  private _startPing;
66
74
  private _stopPing;
67
75
  private _scheduleReconnect;
@@ -102,6 +110,11 @@ export declare class ApiClient {
102
110
  * Does NOT fire on the initial connection — only on reconnects.
103
111
  * Returns an unsubscribe function. */
104
112
  onReconnect(callback: () => void): () => void;
113
+ /** Register a callback that fires once when the executor refuses this
114
+ * client's token: a 401 reply, or a socket closed with code 1008. Every
115
+ * call then fails with a 401 `RpcError` and the client does not reconnect;
116
+ * build a new client to use another token. Returns an unsubscribe function. */
117
+ onAuthFailed(callback: (reason: string) => void): () => void;
105
118
  /** Close the WebSocket and reject pending calls. */
106
119
  closeAll(): void;
107
120
  }
@@ -27,7 +27,12 @@ function nextId() {
27
27
  * for the next socket is safe for writes too. This covers an executor that
28
28
  * is still binding its port (about 1.5 s with the reconnect backoff). */
29
29
  const MAX_CONNECT_ATTEMPTS = 3;
30
- const closedError = () => new RpcError(503, 'WebSocket connection closed');
30
+ const closedError = (reason) => new RpcError(503, reason || 'WebSocket connection closed');
31
+ /** Close code for "try again later": the executor's wallet is locked, so it cannot check the
32
+ * token yet. The token may be good: reconnect as for any close, and pass the reason on. */
33
+ const CLOSE_TRY_AGAIN_LATER = 1013;
34
+ /** Close code the executor uses when the socket's token opens no session, expired or was revoked. */
35
+ const CLOSE_AUTH_FAILED = 1008;
31
36
  export class ApiClient {
32
37
  constructor(baseUrl, token, webSocketImpl, fetchImpl) {
33
38
  // ── WebSocket ───────────────────────────────────────────────────────────
@@ -38,6 +43,10 @@ export class ApiClient {
38
43
  /** `on()` handlers by event type; a type with none has no entry. */
39
44
  this._handlers = new Map();
40
45
  this._reconnectCallbacks = new Set();
46
+ this._authFailedCallbacks = new Set();
47
+ /** Set once the executor refused the token: the reason. The client then
48
+ * never connects again; a new token needs a new client. */
49
+ this._authFailed = null;
41
50
  this._hasConnectedOnce = false;
42
51
  this._pendingCalls = new Map();
43
52
  this._wsReconnectTimer = null;
@@ -73,6 +82,8 @@ export class ApiClient {
73
82
  _ensureWs() {
74
83
  if (this._ws)
75
84
  return;
85
+ if (this._authFailed !== null)
86
+ throw new RpcError(401, this._authFailed);
76
87
  const WsImpl = this._webSocketImpl ?? globalThis.WebSocket;
77
88
  const ws = new WsImpl(this._getWsUrl());
78
89
  this._ws = ws;
@@ -81,9 +92,17 @@ export class ApiClient {
81
92
  resolve();
82
93
  this._onOpen(ws);
83
94
  };
84
- ws.onclose = () => {
85
- reject(closedError());
86
- this._onClose(ws);
95
+ ws.onclose = (event) => {
96
+ // Classify the close for watchApplied() as for every other waiting call.
97
+ reject(event?.code === CLOSE_AUTH_FAILED
98
+ ? new RpcError(401, event.reason || 'token expired or revoked')
99
+ : closedError(event?.code === CLOSE_TRY_AGAIN_LATER ? event.reason : undefined));
100
+ if (event?.code === CLOSE_AUTH_FAILED && this._ws === ws) {
101
+ this._failAuth(event.reason || 'Unauthorized access: the token expired or was revoked');
102
+ }
103
+ else {
104
+ this._onClose(ws, event?.code === CLOSE_TRY_AGAIN_LATER ? event.reason : undefined);
105
+ }
87
106
  };
88
107
  });
89
108
  // Only watchApplied() awaits this; a close before open is not an error otherwise.
@@ -103,10 +122,15 @@ export class ApiClient {
103
122
  if (!pending)
104
123
  return; // late reply to a timed-out or aborted call, or a cancel ack
105
124
  const error = parsed.error;
106
- if (error)
107
- pending.reject(new RpcError(error.code ?? 500, error.message ?? 'Unknown error'));
108
- else
125
+ if (!error) {
109
126
  pending.resolve(parsed.result);
127
+ return;
128
+ }
129
+ const rpcError = new RpcError(error.code ?? 500, error.message ?? 'Unknown error');
130
+ pending.reject(rpcError);
131
+ // The executor answers 401 only when the token stopped working, then closes the socket.
132
+ if (rpcError.status === 401)
133
+ this._failAuth(rpcError.body);
110
134
  return;
111
135
  }
112
136
  if (parsed.type === 'pong')
@@ -155,7 +179,8 @@ export class ApiClient {
155
179
  }
156
180
  this._hasConnectedOnce = true;
157
181
  }
158
- _onClose(ws) {
182
+ /** `reason` is set when the executor asked to try again later; calls that fail carry it. */
183
+ _onClose(ws, reason) {
159
184
  // A socket closed by _closeWs() can report after a new one exists.
160
185
  if (this._ws !== ws)
161
186
  return;
@@ -170,12 +195,25 @@ export class ApiClient {
170
195
  pending.retry = false;
171
196
  }
172
197
  else {
173
- pending.reject(closedError());
198
+ pending.reject(closedError(reason));
174
199
  }
175
200
  }
176
201
  if (this._handlers.size > 0 || this._pendingCalls.size > 0)
177
202
  this._scheduleReconnect();
178
203
  }
204
+ /** The executor refused the token: fail every call with 401, stop
205
+ * reconnecting and tell the `onAuthFailed` callbacks, once. */
206
+ _failAuth(reason) {
207
+ if (this._authFailed !== null)
208
+ return;
209
+ this._authFailed = reason;
210
+ const error = new RpcError(401, reason);
211
+ for (const pending of this._pendingCalls.values())
212
+ pending.reject(error);
213
+ this._closeWs();
214
+ for (const cb of [...this._authFailedCallbacks])
215
+ callSafely(cb, 'Error in auth-failed callback:', reason);
216
+ }
179
217
  _startPing() {
180
218
  this._stopPing();
181
219
  this._wsPingTimer = setInterval(() => {
@@ -191,7 +229,7 @@ export class ApiClient {
191
229
  }
192
230
  }
193
231
  _scheduleReconnect() {
194
- if (this._wsReconnectTimer)
232
+ if (this._wsReconnectTimer || this._authFailed !== null)
195
233
  return;
196
234
  const delay = this._wsReconnectDelay;
197
235
  this._wsReconnectDelay = Math.min(this._wsReconnectDelay * 2, MAX_RECONNECT_DELAY_MS);
@@ -291,7 +329,9 @@ export class ApiClient {
291
329
  regs.add(reg);
292
330
  this._scheduleWatch();
293
331
  }
294
- this._ensureWs();
332
+ // A client whose token was refused keeps the handler but opens no socket.
333
+ if (this._authFailed === null)
334
+ this._ensureWs();
295
335
  return () => {
296
336
  const regs = this._handlers.get(type);
297
337
  if (!regs?.delete(reg))
@@ -358,10 +398,13 @@ export class ApiClient {
358
398
  if (key === this._watching)
359
399
  return;
360
400
  this._watching = key;
361
- this._watchSent = this._request('events.watch', events).then(() => { this._watchRetries = 0; }, (e) => {
401
+ const sent = this._request('events.watch', events).then(() => { this._watchRetries = 0; }, (e) => {
362
402
  if (this._watching !== key)
363
403
  return;
364
404
  this._watching = null;
405
+ // A refused token (401) gets no next socket: watchApplied() must not resolve.
406
+ if (e instanceof RpcError && e.status === 401)
407
+ throw e;
365
408
  // A closed socket (503) gets the watch again when the next one opens.
366
409
  if (e instanceof RpcError && e.status === 503)
367
410
  return;
@@ -373,6 +416,9 @@ export class ApiClient {
373
416
  }, WATCH_RETRY_DELAY_MS);
374
417
  }
375
418
  });
419
+ // Only watchApplied() awaits this; a refused watch is not an unhandled rejection otherwise.
420
+ sent.catch(() => { });
421
+ this._watchSent = sent;
376
422
  }
377
423
  _closeWs() {
378
424
  this._stopPing();
@@ -396,6 +442,14 @@ export class ApiClient {
396
442
  this._reconnectCallbacks.add(callback);
397
443
  return () => { this._reconnectCallbacks.delete(callback); };
398
444
  }
445
+ /** Register a callback that fires once when the executor refuses this
446
+ * client's token: a 401 reply, or a socket closed with code 1008. Every
447
+ * call then fails with a 401 `RpcError` and the client does not reconnect;
448
+ * build a new client to use another token. Returns an unsubscribe function. */
449
+ onAuthFailed(callback) {
450
+ this._authFailedCallbacks.add(callback);
451
+ return () => { this._authFailedCallbacks.delete(callback); };
452
+ }
399
453
  /** Close the WebSocket and reject pending calls. */
400
454
  closeAll() {
401
455
  for (const pending of this._pendingCalls.values()) {
@@ -404,6 +458,7 @@ export class ApiClient {
404
458
  this._closeWs();
405
459
  this._handlers.clear();
406
460
  this._reconnectCallbacks.clear();
461
+ this._authFailedCallbacks.clear();
407
462
  // A reused client must not fire onReconnect on its next first open.
408
463
  this._hasConnectedOnce = false;
409
464
  }
@@ -3,5 +3,9 @@ export type Apps = {
3
3
  auth: AuthInfo;
4
4
  requestId: string;
5
5
  revoked: boolean | null;
6
+ /**
7
+ * Always empty: the executor does not keep app tokens, and an app receives its token
8
+ * once, from `agent.generateJwt`. The field stays for clients that require it.
9
+ */
6
10
  token: string;
7
11
  };
@@ -6,5 +6,9 @@ export type AuthInfo = {
6
6
  appUrl: string | null;
7
7
  appIconPath: string | null;
8
8
  capabilities: Array<Capability> | null;
9
+ /**
10
+ * The user a multi-user token is minted for: the login name of a managed agent's
11
+ * account. The token's `sub` carries the agent's DID; this stays as the account's name.
12
+ */
9
13
  userEmail: string | null;
10
14
  };
@@ -7,14 +7,13 @@ import type { AutoProcessorNeighbourhoodState } from "./AutoProcessorNeighbourho
7
7
  import type { ExceptionOccurredEvent } from "./ExceptionOccurredEvent";
8
8
  import type { FlowStateChangedEvent } from "./FlowStateChangedEvent";
9
9
  import type { HostingUserInfo } from "./HostingUserInfo";
10
- import type { MessageReceivedEvent } from "./MessageReceivedEvent";
11
10
  import type { NeighbourhoodSignalFilter } from "./NeighbourhoodSignalFilter";
12
11
  import type { NotificationTriggeredEvent } from "./NotificationTriggeredEvent";
13
- import type { PerspectiveLinkUpdatedWithOwner } from "./PerspectiveLinkUpdatedWithOwner";
14
- import type { PerspectiveLinkWithOwner } from "./PerspectiveLinkWithOwner";
15
- import type { PerspectiveRemovedWithOwner } from "./PerspectiveRemovedWithOwner";
12
+ import type { PerspectiveEvent } from "./PerspectiveEvent";
13
+ import type { PerspectiveLinkEvent } from "./PerspectiveLinkEvent";
14
+ import type { PerspectiveLinkUpdatedEvent } from "./PerspectiveLinkUpdatedEvent";
15
+ import type { PerspectiveRemovedEvent } from "./PerspectiveRemovedEvent";
16
16
  import type { PerspectiveStateFilter } from "./PerspectiveStateFilter";
17
- import type { PerspectiveWithOwner } from "./PerspectiveWithOwner";
18
17
  import type { QuerySubscriptionUpdateEvent } from "./QuerySubscriptionUpdateEvent";
19
18
  import type { SfuCallRenegotiationOffer } from "./SfuCallRenegotiationOffer";
20
19
  import type { SfuDataMessage } from "./SfuDataMessage";
@@ -27,15 +26,14 @@ export interface EventMap {
27
26
  "agent-updated": AgentUpdatedEvent;
28
27
  "apps-changed": Apps;
29
28
  "hosting-user-info-changed": HostingUserInfo;
30
- "perspective-added": PerspectiveWithOwner;
31
- "perspective-removed": PerspectiveRemovedWithOwner;
32
- "perspective-updated": PerspectiveWithOwner;
29
+ "perspective-added": PerspectiveEvent;
30
+ "perspective-removed": PerspectiveRemovedEvent;
31
+ "perspective-updated": PerspectiveEvent;
33
32
  "sync-state-change": PerspectiveStateFilter;
34
- "link-added": PerspectiveLinkWithOwner;
35
- "link-removed": PerspectiveLinkWithOwner;
36
- "link-updated": PerspectiveLinkUpdatedWithOwner;
33
+ "link-added": PerspectiveLinkEvent;
34
+ "link-removed": PerspectiveLinkEvent;
35
+ "link-updated": PerspectiveLinkUpdatedEvent;
37
36
  "signal": NeighbourhoodSignalFilter;
38
- "message-received": MessageReceivedEvent;
39
37
  "notification-triggered": NotificationTriggeredEvent;
40
38
  "exception-occurred": ExceptionOccurredEvent;
41
39
  "transcription-text": TranscriptionTextFilter;
@@ -11,8 +11,9 @@
11
11
  export type FlowStateChangedEvent = {
12
12
  perspectiveUuid: string;
13
13
  /**
14
- * The agent whose replica derived this. The delivery filter matches it
15
- * against the socket's agent; nobody else receives the event.
14
+ * The agent whose replica derived this: the event's only recipient when it
15
+ * may read the perspective. Otherwise only the operator gets the main
16
+ * agent's event, and nobody gets another agent's.
16
17
  */
17
18
  agentDid: string;
18
19
  instance: string;
@@ -1,6 +1,10 @@
1
1
  import type { LocalModel } from "./LocalModel";
2
2
  import type { ModelApi } from "./ModelApi";
3
3
  import type { ModelType } from "./ModelType";
4
+ /**
5
+ * A model as RPC results show it. Its provider key never leaves the executor:
6
+ * `api.hasApiKey` says whether one is set.
7
+ */
4
8
  export type Model = {
5
9
  id: string;
6
10
  name: string;
@@ -1,7 +1,11 @@
1
1
  import type { ModelApiType } from "./ModelApiType";
2
+ /**
3
+ * A remote model's endpoint as RPC results show it: whether a provider key is set,
4
+ * never the key.
5
+ */
2
6
  export type ModelApi = {
3
7
  baseUrl: string;
4
- apiKey: string;
8
+ hasApiKey: boolean;
5
9
  model: string;
6
10
  apiType: ModelApiType;
7
11
  /**
@@ -1,6 +1,12 @@
1
1
  export type ModelApiInput = {
2
2
  baseUrl: string;
3
- apiKey: string;
3
+ /**
4
+ * The provider key. An empty key stores no key, and so does `ai.addModel` without
5
+ * one. `ai.updateModel` without one keeps the stored key; it refuses the update if
6
+ * `baseUrl` changes too, because a key goes only to the endpoint it was set for.
7
+ * Never serialised back out.
8
+ */
9
+ apiKey?: string;
4
10
  model: string;
5
11
  apiType: string;
6
12
  /**
@@ -1,3 +1,7 @@
1
+ /**
2
+ * A notification as RPC results and events show it: whether a webhook credential is
3
+ * set, never the credential.
4
+ */
1
5
  export type Notification = {
2
6
  id: string;
3
7
  granted: boolean;
@@ -8,7 +12,7 @@ export type Notification = {
8
12
  trigger: string;
9
13
  perspectiveIds: Array<string>;
10
14
  webhookUrl: string;
11
- webhookAuth: string;
15
+ hasWebhookAuth: boolean;
12
16
  /**
13
17
  * The owner's DID: a managed user's, or the main agent's.
14
18
  */
@@ -6,5 +6,9 @@ export type NotificationInput = {
6
6
  trigger: string;
7
7
  perspectiveIds: Array<string>;
8
8
  webhookUrl: string;
9
+ /**
10
+ * Sent as the bearer credential to `webhookUrl`. Results and events say only
11
+ * whether one is set (`hasWebhookAuth`).
12
+ */
9
13
  webhookAuth: string;
10
14
  };
@@ -0,0 +1,8 @@
1
+ import type { PerspectiveHandle } from "./PerspectiveHandle";
2
+ /**
3
+ * `perspective-added` / `perspective-updated`: one event to all of the perspective's owners.
4
+ */
5
+ export type PerspectiveEvent = {
6
+ perspectiveUuid: string;
7
+ perspective: PerspectiveHandle;
8
+ };
@@ -1,6 +1,8 @@
1
1
  import type { DecoratedLinkExpression } from "./DecoratedLinkExpression";
2
- export type PerspectiveLinkWithOwner = {
2
+ /**
3
+ * `link-added` / `link-removed`: one event to all of the perspective's owners.
4
+ */
5
+ export type PerspectiveLinkEvent = {
3
6
  perspectiveUuid: string;
4
7
  link: DecoratedLinkExpression;
5
- owner: string;
6
8
  };
@@ -1,7 +1,9 @@
1
1
  import type { DecoratedLinkExpression } from "./DecoratedLinkExpression";
2
- export type PerspectiveLinkUpdatedWithOwner = {
2
+ /**
3
+ * `link-updated`: one event to all of the perspective's owners.
4
+ */
5
+ export type PerspectiveLinkUpdatedEvent = {
3
6
  perspectiveUuid: string;
4
7
  newLink: DecoratedLinkExpression;
5
8
  oldLink: DecoratedLinkExpression;
6
- owner: string;
7
9
  };
@@ -0,0 +1,7 @@
1
+ /**
2
+ * `perspective-removed`: one event to all of the perspective's owners.
3
+ */
4
+ export type PerspectiveRemovedEvent = {
5
+ perspectiveUuid: string;
6
+ uuid: string;
7
+ };
@@ -1,4 +1,5 @@
1
1
  import type { AuthInfoInput } from "./AuthInfoInput";
2
2
  export type RequestCapabilityRequest = {
3
3
  authInfo: AuthInfoInput;
4
+ agent?: string;
4
5
  };
@@ -172,6 +172,7 @@ import type { UsersEmailTestParams } from "./UsersEmailTestParams";
172
172
  import type { UsersEmailTestResult } from "./UsersEmailTestResult";
173
173
  import type { UsersLoginParams } from "./UsersLoginParams";
174
174
  import type { UsersRequestVerificationParams } from "./UsersRequestVerificationParams";
175
+ import type { UsersRevokeAllSessionsParams } from "./UsersRevokeAllSessionsParams";
175
176
  import type { UsersSetCreditsParams } from "./UsersSetCreditsParams";
176
177
  import type { UsersVerifyEmailParams } from "./UsersVerifyEmailParams";
177
178
  import type { ValidOutput } from "./ValidOutput";
@@ -743,7 +744,7 @@ export interface RpcMethods {
743
744
  };
744
745
  "runtime.linkLanguageTemplates": {
745
746
  params: Record<string, never>;
746
- result: Array<string>;
747
+ result: Array<LanguageMeta>;
747
748
  };
748
749
  "runtime.networkMetrics": {
749
750
  params: Record<string, never>;
@@ -933,6 +934,10 @@ export interface RpcMethods {
933
934
  params: UsersLoginParams;
934
935
  result: string;
935
936
  };
937
+ "user.logout": {
938
+ params: Record<string, never>;
939
+ result: boolean;
940
+ };
936
941
  "user.multiUserEnabled": {
937
942
  params: Record<string, never>;
938
943
  result: boolean;
@@ -941,6 +946,10 @@ export interface RpcMethods {
941
946
  params: UsersRequestVerificationParams;
942
947
  result: VerificationRequestResult;
943
948
  };
949
+ "user.revokeAllSessions": {
950
+ params: UsersRevokeAllSessionsParams;
951
+ result: boolean;
952
+ };
944
953
  "user.setMultiUserEnabled": {
945
954
  params: SetMultiUserRequest;
946
955
  result: boolean;
@@ -1,5 +1,10 @@
1
1
  export type RuntimeInfo = {
2
2
  ad4mExecutorVersion: string;
3
+ /**
4
+ * The commit the executor was built from, or nothing when the build could not tell (no git
5
+ * checkout). Every build between two releases reports one version; this names the build.
6
+ */
7
+ ad4mExecutorCommit: string | null;
3
8
  isInitialized: boolean;
4
9
  isUnlocked: boolean;
5
10
  };
@@ -7,5 +7,10 @@ export type RuntimeUpdateNotificationParams = {
7
7
  trigger: string;
8
8
  perspectiveIds: Array<string>;
9
9
  webhookUrl: string;
10
- webhookAuth: string;
10
+ /**
11
+ * Without it the update keeps the stored credential, and fails if `webhookUrl`
12
+ * changes too, because a credential goes only to the webhook it was set for. An empty
13
+ * string clears it.
14
+ */
15
+ webhookAuth?: string;
11
16
  };
@@ -0,0 +1,7 @@
1
+ export type UsersRevokeAllSessionsParams = {
2
+ /**
3
+ * The user whose sessions to revoke. A user may leave it out or name themselves; the
4
+ * operator must name the user.
5
+ */
6
+ email?: string;
7
+ };
@@ -1,3 +1,2 @@
1
1
  // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
-
3
- export type PerspectiveRemovedWithOwner = { perspectiveUuid: string, uuid: string, owner: string, };
2
+ export {};
@@ -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/Container";
24
25
  export * from "./perspectives/FlowInstance";
25
26
  export * from "./perspectives/SparqlBindings";
26
27
  export * from "./perspectives/WakerSubscriptionManager";
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/Container";
24
25
  // Also exports FlowFireOutcome / FlowProposeResult, the result shapes of the
25
26
  // flow write API — they live beside the `proposeTransition()` surface.
26
27
  export * from "./perspectives/FlowInstance";