@coasys/ad4m 0.13.1-staging.7 → 0.13.1-staging.9

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 (93) hide show
  1. package/lib/index.cjs +652 -147
  2. package/lib/index.js +648 -148
  3. package/lib/src/agent/AgentClient.d.ts +6 -0
  4. package/lib/src/agent/AgentClient.js +17 -0
  5. package/lib/src/agent/AgentKind.d.ts +17 -0
  6. package/lib/src/agent/AgentKind.js +21 -0
  7. package/lib/src/apiClient.d.ts +4 -1
  8. package/lib/src/apiClient.js +13 -4
  9. package/lib/src/generated/api/CallSessionInfo.d.ts +1 -1
  10. package/lib/src/generated/api/Events.d.ts +2 -0
  11. package/lib/src/generated/api/PerspectiveModelSubscribeParams.d.ts +11 -0
  12. package/lib/src/generated/api/PerspectiveModelSubscribeParams.js +2 -0
  13. package/lib/src/generated/api/PerspectiveSubscribeQueryParams.d.ts +9 -0
  14. package/lib/src/generated/api/PerspectiveSubscribeQueryParams.js +2 -0
  15. package/lib/src/generated/api/RpcMethods.d.ts +10 -4
  16. package/lib/src/generated/api/RpcMethods.js +5 -0
  17. package/lib/src/generated/api/SfuAddIceCandidateParams.d.ts +4 -0
  18. package/lib/src/generated/api/SfuAnswerServerOfferParams.d.ts +4 -0
  19. package/lib/src/generated/api/SfuCallJoinParams.d.ts +13 -0
  20. package/lib/src/generated/api/SfuCallLeaveParams.d.ts +12 -0
  21. package/lib/src/generated/api/SfuCallLeaveParams.js +2 -0
  22. package/lib/src/generated/api/SfuCallRenegotiationOffer.d.ts +5 -0
  23. package/lib/src/generated/api/SfuDataMessage.d.ts +6 -0
  24. package/lib/src/generated/api/SfuQualityPreferenceParams.d.ts +4 -0
  25. package/lib/src/generated/api/SfuRestartIceParams.d.ts +12 -0
  26. package/lib/src/generated/api/SfuRestartIceParams.js +2 -0
  27. package/lib/src/generated/api/SfuRoomParticipantInfo.d.ts +4 -0
  28. package/lib/src/generated/api/SfuRoomRoster.d.ts +6 -2
  29. package/lib/src/generated/api/SfuRoomRoster.js +0 -1
  30. package/lib/src/generated/api/SfuRosterParticipant.d.ts +7 -0
  31. package/lib/src/generated/api/SfuRosterParticipant.js +2 -0
  32. package/lib/src/generated/api/SfuSendDataParams.d.ts +4 -0
  33. package/lib/src/generated/api/SfuSessionReplaced.d.ts +15 -0
  34. package/lib/src/generated/api/SfuSessionReplaced.js +2 -0
  35. package/lib/src/generated/api/SubscribeQueryRequest.d.ts +4 -0
  36. package/lib/src/generated/api/TrackMapEntry.d.ts +6 -1
  37. package/lib/src/generated/api/index.d.ts +1 -1
  38. package/lib/src/generated/api/index.js +1 -1
  39. package/lib/src/index.d.ts +1 -0
  40. package/lib/src/index.js +1 -0
  41. package/lib/src/neighbourhood/MeshManager.d.ts +19 -2
  42. package/lib/src/neighbourhood/MeshManager.js +55 -8
  43. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +34 -13
  44. package/lib/src/neighbourhood/NeighbourhoodClient.js +44 -14
  45. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +15 -7
  46. package/lib/src/neighbourhood/NeighbourhoodProxy.js +26 -13
  47. package/lib/src/neighbourhood/Session.d.ts +24 -5
  48. package/lib/src/neighbourhood/Session.js +179 -35
  49. package/lib/src/neighbourhood/SfuManager.d.ts +98 -28
  50. package/lib/src/neighbourhood/SfuManager.js +258 -71
  51. package/lib/src/neighbourhood/SfuTypes.d.ts +4 -0
  52. package/lib/src/perspectives/PerspectiveClient.js +33 -4
  53. package/package.json +2 -2
  54. package/src/Ad4mClient.test.ts +5 -5
  55. package/src/agent/AgentClient.ts +20 -0
  56. package/src/agent/AgentKind.ts +28 -0
  57. package/src/agent/mutatePublicPerspective.test.ts +72 -0
  58. package/src/apiClient.test.ts +46 -0
  59. package/src/apiClient.ts +16 -5
  60. package/src/generated/api/CallSessionInfo.ts +1 -1
  61. package/src/generated/api/Events.ts +2 -0
  62. package/src/generated/api/PerspectiveModelSubscribeParams.ts +7 -0
  63. package/src/generated/api/PerspectiveSubscribeQueryParams.ts +7 -0
  64. package/src/generated/api/RpcMethods.ts +14 -4
  65. package/src/generated/api/SfuAddIceCandidateParams.ts +4 -0
  66. package/src/generated/api/SfuAnswerServerOfferParams.ts +4 -0
  67. package/src/generated/api/SfuCallJoinParams.ts +13 -0
  68. package/src/generated/api/SfuCallLeaveParams.ts +11 -0
  69. package/src/generated/api/SfuCallRenegotiationOffer.ts +6 -1
  70. package/src/generated/api/SfuDataMessage.ts +7 -1
  71. package/src/generated/api/SfuQualityPreferenceParams.ts +4 -0
  72. package/src/generated/api/SfuRestartIceParams.ts +11 -0
  73. package/src/generated/api/SfuRoomParticipantInfo.ts +5 -1
  74. package/src/generated/api/SfuRoomRoster.ts +6 -2
  75. package/src/generated/api/SfuRosterParticipant.ts +6 -0
  76. package/src/generated/api/SfuSendDataParams.ts +5 -1
  77. package/src/generated/api/SfuSessionReplaced.ts +13 -0
  78. package/src/generated/api/SubscribeQueryRequest.ts +5 -1
  79. package/src/generated/api/TrackMapEntry.ts +6 -1
  80. package/src/generated/api/index.ts +1 -1
  81. package/src/index.ts +1 -0
  82. package/src/neighbourhood/MeshManager.test.ts +101 -25
  83. package/src/neighbourhood/MeshManager.ts +56 -7
  84. package/src/neighbourhood/NeighbourhoodClient.test.ts +45 -15
  85. package/src/neighbourhood/NeighbourhoodClient.ts +49 -9
  86. package/src/neighbourhood/NeighbourhoodProxy.ts +29 -6
  87. package/src/neighbourhood/Session.test.ts +388 -36
  88. package/src/neighbourhood/Session.ts +185 -38
  89. package/src/neighbourhood/SfuManager.test.ts +626 -20
  90. package/src/neighbourhood/SfuManager.ts +275 -67
  91. package/src/neighbourhood/SfuTypes.ts +4 -0
  92. package/src/perspectives/PerspectiveClient.ts +36 -4
  93. package/src/perspectives/abandoned-subscribe.test.ts +219 -0
@@ -132,9 +132,37 @@ export function parseCallMessage(payload) {
132
132
  // ── Signalling channel ──────────────────────────────────────────────
133
133
  const RTC_PREDICATE = "ad4m://session/rtc";
134
134
  const TARGET_ALL = "*";
135
+ /**
136
+ * A mesh peer: one agent on one device. An agent calling from two devices is
137
+ * two peers, each with its own connection to everyone else, so neither device's
138
+ * media or teardown can stand in for the other's.
139
+ */
140
+ export function meshPeerId(did, device) {
141
+ if (!isMeshDevice(device))
142
+ throw new Error(`mesh: device id must be non-empty and without '#': ${JSON.stringify(device)}`);
143
+ return `${did}#${device}`;
144
+ }
145
+ /** A device id a mesh peer id can carry: `#` would move the split in {@link agentOfMeshPeer}. */
146
+ function isMeshDevice(device) {
147
+ return typeof device === "string" && device.length > 0 && !device.includes("#");
148
+ }
149
+ /** The agent a mesh peer id belongs to. */
150
+ export function agentOfMeshPeer(peerId) {
151
+ const at = peerId.lastIndexOf("#");
152
+ return at === -1 ? peerId : peerId.slice(0, at);
153
+ }
135
154
  /**
136
155
  * Bridge NeighbourhoodProxy telepresence to the SignallingChannel
137
- * the mesh consumes.
156
+ * the mesh consumes, as the peer `selfDid` on `selfDevice`.
157
+ *
158
+ * ## Peers are devices
159
+ *
160
+ * The sender a message reports is a {@link meshPeerId}: the link's author,
161
+ * which the executor verified, and the device the author's payload names. A
162
+ * device is only the author's own claim, so it can tell this agent's devices
163
+ * apart but never speak for another agent. Only this device's own echo is
164
+ * dropped: a broadcast from another device of this agent — the executor hands
165
+ * one to every client of the agent — is a peer like any other.
138
166
  *
139
167
  * ## Why unicast runs emulated over broadcast
140
168
  *
@@ -144,9 +172,11 @@ const TARGET_ALL = "*";
144
172
  * receivers drop anything not addressed to them. That provides
145
173
  * **addressing, not privacy** — every peer still receives the payload.
146
174
  */
147
- export function createTelepresenceChannel(proxy, selfDid) {
175
+ export function createTelepresenceChannel(proxy, selfDid, selfDevice) {
176
+ const self = meshPeerId(selfDid, selfDevice);
148
177
  const resultListeners = new Set();
149
178
  let subscribed = Promise.resolve();
179
+ let warnedNoDevice = false;
150
180
  const report = (result) => {
151
181
  for (const cb of resultListeners) {
152
182
  try {
@@ -166,7 +196,7 @@ export function createTelepresenceChannel(proxy, selfDid) {
166
196
  try {
167
197
  sent = proxy.sendBroadcastU({
168
198
  links: [{
169
- source: JSON.stringify(payload),
199
+ source: JSON.stringify({ device: selfDevice, message: payload }),
170
200
  predicate: RTC_PREDICATE,
171
201
  target: to?.agentId ?? TARGET_ALL,
172
202
  }],
@@ -203,10 +233,7 @@ export function createTelepresenceChannel(proxy, selfDid) {
203
233
  if (typeof predicate !== "string" || predicate !== RTC_PREDICATE)
204
234
  return;
205
235
  // Emulated unicast: drop messages addressed to someone else
206
- if (target && target !== TARGET_ALL && target !== selfDid)
207
- return;
208
- // Drop our own echo
209
- if (link.author === selfDid)
236
+ if (target && target !== TARGET_ALL && target !== self)
210
237
  return;
211
238
  let parsed;
212
239
  try {
@@ -215,7 +242,22 @@ export function createTelepresenceChannel(proxy, selfDid) {
215
242
  catch {
216
243
  return;
217
244
  }
218
- cb(link.author, parsed);
245
+ if (typeof parsed !== "object" || parsed === null)
246
+ return;
247
+ const { device, message } = parsed;
248
+ if (!isMeshDevice(device)) {
249
+ // An SDK from before peers were devices sends none: say so once, or a mixed call just looks empty.
250
+ if (device === undefined && !warnedNoDevice) {
251
+ warnedNoDevice = true;
252
+ console.warn(`mesh: ${link.author} sends no device id (an older SDK); its mesh messages are ignored`);
253
+ }
254
+ return;
255
+ }
256
+ const from = meshPeerId(link.author, device);
257
+ // Drop this device's own echo, and only that.
258
+ if (from === self)
259
+ return;
260
+ cb(from, message);
219
261
  };
220
262
  subscribed = proxy.addSignalHandler(handler).catch((err) => {
221
263
  console.warn("mesh: signal handler registration failed — inbound traffic will get missed:", err);
@@ -414,6 +456,9 @@ export class MeshManager {
414
456
  });
415
457
  // A session announces itself once `join` returns; peers offer at once.
416
458
  await this.channel.listening?.();
459
+ // Left or destroyed while the channel came up: start nothing.
460
+ if (this.closed)
461
+ return;
417
462
  /*
418
463
  * Spend the transport's first-send cost on something that does not
419
464
  * matter. The first broadcast on a freshly joined neighbourhood has
@@ -573,6 +618,8 @@ export class MeshManager {
573
618
  handleData(from, message) {
574
619
  const msg = {
575
620
  senderDid: from,
621
+ // The mesh keys its peers by DID: one session per agent.
622
+ senderParticipantId: from,
576
623
  neighbourhoodUrl: "",
577
624
  roomName: this.callId,
578
625
  channelLabel: message.label,
@@ -4,7 +4,7 @@ import { DID } from "../DID";
4
4
  import { OnlineAgent, TelepresenceSignalCallback } from "../language/Language";
5
5
  import { Perspective, PerspectiveExpression, PerspectiveUnsignedInput } from "../perspectives/Perspective";
6
6
  import { PerspectiveHandle } from "../perspectives/PerspectiveHandle";
7
- import type { CallSessionInfo, SfuCallRenegotiationOffer, SfuCascadeStatus, SfuConfig, SfuDataMessage, SfuMigrateEvent, SfuParticipantQualityPreference, SfuQualityPreference, SfuRoomInfo, SfuRoomRoster, SfuStatus } from "./SfuTypes";
7
+ import type { CallSessionInfo, SfuCallRenegotiationOffer, SfuCascadeStatus, SfuConfig, SfuDataMessage, SfuMigrateEvent, SfuParticipantQualityPreference, SfuQualityPreference, SfuRoomInfo, SfuRoomRoster, SfuSessionReplaced, SfuStatus } from "./SfuTypes";
8
8
  export declare class NeighbourhoodClient {
9
9
  #private;
10
10
  constructor(baseUrl: string, token?: string, sharedApiClient?: ApiClient);
@@ -28,14 +28,24 @@ export declare class NeighbourhoodClient {
28
28
  sfuStartRoom(neighbourhoodUrl: string, roomName: string): Promise<SfuRoomInfo>;
29
29
  sfuStopRoom(neighbourhoodUrl: string, roomName: string): Promise<boolean>;
30
30
  sfuListRooms(): Promise<SfuRoomInfo[]>;
31
- sfuCallJoin(neighbourhoodUrl: string, roomName: string, sdpOffer: string): Promise<CallSessionInfo>;
32
- sfuCallLeave(neighbourhoodUrl: string, roomName: string): Promise<boolean>;
33
- sfuCallSetQualityPreference(neighbourhoodUrl: string, roomName: string, preference: SfuQualityPreference): Promise<boolean>;
34
- sfuCallAnswerServerOffer(neighbourhoodUrl: string, roomName: string, sdpAnswer: string): Promise<boolean>;
35
- /** Ask the SFU to restart ICE on this agent's call connection. The offer
36
- * arrives as an `sfu-call-renegotiation-offer` event; answer it with
37
- * {@link sfuCallAnswerServerOffer}. */
38
- sfuCallRestartIce(neighbourhoodUrl: string, roomName: string): Promise<boolean>;
31
+ /**
32
+ * Join a call from `deviceId`. The executor replaces this agent's session
33
+ * from the same device (another tab) and keeps those from other devices.
34
+ * The result's `participantId` names the session in every later call.
35
+ * `sessionKey` is the caller's random key for the session: a rebuild
36
+ * sends it again; a key a later join from this device replaced is
37
+ * refused with `RpcError` status 409, and that session must stop.
38
+ */
39
+ sfuCallJoin(neighbourhoodUrl: string, roomName: string, sdpOffer: string, deviceId: string, sessionKey: string): Promise<CallSessionInfo>;
40
+ /** Leave the session `participantId`; `false` when it is not this agent's or is gone already. */
41
+ sfuCallLeave(neighbourhoodUrl: string, roomName: string, participantId: string): Promise<boolean>;
42
+ sfuCallSetQualityPreference(neighbourhoodUrl: string, roomName: string, participantId: string, preference: SfuQualityPreference): Promise<boolean>;
43
+ sfuCallAnswerServerOffer(neighbourhoodUrl: string, roomName: string, participantId: string, sdpAnswer: string): Promise<boolean>;
44
+ /** Ask the SFU to restart ICE on the session `participantId` (this
45
+ * agent's, as its join returned it; any other is refused). The offer
46
+ * arrives as an `sfu-call-renegotiation-offer` event for that session;
47
+ * answer it with {@link sfuCallAnswerServerOffer}. */
48
+ sfuCallRestartIce(neighbourhoodUrl: string, roomName: string, participantId: string): Promise<boolean>;
39
49
  /** Fires after a network change, once the client's socket is back on
40
50
  * the new network. See {@link ApiClient.onNetworkChange}. */
41
51
  onNetworkChange(callback: () => void): () => void;
@@ -54,21 +64,30 @@ export declare class NeighbourhoodClient {
54
64
  * complete (which can take up to 8 seconds on restrictive
55
65
  * networks).
56
66
  */
57
- sfuAddIceCandidate(neighbourhoodUrl: string, roomName: string, candidate: string): Promise<boolean>;
67
+ sfuAddIceCandidate(neighbourhoodUrl: string, roomName: string, participantId: string, candidate: string): Promise<boolean>;
58
68
  /**
59
69
  * Send data through the SFU to all other participants in the room.
60
70
  * The server relays it to their matching data channel and
61
71
  * publishes it as an `sfu-data` event.
62
72
  */
63
- sfuSendData(neighbourhoodUrl: string, roomName: string, channelLabel: string, data: string, binary?: boolean): Promise<boolean>;
73
+ sfuSendData(neighbourhoodUrl: string, roomName: string, participantId: string, channelLabel: string, data: string, binary?: boolean): Promise<boolean>;
64
74
  /**
65
75
  * Subscribe to SFU data channel messages. Returns an unsubscribe
66
76
  * function. Messages arrive for every participant in the room;
67
- * filter by `senderDid` if needed.
77
+ * filter by `senderDid` or `senderParticipantId` if needed. One sent by
78
+ * a session of this agent arrives here when the agent is in the call on
79
+ * another device too: it carries the sending session's participant id.
68
80
  */
69
81
  subscribeSfuDataChannel(callback: (message: SfuDataMessage) => void): () => void;
70
- /** Subscribe to the rosters of the call rooms this agent is in: who is in each, whenever that changes. */
82
+ /** Subscribe to the rosters of the call rooms this agent is in: who is in each, by session, whenever that changes. */
71
83
  subscribeSfuRoomRoster(callback: (roster: SfuRoomRoster) => void): () => void;
84
+ /**
85
+ * Subscribe to the executor's notice that a session of this agent was
86
+ * replaced: a later join from the same device took its call over. The
87
+ * notice names the replaced session's participant id; the session that
88
+ * holds it stops and does not rejoin.
89
+ */
90
+ subscribeSfuSessionReplaced(callback: (event: SfuSessionReplaced) => void): () => void;
72
91
  /**
73
92
  * Subscribe to server-pushed SFU SDP renegotiation offers. The
74
93
  * server publishes an `sfu-call-renegotiation-offer` event every
@@ -78,6 +97,8 @@ export declare class NeighbourhoodClient {
78
97
  *
79
98
  * The executor already sends each socket only its own DID's offers;
80
99
  * this subscription additionally filters on `targetDid` for safety.
100
+ * An agent in the call on two devices gets the offers of both: each
101
+ * names the session it is for (`participantId`).
81
102
  * Returns an unsubscribe function.
82
103
  */
83
104
  subscribeSfuCallRenegotiationOffer(targetDid: string, callback: (payload: SfuCallRenegotiationOffer) => void): () => void;
@@ -132,35 +132,49 @@ export class NeighbourhoodClient {
132
132
  async sfuListRooms() {
133
133
  return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").call("sfu.listRooms", {});
134
134
  }
135
- async sfuCallJoin(neighbourhoodUrl, roomName, sdpOffer) {
135
+ /**
136
+ * Join a call from `deviceId`. The executor replaces this agent's session
137
+ * from the same device (another tab) and keeps those from other devices.
138
+ * The result's `participantId` names the session in every later call.
139
+ * `sessionKey` is the caller's random key for the session: a rebuild
140
+ * sends it again; a key a later join from this device replaced is
141
+ * refused with `RpcError` status 409, and that session must stop.
142
+ */
143
+ async sfuCallJoin(neighbourhoodUrl, roomName, sdpOffer, deviceId, sessionKey) {
136
144
  return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").call("sfu.callJoin", {
137
145
  neighbourhoodUrl,
138
146
  roomName,
139
147
  sdpOffer,
148
+ deviceId,
149
+ sessionKey,
140
150
  });
141
151
  }
142
- async sfuCallLeave(neighbourhoodUrl, roomName) {
143
- return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").call("sfu.callLeave", { neighbourhoodUrl, roomName });
152
+ /** Leave the session `participantId`; `false` when it is not this agent's or is gone already. */
153
+ async sfuCallLeave(neighbourhoodUrl, roomName, participantId) {
154
+ return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").call("sfu.callLeave", { neighbourhoodUrl, roomName, participantId });
144
155
  }
145
- async sfuCallSetQualityPreference(neighbourhoodUrl, roomName, preference) {
156
+ async sfuCallSetQualityPreference(neighbourhoodUrl, roomName, participantId, preference) {
146
157
  return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").call("sfu.callSetQualityPreference", {
147
158
  neighbourhoodUrl,
148
159
  roomName,
160
+ participantId,
149
161
  preference,
150
162
  });
151
163
  }
152
- async sfuCallAnswerServerOffer(neighbourhoodUrl, roomName, sdpAnswer) {
164
+ async sfuCallAnswerServerOffer(neighbourhoodUrl, roomName, participantId, sdpAnswer) {
153
165
  return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").call("sfu.callAnswerServerOffer", {
154
166
  neighbourhoodUrl,
155
167
  roomName,
168
+ participantId,
156
169
  sdpAnswer,
157
170
  });
158
171
  }
159
- /** Ask the SFU to restart ICE on this agent's call connection. The offer
160
- * arrives as an `sfu-call-renegotiation-offer` event; answer it with
161
- * {@link sfuCallAnswerServerOffer}. */
162
- async sfuCallRestartIce(neighbourhoodUrl, roomName) {
163
- return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").call("sfu.callRestartIce", { neighbourhoodUrl, roomName });
172
+ /** Ask the SFU to restart ICE on the session `participantId` (this
173
+ * agent's, as its join returned it; any other is refused). The offer
174
+ * arrives as an `sfu-call-renegotiation-offer` event for that session;
175
+ * answer it with {@link sfuCallAnswerServerOffer}. */
176
+ async sfuCallRestartIce(neighbourhoodUrl, roomName, participantId) {
177
+ return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").call("sfu.callRestartIce", { neighbourhoodUrl, roomName, participantId });
164
178
  }
165
179
  /** Fires after a network change, once the client's socket is back on
166
180
  * the new network. See {@link ApiClient.onNetworkChange}. */
@@ -193,10 +207,11 @@ export class NeighbourhoodClient {
193
207
  * complete (which can take up to 8 seconds on restrictive
194
208
  * networks).
195
209
  */
196
- async sfuAddIceCandidate(neighbourhoodUrl, roomName, candidate) {
210
+ async sfuAddIceCandidate(neighbourhoodUrl, roomName, participantId, candidate) {
197
211
  return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").call("sfu.addIceCandidate", {
198
212
  neighbourhoodUrl,
199
213
  roomName,
214
+ participantId,
200
215
  candidate,
201
216
  });
202
217
  }
@@ -206,10 +221,11 @@ export class NeighbourhoodClient {
206
221
  * The server relays it to their matching data channel and
207
222
  * publishes it as an `sfu-data` event.
208
223
  */
209
- async sfuSendData(neighbourhoodUrl, roomName, channelLabel, data, binary = false) {
224
+ async sfuSendData(neighbourhoodUrl, roomName, participantId, channelLabel, data, binary = false) {
210
225
  return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").call("sfu.sendData", {
211
226
  neighbourhoodUrl,
212
227
  roomName,
228
+ participantId,
213
229
  channelLabel,
214
230
  data,
215
231
  binary,
@@ -218,17 +234,28 @@ export class NeighbourhoodClient {
218
234
  /**
219
235
  * Subscribe to SFU data channel messages. Returns an unsubscribe
220
236
  * function. Messages arrive for every participant in the room;
221
- * filter by `senderDid` if needed.
237
+ * filter by `senderDid` or `senderParticipantId` if needed. One sent by
238
+ * a session of this agent arrives here when the agent is in the call on
239
+ * another device too: it carries the sending session's participant id.
222
240
  */
223
241
  subscribeSfuDataChannel(callback) {
224
242
  // A fresh handler per call: `on` merges a repeated handler, and
225
243
  // each subscription must own its unsubscribe.
226
244
  return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").on("sfu-data", (message) => callback(message));
227
245
  }
228
- /** Subscribe to the rosters of the call rooms this agent is in: who is in each, whenever that changes. */
246
+ /** Subscribe to the rosters of the call rooms this agent is in: who is in each, by session, whenever that changes. */
229
247
  subscribeSfuRoomRoster(callback) {
230
248
  return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").on("sfu-room-roster", (roster) => callback(roster));
231
249
  }
250
+ /**
251
+ * Subscribe to the executor's notice that a session of this agent was
252
+ * replaced: a later join from the same device took its call over. The
253
+ * notice names the replaced session's participant id; the session that
254
+ * holds it stops and does not rejoin.
255
+ */
256
+ subscribeSfuSessionReplaced(callback) {
257
+ return __classPrivateFieldGet(this, _NeighbourhoodClient_apiClient, "f").on("sfu-session-replaced", (event) => callback(event));
258
+ }
232
259
  /**
233
260
  * Subscribe to server-pushed SFU SDP renegotiation offers. The
234
261
  * server publishes an `sfu-call-renegotiation-offer` event every
@@ -238,6 +265,8 @@ export class NeighbourhoodClient {
238
265
  *
239
266
  * The executor already sends each socket only its own DID's offers;
240
267
  * this subscription additionally filters on `targetDid` for safety.
268
+ * An agent in the call on two devices gets the offers of both: each
269
+ * names the session it is for (`participantId`).
241
270
  * Returns an unsubscribe function.
242
271
  */
243
272
  subscribeSfuCallRenegotiationOffer(targetDid, callback) {
@@ -246,6 +275,7 @@ export class NeighbourhoodClient {
246
275
  return;
247
276
  callback({
248
277
  targetDid: event.targetDid,
278
+ participantId: event.participantId,
249
279
  neighbourhoodUrl: event.neighbourhoodUrl,
250
280
  roomName: event.roomName,
251
281
  sdpOffer: event.sdpOffer,
@@ -2,7 +2,7 @@ import { DID } from "../DID";
2
2
  import { OnlineAgent } from "../language/Language";
3
3
  import { Perspective, PerspectiveExpression, PerspectiveUnsignedInput } from "../perspectives/Perspective";
4
4
  import { NeighbourhoodClient } from "./NeighbourhoodClient";
5
- import type { CallSessionInfo, SfuCallRenegotiationOffer, SfuCascadeStatus, SfuConfig, SfuDataMessage, SfuMigrateEvent, SfuParticipantQualityPreference, SfuQualityPreference, SfuRoomInfo } from "./SfuTypes";
5
+ import type { CallSessionInfo, SfuCallRenegotiationOffer, SfuCascadeStatus, SfuConfig, SfuDataMessage, SfuMigrateEvent, SfuParticipantQualityPreference, SfuQualityPreference, SfuRoomInfo, SfuSessionReplaced } from "./SfuTypes";
6
6
  import { type Session, type SessionCreateOptions } from "./Session";
7
7
  export declare class NeighbourhoodProxy {
8
8
  #private;
@@ -48,10 +48,18 @@ export declare class NeighbourhoodProxy {
48
48
  sfuStartRoom(neighbourhoodUrl: string, roomName: string): Promise<SfuRoomInfo>;
49
49
  sfuStopRoom(neighbourhoodUrl: string, roomName: string): Promise<boolean>;
50
50
  sfuListRooms(): Promise<SfuRoomInfo[]>;
51
- callJoin(neighbourhoodUrl: string, roomName: string, sdpOffer: string): Promise<CallSessionInfo>;
52
- callLeave(neighbourhoodUrl: string, roomName: string): Promise<boolean>;
53
- callSetQualityPreference(neighbourhoodUrl: string, roomName: string, preference: SfuQualityPreference): Promise<boolean>;
54
- callAnswerServerOffer(neighbourhoodUrl: string, roomName: string, sdpAnswer: string): Promise<boolean>;
51
+ /** Join from `deviceId`: a join from the same device replaces this agent's session there. */
52
+ callJoin(neighbourhoodUrl: string, roomName: string, sdpOffer: string, deviceId: string, sessionKey: string): Promise<CallSessionInfo>;
53
+ /** Leave the session `participantId` (the join's). */
54
+ callLeave(neighbourhoodUrl: string, roomName: string, participantId: string): Promise<boolean>;
55
+ callSetQualityPreference(neighbourhoodUrl: string, roomName: string, participantId: string, preference: SfuQualityPreference): Promise<boolean>;
56
+ callAnswerServerOffer(neighbourhoodUrl: string, roomName: string, participantId: string, sdpAnswer: string): Promise<boolean>;
57
+ /**
58
+ * Subscribe to the executor's notices that a session of this agent was
59
+ * replaced by a later join from the same device. Returns an unsubscribe
60
+ * function.
61
+ */
62
+ subscribeSessionReplaced(callback: (event: SfuSessionReplaced) => void): () => void;
55
63
  /**
56
64
  * Subscribe to server-pushed renegotiation offers for `targetDid`.
57
65
  * Returns an unsubscribe function. See
@@ -64,8 +72,8 @@ export declare class NeighbourhoodProxy {
64
72
  * Returns an unsubscribe function.
65
73
  */
66
74
  subscribeMigrateEvent(targetDid: string, callback: (event: SfuMigrateEvent) => void): () => void;
67
- addIceCandidate(neighbourhoodUrl: string, roomName: string, candidate: string): Promise<boolean>;
68
- sendData(neighbourhoodUrl: string, roomName: string, channelLabel: string, data: string, binary?: boolean): Promise<boolean>;
75
+ addIceCandidate(neighbourhoodUrl: string, roomName: string, participantId: string, candidate: string): Promise<boolean>;
76
+ sendData(neighbourhoodUrl: string, roomName: string, participantId: string, channelLabel: string, data: string, binary?: boolean): Promise<boolean>;
69
77
  subscribeDataChannel(callback: (message: SfuDataMessage) => void): () => void;
70
78
  sfuCascadeStatus(): Promise<SfuCascadeStatus>;
71
79
  sfuQualityPreferences(): Promise<SfuParticipantQualityPreference[]>;
@@ -12,6 +12,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
12
12
  var _NeighbourhoodProxy_client, _NeighbourhoodProxy_pID, _NeighbourhoodProxy_agentDid, _NeighbourhoodProxy_sessions, _NeighbourhoodProxy_sfuStatusCache;
13
13
  import { createSession } from "./Session";
14
14
  import { createTelepresenceChannel } from "./MeshManager";
15
+ import { defaultDeviceId } from "./SfuManager";
15
16
  export class NeighbourhoodProxy {
16
17
  constructor(client, pID, agentDid = "") {
17
18
  _NeighbourhoodProxy_client.set(this, void 0);
@@ -113,6 +114,7 @@ export class NeighbourhoodProxy {
113
114
  }
114
115
  }
115
116
  const proxy = this;
117
+ const deviceId = options?.deviceId || defaultDeviceId();
116
118
  const session = createSession({
117
119
  api: __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f"),
118
120
  roomId: roomName,
@@ -121,12 +123,13 @@ export class NeighbourhoodProxy {
121
123
  topology: options?.topology ?? "auto",
122
124
  sfuConfig: options?.sfuConfig,
123
125
  iceServers: options?.iceServers,
126
+ deviceId,
124
127
  localSfuStatus: __classPrivateFieldGet(this, _NeighbourhoodProxy_sfuStatusCache, "f") ?? undefined,
125
128
  sfuServesAllMembers: () => __classPrivateFieldGet(proxy, _NeighbourhoodProxy_client, "f").sfuServesAllMembers(__classPrivateFieldGet(proxy, _NeighbourhoodProxy_pID, "f")),
126
129
  // Mesh needs a signalling channel and presence callbacks.
127
130
  // SFU ignores these — they remain unused when the resolved
128
131
  // topology selects the SFU path.
129
- channel: createTelepresenceChannel(proxy, __classPrivateFieldGet(proxy, _NeighbourhoodProxy_agentDid, "f")),
132
+ channel: createTelepresenceChannel(proxy, __classPrivateFieldGet(proxy, _NeighbourhoodProxy_agentDid, "f"), deviceId),
130
133
  ownOnlineStatus: () => proxy.ownOnlineStatus(),
131
134
  setOnlineStatus: (status) => proxy.setOnlineStatusU(status),
132
135
  onlineAgents: () => proxy.onlineAgents(),
@@ -168,17 +171,27 @@ export class NeighbourhoodProxy {
168
171
  async sfuListRooms() {
169
172
  return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuListRooms();
170
173
  }
171
- async callJoin(neighbourhoodUrl, roomName, sdpOffer) {
172
- return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuCallJoin(neighbourhoodUrl, roomName, sdpOffer);
174
+ /** Join from `deviceId`: a join from the same device replaces this agent's session there. */
175
+ async callJoin(neighbourhoodUrl, roomName, sdpOffer, deviceId, sessionKey) {
176
+ return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuCallJoin(neighbourhoodUrl, roomName, sdpOffer, deviceId, sessionKey);
173
177
  }
174
- async callLeave(neighbourhoodUrl, roomName) {
175
- return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuCallLeave(neighbourhoodUrl, roomName);
178
+ /** Leave the session `participantId` (the join's). */
179
+ async callLeave(neighbourhoodUrl, roomName, participantId) {
180
+ return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuCallLeave(neighbourhoodUrl, roomName, participantId);
176
181
  }
177
- async callSetQualityPreference(neighbourhoodUrl, roomName, preference) {
178
- return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuCallSetQualityPreference(neighbourhoodUrl, roomName, preference);
182
+ async callSetQualityPreference(neighbourhoodUrl, roomName, participantId, preference) {
183
+ return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuCallSetQualityPreference(neighbourhoodUrl, roomName, participantId, preference);
179
184
  }
180
- async callAnswerServerOffer(neighbourhoodUrl, roomName, sdpAnswer) {
181
- return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuCallAnswerServerOffer(neighbourhoodUrl, roomName, sdpAnswer);
185
+ async callAnswerServerOffer(neighbourhoodUrl, roomName, participantId, sdpAnswer) {
186
+ return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuCallAnswerServerOffer(neighbourhoodUrl, roomName, participantId, sdpAnswer);
187
+ }
188
+ /**
189
+ * Subscribe to the executor's notices that a session of this agent was
190
+ * replaced by a later join from the same device. Returns an unsubscribe
191
+ * function.
192
+ */
193
+ subscribeSessionReplaced(callback) {
194
+ return __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").subscribeSfuSessionReplaced(callback);
182
195
  }
183
196
  /**
184
197
  * Subscribe to server-pushed renegotiation offers for `targetDid`.
@@ -197,12 +210,12 @@ export class NeighbourhoodProxy {
197
210
  return __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").subscribeSfuMigrateEvent(targetDid, callback);
198
211
  }
199
212
  // ── SFU trickle ICE ─────────────────────────────────────────────────
200
- async addIceCandidate(neighbourhoodUrl, roomName, candidate) {
201
- return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuAddIceCandidate(neighbourhoodUrl, roomName, candidate);
213
+ async addIceCandidate(neighbourhoodUrl, roomName, participantId, candidate) {
214
+ return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuAddIceCandidate(neighbourhoodUrl, roomName, participantId, candidate);
202
215
  }
203
216
  // ── SFU data channel relay ────────────────────────────────────────
204
- async sendData(neighbourhoodUrl, roomName, channelLabel, data, binary = false) {
205
- return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuSendData(neighbourhoodUrl, roomName, channelLabel, data, binary);
217
+ async sendData(neighbourhoodUrl, roomName, participantId, channelLabel, data, binary = false) {
218
+ return await __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").sfuSendData(neighbourhoodUrl, roomName, participantId, channelLabel, data, binary);
206
219
  }
207
220
  subscribeDataChannel(callback) {
208
221
  return __classPrivateFieldGet(this, _NeighbourhoodProxy_client, "f").subscribeSfuDataChannel(callback);
@@ -10,15 +10,23 @@ export type SessionEvent = "topology-changed" | "participant-joined" | "particip
10
10
  /** `(did, RTCPeerConnectionState)` — one pair's connection state. Mesh only. */
11
11
  | "peer-state"
12
12
  /** `(did, { rung, attempts })` — the mesh attempted a repair on this pair. */
13
- | "peer-recovery" | "state-changed" | "error";
13
+ | "peer-recovery" | "state-changed"
14
+ /**
15
+ * `(SfuSessionReplaced)` — the call was joined again from this device (another tab), and
16
+ * that join took it over: this session's call has ended, and it is idle again.
17
+ */
18
+ | "replaced" | "error";
14
19
  export type SessionEventCallback = (...args: any[]) => void;
15
20
  /** Unified WebRTC media session wrapping both mesh and SFU topologies. */
16
21
  export interface Session {
17
- /** Connect to the room with local media. Resolves when the session becomes active. */
22
+ /**
23
+ * Connect to the room with local media. Resolves when the session becomes active, or
24
+ * idle if another tab on this device replaced the call while it joined (`replaced`).
25
+ */
18
26
  join(localStream: MediaStream): Promise<void>;
19
27
  /** Disconnect from the room. The session returns to idle and can rejoin. */
20
28
  leave(): Promise<void>;
21
- /** Current participants in the room (excluding self). */
29
+ /** Current participants in the room (excluding this session; this agent's other devices included). */
22
30
  readonly participants: ReadonlyArray<SfuParticipantInfo>;
23
31
  /** Subscribe to incoming remote media tracks. Returns an unsubscribe function. */
24
32
  onTrack(cb: (stream: MediaStream, track: MediaStreamTrack) => void): () => void;
@@ -60,6 +68,12 @@ export interface SessionCreateOptions {
60
68
  sfuConfig?: SfuConfig;
61
69
  /** NAT traversal for both paths, each server as given. Takes precedence over `sfuConfig.iceServers`. */
62
70
  iceServers?: IceServer[];
71
+ /**
72
+ * The device this session calls from: a join from the same device replaces this agent's
73
+ * earlier session (another tab); another device joins beside it, as a participant of its own.
74
+ * Unset, the browser profile's id (`localStorage`), or one per process outside a browser.
75
+ */
76
+ deviceId?: string;
63
77
  }
64
78
  interface SessionImplConfig {
65
79
  api: SfuNeighbourhoodApi;
@@ -69,7 +83,10 @@ interface SessionImplConfig {
69
83
  topology: SessionTopology;
70
84
  sfuConfig?: SfuConfig;
71
85
  iceServers?: IceServer[];
72
- /** Signalling channel for mesh topology — required when topology resolves to mesh. */
86
+ /** See `SessionCreateOptions.deviceId`. */
87
+ deviceId?: string;
88
+ /** Signalling channel for mesh topology — required when topology resolves to mesh. It must
89
+ * speak as this session's peer, {@link meshPeerId} of `agentDid` and the device. */
73
90
  channel?: SignallingChannel;
74
91
  /** Publish call-presence via telepresence. The session broadcasts
75
92
  * membership so other agents' roster polls can discover it. */
@@ -77,7 +94,9 @@ interface SessionImplConfig {
77
94
  links: StatusLink[];
78
95
  }) => Promise<boolean>;
79
96
  /** This agent's current online status. The session adds its presence
80
- * link to it and takes it out again, leaving the app's own links. */
97
+ * link to it and takes it out again, leaving the app's own links and
98
+ * the presence of this agent's other devices — which the mesh roster
99
+ * reads from here too. */
81
100
  ownOnlineStatus?: () => Promise<{
82
101
  data?: {
83
102
  links?: {