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

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 (222) hide show
  1. package/lib/index.cjs +3789 -1192
  2. package/lib/index.js +3783 -1193
  3. package/lib/src/generated/api/AgentsByDidsRequest.d.ts +3 -0
  4. package/lib/src/generated/api/CallSessionInfo.d.ts +23 -0
  5. package/lib/src/generated/api/DiscardBatchRequest.d.ts +3 -0
  6. package/lib/src/generated/api/Events.d.ts +13 -3
  7. package/lib/src/generated/api/Events.js +1 -0
  8. package/lib/src/generated/api/FlowStateChangedEvent.d.ts +38 -0
  9. package/lib/src/generated/api/FlowStateEntry.d.ts +18 -0
  10. package/lib/src/generated/api/FlowStateEntry.js +2 -0
  11. package/lib/src/generated/api/IceServer.d.ts +18 -0
  12. package/lib/src/generated/api/IceServer.js +2 -0
  13. package/lib/src/generated/api/OnlineAgent.d.ts +4 -0
  14. package/lib/src/generated/api/PerspectiveDiscardBatchParams.d.ts +4 -0
  15. package/lib/src/generated/api/PerspectiveDiscardBatchParams.js +2 -0
  16. package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +8 -0
  17. package/lib/src/generated/api/PerspectiveFlowFiredParams.js +2 -0
  18. package/lib/src/generated/api/PerspectiveFlowStatesParams.d.ts +11 -0
  19. package/lib/src/generated/api/PerspectiveFlowStatesParams.js +2 -0
  20. package/lib/src/generated/api/PerspectiveGetAllShaclParams.d.ts +7 -0
  21. package/lib/src/generated/api/PerspectiveGetAllShaclParams.js +2 -0
  22. package/lib/src/generated/api/PerspectiveModelQueryParams.d.ts +6 -1
  23. package/lib/src/generated/api/PerspectiveRemoveSubjectParams.d.ts +6 -0
  24. package/lib/src/generated/api/PerspectiveRemoveSubjectParams.js +2 -0
  25. package/lib/src/generated/api/PerspectiveResynced.d.ts +8 -0
  26. package/lib/src/generated/api/PerspectiveResynced.js +2 -0
  27. package/lib/src/generated/api/PerspectiveSubscribed.d.ts +10 -0
  28. package/lib/src/generated/api/PerspectiveSubscribed.js +2 -0
  29. package/lib/src/generated/api/PerspectiveUpdateSubjectParams.d.ts +10 -0
  30. package/lib/src/generated/api/PerspectiveUpdateSubjectParams.js +2 -0
  31. package/lib/src/generated/api/QuerySubscriptionUpdate.d.ts +19 -0
  32. package/lib/src/generated/api/QuerySubscriptionUpdate.js +2 -0
  33. package/lib/src/generated/api/QuerySubscriptionUpdateEvent.d.ts +7 -0
  34. package/lib/src/generated/api/QuerySubscriptionUpdateEvent.js +1 -0
  35. package/lib/src/generated/api/QueryUpdatesLagged.d.ts +7 -0
  36. package/lib/src/generated/api/QueryUpdatesLagged.js +2 -0
  37. package/lib/src/generated/api/RemoveSubjectRequest.d.ts +9 -0
  38. package/lib/src/generated/api/RemoveSubjectRequest.js +2 -0
  39. package/lib/src/generated/api/ResyncSubscriptionRequest.d.ts +3 -0
  40. package/lib/src/generated/api/ResyncSubscriptionRequest.js +2 -0
  41. package/lib/src/generated/api/RpcMethods.d.ts +134 -14
  42. package/lib/src/generated/api/RpcMethods.js +12 -0
  43. package/lib/src/generated/api/SfuAddIceCandidateParams.d.ts +8 -0
  44. package/lib/src/generated/api/SfuAddIceCandidateParams.js +2 -0
  45. package/lib/src/generated/api/SfuAnswerServerOfferParams.d.ts +8 -0
  46. package/lib/src/generated/api/SfuAnswerServerOfferParams.js +2 -0
  47. package/lib/src/generated/api/SfuCallJoinParams.d.ts +14 -0
  48. package/lib/src/generated/api/SfuCallJoinParams.js +2 -0
  49. package/lib/src/generated/api/SfuCallRenegotiationOffer.d.ts +30 -0
  50. package/lib/src/generated/api/SfuCallRenegotiationOffer.js +1 -0
  51. package/lib/src/generated/api/SfuCascadePipe.d.ts +4 -0
  52. package/lib/src/generated/api/SfuCascadePipe.js +2 -0
  53. package/lib/src/generated/api/SfuCascadeStatus.d.ts +8 -0
  54. package/lib/src/generated/api/SfuCascadeStatus.js +1 -0
  55. package/lib/src/generated/api/SfuConfig.d.ts +52 -0
  56. package/lib/src/generated/api/SfuConfig.js +1 -0
  57. package/lib/src/generated/api/SfuDataMessage.d.ts +24 -0
  58. package/lib/src/generated/api/SfuDataMessage.js +2 -0
  59. package/lib/src/generated/api/SfuEnsureMembershipParams.d.ts +4 -0
  60. package/lib/src/generated/api/SfuEnsureMembershipParams.js +2 -0
  61. package/lib/src/generated/api/SfuMigrateEvent.d.ts +21 -0
  62. package/lib/src/generated/api/SfuMigrateEvent.js +2 -0
  63. package/lib/src/generated/api/SfuNeighbourhoodParams.d.ts +3 -0
  64. package/lib/src/generated/api/SfuNeighbourhoodParams.js +2 -0
  65. package/lib/src/generated/api/SfuParticipantQualityPreference.d.ts +7 -0
  66. package/lib/src/generated/api/SfuParticipantQualityPreference.js +2 -0
  67. package/lib/src/generated/api/SfuPerspectiveParams.d.ts +6 -0
  68. package/lib/src/generated/api/SfuPerspectiveParams.js +2 -0
  69. package/lib/src/generated/api/SfuQualityPreferenceParams.d.ts +8 -0
  70. package/lib/src/generated/api/SfuQualityPreferenceParams.js +2 -0
  71. package/lib/src/generated/api/SfuRoomInfo.d.ts +11 -0
  72. package/lib/src/generated/api/SfuRoomInfo.js +1 -0
  73. package/lib/src/generated/api/SfuRoomParams.d.ts +4 -0
  74. package/lib/src/generated/api/SfuRoomParams.js +2 -0
  75. package/lib/src/generated/api/SfuRoomParticipantInfo.d.ts +11 -0
  76. package/lib/src/generated/api/SfuRoomParticipantInfo.js +2 -0
  77. package/lib/src/generated/api/SfuRoomRoster.d.ts +13 -0
  78. package/lib/src/generated/api/SfuRoomRoster.js +2 -0
  79. package/lib/src/generated/api/SfuSendDataParams.d.ts +10 -0
  80. package/lib/src/generated/api/SfuSendDataParams.js +2 -0
  81. package/lib/src/generated/api/SfuSetConfigParams.d.ts +5 -0
  82. package/lib/src/generated/api/SfuSetConfigParams.js +1 -0
  83. package/lib/src/generated/api/SfuStatus.d.ts +24 -0
  84. package/lib/src/generated/api/SfuStatus.js +2 -0
  85. package/lib/src/generated/api/TrackMapEntry.d.ts +17 -0
  86. package/lib/src/generated/api/TrackMapEntry.js +2 -0
  87. package/lib/src/generated/api/UpdateSubjectRequest.d.ts +12 -0
  88. package/lib/src/generated/api/UpdateSubjectRequest.js +2 -0
  89. package/lib/src/generated/api/index.d.ts +3 -0
  90. package/lib/src/index.d.ts +7 -0
  91. package/lib/src/index.js +4 -0
  92. package/lib/src/model/Ad4mModel.d.ts +84 -0
  93. package/lib/src/model/Ad4mModel.js +234 -4
  94. package/lib/src/model/ModelQueryBuilder.d.ts +16 -35
  95. package/lib/src/model/ModelQueryBuilder.js +88 -270
  96. package/lib/src/model/decorators.d.ts +32 -0
  97. package/lib/src/model/decorators.js +40 -1
  98. package/lib/src/model/shacl-gen.d.ts +3 -1
  99. package/lib/src/model/shacl-gen.js +13 -1
  100. package/lib/src/model/types.d.ts +7 -0
  101. package/lib/src/neighbourhood/MeshManager.d.ts +384 -0
  102. package/lib/src/neighbourhood/MeshManager.js +1144 -0
  103. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +91 -0
  104. package/lib/src/neighbourhood/NeighbourhoodClient.js +196 -0
  105. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +55 -1
  106. package/lib/src/neighbourhood/NeighbourhoodProxy.js +170 -3
  107. package/lib/src/neighbourhood/Session.d.ts +105 -0
  108. package/lib/src/neighbourhood/Session.js +412 -0
  109. package/lib/src/neighbourhood/SfuManager.d.ts +174 -0
  110. package/lib/src/neighbourhood/SfuManager.js +619 -0
  111. package/lib/src/neighbourhood/SfuTypes.d.ts +35 -0
  112. package/lib/src/neighbourhood/SfuTypes.js +8 -0
  113. package/lib/src/perspectives/FlowInstance.d.ts +63 -24
  114. package/lib/src/perspectives/FlowInstance.js +74 -31
  115. package/lib/src/perspectives/FlowModels.d.ts +0 -16
  116. package/lib/src/perspectives/FlowModels.js +8 -16
  117. package/lib/src/perspectives/LiveQuery.d.ts +49 -0
  118. package/lib/src/perspectives/LiveQuery.js +169 -0
  119. package/lib/src/perspectives/PerspectiveClient.d.ts +24 -15
  120. package/lib/src/perspectives/PerspectiveClient.js +33 -36
  121. package/lib/src/perspectives/PerspectiveProxy.d.ts +67 -167
  122. package/lib/src/perspectives/PerspectiveProxy.js +121 -475
  123. package/lib/src/perspectives/TextContent.d.ts +31 -0
  124. package/lib/src/perspectives/TextContent.js +52 -0
  125. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +23 -0
  126. package/lib/src/perspectives/WakerSubscriptionManager.js +58 -17
  127. package/lib/src/shacl/SHACLFlow.d.ts +7 -4
  128. package/lib/src/shacl/SHACLFlow.js +7 -4
  129. package/lib/src/shacl/SHACLShape.d.ts +9 -0
  130. package/lib/src/shacl/SHACLShape.js +37 -0
  131. package/package.json +2 -2
  132. package/pnpm-workspace.yaml +4 -1
  133. package/src/Ad4mClient.test.ts +89 -17
  134. package/src/generated/api/AgentsByDidsRequest.ts +3 -0
  135. package/src/generated/api/CallSessionInfo.ts +20 -0
  136. package/src/generated/api/DiscardBatchRequest.ts +3 -0
  137. package/src/generated/api/Events.ts +14 -3
  138. package/src/generated/api/FlowStateChangedEvent.ts +36 -0
  139. package/src/generated/api/FlowStateEntry.ts +18 -0
  140. package/src/generated/api/IceServer.ts +19 -0
  141. package/src/generated/api/OnlineAgent.ts +6 -1
  142. package/src/generated/api/PerspectiveDiscardBatchParams.ts +3 -0
  143. package/src/generated/api/PerspectiveFlowFiredParams.ts +7 -0
  144. package/src/generated/api/PerspectiveFlowStatesParams.ts +11 -0
  145. package/src/generated/api/PerspectiveGetAllShaclParams.ts +6 -0
  146. package/src/generated/api/PerspectiveModelQueryParams.ts +5 -1
  147. package/src/generated/api/PerspectiveRemoveSubjectParams.ts +3 -0
  148. package/src/generated/api/PerspectiveResynced.ts +7 -0
  149. package/src/generated/api/PerspectiveSubscribed.ts +8 -0
  150. package/src/generated/api/PerspectiveUpdateSubjectParams.ts +7 -0
  151. package/src/generated/api/QuerySubscriptionUpdate.ts +10 -0
  152. package/src/generated/api/QuerySubscriptionUpdateEvent.ts +9 -0
  153. package/src/generated/api/QueryUpdatesLagged.ts +7 -0
  154. package/src/generated/api/RemoveSubjectRequest.ts +7 -0
  155. package/src/generated/api/ResyncSubscriptionRequest.ts +3 -0
  156. package/src/generated/api/RpcMethods.ts +68 -8
  157. package/src/generated/api/SfuAddIceCandidateParams.ts +7 -0
  158. package/src/generated/api/SfuAnswerServerOfferParams.ts +7 -0
  159. package/src/generated/api/SfuCallJoinParams.ts +13 -0
  160. package/src/generated/api/SfuCallRenegotiationOffer.ts +29 -0
  161. package/src/generated/api/SfuCascadePipe.ts +3 -0
  162. package/src/generated/api/SfuCascadeStatus.ts +7 -0
  163. package/src/generated/api/SfuConfig.ts +53 -0
  164. package/src/generated/api/SfuDataMessage.ts +23 -0
  165. package/src/generated/api/SfuEnsureMembershipParams.ts +3 -0
  166. package/src/generated/api/SfuMigrateEvent.ts +20 -0
  167. package/src/generated/api/{KeepAliveQueryRequest.ts → SfuNeighbourhoodParams.ts} +1 -1
  168. package/src/generated/api/SfuParticipantQualityPreference.ts +6 -0
  169. package/src/generated/api/{PerspectiveSubscribeQueryResult.ts → SfuPerspectiveParams.ts} +4 -1
  170. package/src/generated/api/SfuQualityPreferenceParams.ts +7 -0
  171. package/src/generated/api/SfuRoomInfo.ts +7 -0
  172. package/src/generated/api/SfuRoomParams.ts +3 -0
  173. package/src/generated/api/SfuRoomParticipantInfo.ts +8 -0
  174. package/src/generated/api/SfuRoomRoster.ts +12 -0
  175. package/src/generated/api/SfuSendDataParams.ts +7 -0
  176. package/src/generated/api/SfuSetConfigParams.ts +4 -0
  177. package/src/generated/api/SfuStatus.ts +24 -0
  178. package/src/generated/api/TrackMapEntry.ts +18 -0
  179. package/src/generated/api/UpdateSubjectRequest.ts +10 -0
  180. package/src/generated/api/index.ts +3 -0
  181. package/src/index.ts +7 -0
  182. package/src/model/Ad4mModel.test.ts +255 -231
  183. package/src/model/Ad4mModel.ts +271 -4
  184. package/src/model/ModelQueryBuilder.ts +103 -310
  185. package/src/model/abstract-classes.test.ts +225 -0
  186. package/src/model/decorators.ts +81 -0
  187. package/src/model/shacl-gen.ts +13 -0
  188. package/src/model/types.ts +7 -0
  189. package/src/neighbourhood/MeshManager.test.ts +2640 -0
  190. package/src/neighbourhood/MeshManager.ts +1350 -0
  191. package/src/neighbourhood/NeighbourhoodClient.ts +271 -0
  192. package/src/neighbourhood/NeighbourhoodProxy.test.ts +23 -0
  193. package/src/neighbourhood/NeighbourhoodProxy.ts +247 -1
  194. package/src/neighbourhood/Session.test.ts +800 -0
  195. package/src/neighbourhood/Session.ts +525 -0
  196. package/src/neighbourhood/SfuManager.test.ts +677 -0
  197. package/src/neighbourhood/SfuManager.ts +803 -0
  198. package/src/neighbourhood/SfuTypes.ts +40 -0
  199. package/src/perspectives/FlowInstance.ts +108 -31
  200. package/src/perspectives/FlowModels.ts +8 -18
  201. package/src/perspectives/LiveQuery.test.ts +197 -0
  202. package/src/perspectives/LiveQuery.ts +189 -0
  203. package/src/perspectives/PerspectiveClient.ts +51 -51
  204. package/src/perspectives/PerspectiveProxy.test.ts +85 -401
  205. package/src/perspectives/PerspectiveProxy.ts +126 -536
  206. package/src/perspectives/TextContent.test.ts +123 -0
  207. package/src/perspectives/TextContent.ts +36 -0
  208. package/src/perspectives/WakerSubscriptionManager.test.ts +88 -6
  209. package/src/perspectives/WakerSubscriptionManager.ts +69 -18
  210. package/src/shacl/SHACLFlow.ts +7 -4
  211. package/src/shacl/SHACLShape.test.ts +2 -1
  212. package/src/shacl/SHACLShape.ts +49 -0
  213. package/lib/src/generated/api/KeepAliveQueryRequest.d.ts +0 -3
  214. package/lib/src/generated/api/PerspectiveModelSubscribeResult.d.ts +0 -7
  215. package/lib/src/generated/api/PerspectiveQuerySubscriptionFilter.d.ts +0 -6
  216. package/lib/src/generated/api/PerspectiveSubscribeQueryResult.d.ts +0 -4
  217. package/src/generated/api/PerspectiveModelSubscribeResult.ts +0 -6
  218. package/src/generated/api/PerspectiveQuerySubscriptionFilter.ts +0 -3
  219. /package/lib/src/generated/api/{KeepAliveQueryRequest.js → AgentsByDidsRequest.js} +0 -0
  220. /package/lib/src/generated/api/{PerspectiveModelSubscribeResult.js → CallSessionInfo.js} +0 -0
  221. /package/lib/src/generated/api/{PerspectiveQuerySubscriptionFilter.js → DiscardBatchRequest.js} +0 -0
  222. /package/lib/src/generated/api/{PerspectiveSubscribeQueryResult.js → FlowStateChangedEvent.js} +0 -0
@@ -0,0 +1,525 @@
1
+ import { SfuManager, SfuNeighbourhoodApi } from "./SfuManager"
2
+ import { MeshManager, type SignallingChannel } from "./MeshManager"
3
+ import type { OnlineAgent } from "../language/Language"
4
+ import type {
5
+ SfuConfig,
6
+ SfuDataMessage,
7
+ SfuQualityPreference,
8
+ SfuParticipantInfo,
9
+ SfuStatus,
10
+ IceServer,
11
+ } from "./SfuTypes"
12
+
13
+ export type SessionTopology = "mesh" | "sfu" | "auto"
14
+
15
+ export type SessionState = "idle" | "joining" | "active" | "leaving" | "closed"
16
+
17
+ export type SessionEvent =
18
+ | "topology-changed"
19
+ | "participant-joined"
20
+ | "participant-left"
21
+ | "active-speaker"
22
+ | "stream-added"
23
+ | "stream-removed"
24
+ /** `(participant)` — a participant's stream object or track liveness changed. Mesh only. */
25
+ | "participant-updated"
26
+ /** `(did, RTCPeerConnectionState)` — one pair's connection state. Mesh only. */
27
+ | "peer-state"
28
+ /** `(did, { rung, attempts })` — the mesh attempted a repair on this pair. */
29
+ | "peer-recovery"
30
+ | "state-changed"
31
+ | "error"
32
+
33
+ export type SessionEventCallback = (...args: any[]) => void
34
+
35
+ /** Unified WebRTC media session wrapping both mesh and SFU topologies. */
36
+ export interface Session {
37
+ /** Connect to the room with local media. Resolves when the session becomes active. */
38
+ join(localStream: MediaStream): Promise<void>
39
+ /** Disconnect from the room. The session returns to idle and can rejoin. */
40
+ leave(): Promise<void>
41
+ /** Current participants in the room (excluding self). */
42
+ readonly participants: ReadonlyArray<SfuParticipantInfo>
43
+ /** Subscribe to incoming remote media tracks. Returns an unsubscribe function. */
44
+ onTrack(cb: (stream: MediaStream, track: MediaStreamTrack) => void): () => void
45
+ /**
46
+ * Replace the outbound track of a given kind on all peer connections.
47
+ *
48
+ * Uses `RTCRtpSender.replaceTrack` — no renegotiation, so camera↔screen
49
+ * swaps and mute/unmute are instant and atomic across all peers.
50
+ * Pass `null` to stop sending that kind without tearing down the transceiver.
51
+ */
52
+ replaceTrack(kind: "audio" | "video", track: MediaStreamTrack | null): Promise<void>
53
+ /** Set the preferred simulcast quality layer. */
54
+ setQualityPreference(pref: SfuQualityPreference): Promise<void>
55
+ /** Send data to all other participants via the SFU relay. */
56
+ sendData(label: string, data: string, binary?: boolean): Promise<void>
57
+ /** Subscribe to data channel messages from other participants. Returns an unsubscribe function. */
58
+ onData(cb: (message: SfuDataMessage) => void): () => void
59
+ /** Current lifecycle state. */
60
+ getState(): SessionState
61
+ /** Subscribe to session events. */
62
+ on(event: SessionEvent, cb: SessionEventCallback): void
63
+ /** Unsubscribe from session events. Omit cb to remove all listeners for the event. */
64
+ off(event: SessionEvent, cb?: SessionEventCallback): void
65
+ /** Each mesh peer's connection state. Empty on the SFU path, which has one connection. */
66
+ peerStates(): Map<string, RTCPeerConnectionState>
67
+ /** Rebuild one mesh peer's connection, telling the peer to do the same. No-op on the SFU path. */
68
+ reconnect(did: string): void
69
+ /** How a mesh peer's media travels — `host`, `srflx` or `relay` — or `null`. */
70
+ transportOf(did: string): Promise<string | null>
71
+ /** Release all resources. Calls leave() if still active. */
72
+ destroy(): Promise<void>
73
+ }
74
+
75
+ export interface SessionCreateOptions {
76
+ topology?: SessionTopology
77
+ neighbourhoodUrl?: string
78
+ /** The neighbourhood's call config. With `topology: "auto"`, its mode decides: any SFU mode
79
+ * runs through the SFU, `mesh` stays peer-to-peer. Passing one is the app's statement that
80
+ * every member reaches the same SFU. */
81
+ sfuConfig?: SfuConfig
82
+ /** NAT traversal for both paths, each server as given. Takes precedence over `sfuConfig.iceServers`. */
83
+ iceServers?: IceServer[]
84
+ }
85
+
86
+ interface SessionImplConfig {
87
+ api: SfuNeighbourhoodApi
88
+ roomId: string
89
+ agentDid: string
90
+ neighbourhoodUrl: string
91
+ topology: SessionTopology
92
+ sfuConfig?: SfuConfig
93
+ iceServers?: IceServer[]
94
+ /** Signalling channel for mesh topology — required when topology resolves to mesh. */
95
+ channel?: SignallingChannel
96
+ /** Publish call-presence via telepresence. The session broadcasts
97
+ * membership so other agents' roster polls can discover it. */
98
+ setOnlineStatus?: (status: { links: StatusLink[] }) => Promise<boolean>
99
+ /** This agent's current online status. The session adds its presence
100
+ * link to it and takes it out again, leaving the app's own links. */
101
+ ownOnlineStatus?: () => Promise<{ data?: { links?: { data?: Partial<StatusLink> }[] } } | null>
102
+ /** Poll for agents currently online in the neighbourhood. The
103
+ * session reconciles the result against its mesh connections. */
104
+ onlineAgents?: () => Promise<OnlineAgent[]>
105
+ /** Local executor's SFU status. "auto" needs `isPublic`: clients
106
+ * that are not on the executor's machine must reach its SFU. */
107
+ localSfuStatus?: SfuStatus
108
+ /** Whether every member of the neighbourhood is hosted on the local
109
+ * executor, so all of them reach its SFU. "auto" picks the SFU only
110
+ * when this resolves true. */
111
+ sfuServesAllMembers?: () => Promise<boolean>
112
+ }
113
+
114
+ /**
115
+ * Call-presence predicate. When the session joins, it publishes an
116
+ * online-status link with this predicate and the room id as target.
117
+ * Other agents polling `onlineAgents()` use this to discover the
118
+ * roster without a join message.
119
+ */
120
+ const CALL_PRESENCE_PREDICATE = "ad4m://session/in-call"
121
+
122
+ type StatusLink = { source: string; predicate?: string; target: string }
123
+
124
+ /** How often (ms) the mesh session polls `onlineAgents` for roster changes. */
125
+ const ROSTER_POLL_INTERVAL_MS = 3_000
126
+
127
+ export function createSession(config: SessionImplConfig): Session {
128
+ const {
129
+ api, roomId, agentDid, neighbourhoodUrl,
130
+ topology, sfuConfig, iceServers,
131
+ channel, setOnlineStatus, ownOnlineStatus, onlineAgents,
132
+ localSfuStatus, sfuServesAllMembers,
133
+ } = config
134
+
135
+ let state: SessionState = "idle"
136
+ let sfuManager: SfuManager | null = null
137
+ let meshManager: MeshManager | null = null
138
+ let rosterInterval: ReturnType<typeof setInterval> | null = null
139
+ /** A roster poll is running. Each poll waits on one remote call per
140
+ * online agent, so it can outlast the interval; the next tick is then
141
+ * skipped instead of stacking a second poll on the first. */
142
+ let polling = false
143
+ const callbacks = new Map<SessionEvent, SessionEventCallback[]>()
144
+ const trackListeners: ((stream: MediaStream, track: MediaStreamTrack) => void)[] = []
145
+ const dataListeners: ((message: SfuDataMessage) => void)[] = []
146
+ let dataUnsubscribe: (() => void) | null = null
147
+
148
+ function emit(event: SessionEvent, ...args: any[]) {
149
+ const cbs = callbacks.get(event)
150
+ if (cbs) for (const cb of cbs) cb(...args)
151
+ }
152
+
153
+ function setState(next: SessionState) {
154
+ state = next
155
+ emit("state-changed", next)
156
+ }
157
+
158
+ /**
159
+ * Resolve the effective topology.
160
+ *
161
+ * Explicit "sfu" or "mesh" returns immediately; so does "auto" with an
162
+ * `sfuConfig`. Otherwise "auto" must not split the call: the SFU path
163
+ * joins this executor's SFU only, and the mesh path never reaches it.
164
+ * So it picks the SFU only when the executor says every member of the
165
+ * neighbourhood is hosted on it and its SFU is public. Anything else,
166
+ * including a failed check, is mesh.
167
+ */
168
+ async function resolveTopology(): Promise<"sfu" | "mesh"> {
169
+ if (topology === "sfu") return "sfu"
170
+ if (topology === "mesh") return "mesh"
171
+
172
+ if (sfuConfig) {
173
+ return sfuConfig.mode === "mesh" ? "mesh" : "sfu"
174
+ }
175
+
176
+ if (!localSfuStatus?.isPublic || !sfuServesAllMembers) return "mesh"
177
+ try {
178
+ return (await sfuServesAllMembers()) ? "sfu" : "mesh"
179
+ } catch (err) {
180
+ console.warn("session: SFU membership check failed, using mesh:", err)
181
+ return "mesh"
182
+ }
183
+ }
184
+
185
+ // ── Mesh roster polling ─────────────────────────────────────────
186
+
187
+ /** The app's links in this agent's status when the call started — what
188
+ * leaving restores if the status cannot be read then. */
189
+ let statusBeforeCall: StatusLink[] = []
190
+ let announced = false
191
+
192
+ /** This agent's status links, without this call's presence link. */
193
+ async function ownLinksWithoutCall(): Promise<StatusLink[]> {
194
+ const status = ownOnlineStatus ? await ownOnlineStatus() : null
195
+ const links: StatusLink[] = []
196
+ for (const link of status?.data?.links ?? []) {
197
+ const l = link.data
198
+ if (!l?.source || l.target === undefined) continue
199
+ if (l.predicate === CALL_PRESENCE_PREDICATE && l.target === roomId) continue
200
+ links.push({ source: l.source, target: l.target, ...(l.predicate ? { predicate: l.predicate } : {}) })
201
+ }
202
+ return links
203
+ }
204
+
205
+ /**
206
+ * Add this call's presence link to the agent's online status. Other
207
+ * agents' roster polls pick it up.
208
+ */
209
+ async function announceCallPresence(): Promise<void> {
210
+ if (!setOnlineStatus) return
211
+ try {
212
+ statusBeforeCall = await ownLinksWithoutCall().catch((err) => {
213
+ console.warn("session: reading own status failed:", err)
214
+ return []
215
+ })
216
+ const presence = { source: agentDid, predicate: CALL_PRESENCE_PREDICATE, target: roomId }
217
+ await setOnlineStatus({ links: [...statusBeforeCall, presence] })
218
+ announced = true
219
+ } catch (err) {
220
+ console.warn("session: call-presence announcement failed:", err)
221
+ }
222
+ }
223
+
224
+ /** Take this call's presence link out of the agent's status again. */
225
+ async function withdrawCallPresence(): Promise<void> {
226
+ if (!setOnlineStatus || !announced) return
227
+ announced = false
228
+ try {
229
+ const links = await ownLinksWithoutCall().catch((err) => {
230
+ console.warn("session: reading own status failed:", err)
231
+ return statusBeforeCall
232
+ })
233
+ await setOnlineStatus({ links })
234
+ } catch (err) {
235
+ console.warn("session: withdrawing call presence failed:", err)
236
+ }
237
+ }
238
+
239
+ /**
240
+ * Poll online agents and reconcile the mesh roster.
241
+ *
242
+ * Agents in the same call carry a link with predicate
243
+ * `CALL_PRESENCE_PREDICATE` and target matching the room id.
244
+ * The poll reads the full online-agents list, filters to those
245
+ * links, and passes the resulting DID set to `mesh.setRoster()`.
246
+ * That function opens connections to new arrivals and tears down
247
+ * connections to departed peers.
248
+ */
249
+ async function pollRoster(): Promise<void> {
250
+ const mesh = meshManager
251
+ if (!mesh || !onlineAgents || polling) return
252
+ polling = true
253
+ try {
254
+ const agents = await onlineAgents()
255
+ // The session left while the poll was in flight.
256
+ if (meshManager !== mesh) return
257
+ const inCall: string[] = []
258
+ for (const agent of agents) {
259
+ if (agent.did === agentDid) continue
260
+ // Each agent's status is a signed perspective: its links
261
+ // sit under `data`. Check for the call-presence link
262
+ // matching this room.
263
+ for (const link of agent.status?.data?.links ?? []) {
264
+ const l = link.data
265
+ if (l?.predicate === CALL_PRESENCE_PREDICATE && l.target === roomId) {
266
+ inCall.push(agent.did)
267
+ break
268
+ }
269
+ }
270
+ }
271
+ mesh.setRoster(inCall)
272
+ } catch (err) {
273
+ console.warn("session: roster poll failed:", err)
274
+ } finally {
275
+ polling = false
276
+ }
277
+ }
278
+
279
+ function startRosterPolling(): void {
280
+ // Immediate first poll, then periodic
281
+ void pollRoster()
282
+ rosterInterval = setInterval(() => void pollRoster(), ROSTER_POLL_INTERVAL_MS)
283
+ }
284
+
285
+ function stopRosterPolling(): void {
286
+ if (rosterInterval !== null) {
287
+ clearInterval(rosterInterval)
288
+ rosterInterval = null
289
+ }
290
+ }
291
+
292
+ // ── Mesh wiring helpers ─────────────────────────────────────────
293
+
294
+ function wireMeshEvents(mesh: MeshManager): void {
295
+ for (const event of ["participant-joined", "participant-left", "participant-updated", "peer-state", "peer-recovery", "error"] as const) {
296
+ mesh.on(event, (...args: any[]) => emit(event, ...args))
297
+ }
298
+ mesh.on("stream-added", (stream: MediaStream, track: MediaStreamTrack) => {
299
+ emit("stream-added", stream, track)
300
+ for (const cb of trackListeners) cb(stream, track)
301
+ })
302
+ mesh.on("stream-removed", (stream: MediaStream, track: MediaStreamTrack) => {
303
+ emit("stream-removed", stream, track)
304
+ })
305
+ }
306
+
307
+ // ── SFU wiring helpers ──────────────────────────────────────────
308
+
309
+ function wireSfuEvents(sfu: SfuManager): void {
310
+ for (const event of ["topology-changed", "participant-joined", "participant-left", "active-speaker", "error"] as const) {
311
+ sfu.on(event, (...args: any[]) => emit(event, ...args))
312
+ }
313
+ sfu.on("stream-added", (stream: MediaStream, track: MediaStreamTrack) => {
314
+ emit("stream-added", stream, track)
315
+ for (const cb of trackListeners) cb(stream, track)
316
+ })
317
+ sfu.on("stream-removed", (stream: MediaStream, track: MediaStreamTrack) => {
318
+ emit("stream-removed", stream, track)
319
+ })
320
+ }
321
+
322
+ // ── Session object ──────────────────────────────────────────────
323
+
324
+ const session: Session = {
325
+ async join(localStream: MediaStream) {
326
+ if (state === "closed") throw new Error("Session destroyed")
327
+ if (state === "active" || state === "joining") throw new Error("Session already active")
328
+
329
+ setState("joining")
330
+ const topo = await resolveTopology()
331
+
332
+ if (topo === "mesh") {
333
+ if (!channel) {
334
+ throw new Error(
335
+ "Mesh topology requires a signalling channel — " +
336
+ "pass a channel via SessionImplConfig or use topology 'sfu'",
337
+ )
338
+ }
339
+
340
+ // Build effective ICE servers for the mesh path, using the
341
+ // same precedence as the SFU path: explicit iceServers →
342
+ // sfuConfig.iceServers → MeshManager default.
343
+ const meshIce: RTCIceServer[] = []
344
+ if (iceServers && iceServers.length > 0) {
345
+ for (const s of iceServers) {
346
+ meshIce.push({
347
+ urls: s.urls,
348
+ ...(s.username ? { username: s.username } : {}),
349
+ ...(s.credential ? { credential: s.credential } : {}),
350
+ })
351
+ }
352
+ } else if (sfuConfig?.iceServers && sfuConfig.iceServers.length > 0) {
353
+ for (const s of sfuConfig.iceServers) {
354
+ meshIce.push({
355
+ urls: s.urls,
356
+ ...(s.username ? { username: s.username } : {}),
357
+ ...(s.credential ? { credential: s.credential } : {}),
358
+ })
359
+ }
360
+ }
361
+
362
+ const mesh = new MeshManager({
363
+ channel,
364
+ callId: roomId,
365
+ selfId: agentDid,
366
+ ...(meshIce.length > 0 ? { iceServers: meshIce } : {}),
367
+ })
368
+ meshManager = mesh
369
+ wireMeshEvents(mesh)
370
+
371
+ dataUnsubscribe = mesh.subscribeDataChannel((msg) => {
372
+ for (const cb of dataListeners) cb(msg)
373
+ })
374
+
375
+ await mesh.join(localStream)
376
+
377
+ // Announce this agent's presence in the call, then
378
+ // start polling so the mesh reconciles connections
379
+ // against whoever else the roster contains.
380
+ await announceCallPresence()
381
+ startRosterPolling()
382
+
383
+ emit("topology-changed", "mesh")
384
+ setState("active")
385
+ return
386
+ }
387
+
388
+ // SFU path — this executor's SFU.
389
+ const iceConfig = iceServers && iceServers.length > 0
390
+ ? { servers: iceServers.map(s => ({ urls: s.urls, ...(s.username ? { username: s.username } : {}), ...(s.credential ? { credential: s.credential } : {}) })) }
391
+ : undefined
392
+
393
+ sfuManager = new SfuManager(api, roomId, agentDid, neighbourhoodUrl, iceConfig, sfuConfig)
394
+ wireSfuEvents(sfuManager)
395
+
396
+ dataUnsubscribe = sfuManager.subscribeDataChannel((msg) => {
397
+ for (const cb of dataListeners) cb(msg)
398
+ })
399
+
400
+ await sfuManager.join(localStream)
401
+ emit("topology-changed", "sfu")
402
+ setState("active")
403
+ },
404
+
405
+ async leave() {
406
+ if (state !== "active") return
407
+ setState("leaving")
408
+ stopRosterPolling()
409
+ await withdrawCallPresence()
410
+ if (dataUnsubscribe) { dataUnsubscribe(); dataUnsubscribe = null }
411
+ if (meshManager) { await meshManager.leave(); meshManager = null }
412
+ if (sfuManager) { await sfuManager.leave(); sfuManager = null }
413
+ setState("idle")
414
+ },
415
+
416
+ get participants() {
417
+ if (meshManager) {
418
+ return meshManager.getParticipants().map(p => ({
419
+ agentDid: p.did,
420
+ stream: p.stream,
421
+ hasAudio: p.hasAudio,
422
+ hasVideo: p.hasVideo,
423
+ isActiveSpeaker: p.isActiveSpeaker,
424
+ }))
425
+ }
426
+ if (sfuManager) {
427
+ return sfuManager.getParticipants().map(p => ({
428
+ agentDid: p.did,
429
+ stream: p.stream,
430
+ hasAudio: p.hasAudio,
431
+ hasVideo: p.hasVideo,
432
+ isActiveSpeaker: p.isActiveSpeaker,
433
+ }))
434
+ }
435
+ return []
436
+ },
437
+
438
+ onTrack(cb) {
439
+ trackListeners.push(cb)
440
+ return () => {
441
+ const idx = trackListeners.indexOf(cb)
442
+ if (idx !== -1) trackListeners.splice(idx, 1)
443
+ }
444
+ },
445
+
446
+ async replaceTrack(kind, track) {
447
+ if (meshManager) { await meshManager.replaceTrack(kind, track); return }
448
+ if (sfuManager) { await sfuManager.replaceTrack(kind, track); return }
449
+ throw new Error("Session not active")
450
+ },
451
+
452
+ async setQualityPreference(pref) {
453
+ // Mesh has no quality layers — simulcast only applies to SFU.
454
+ // Silently accept so callers need no topology check.
455
+ if (meshManager) return
456
+ if (!sfuManager) throw new Error("Session not active")
457
+ await sfuManager.setQualityPreference(pref)
458
+ },
459
+
460
+ async sendData(label, data, binary = false) {
461
+ if (meshManager) {
462
+ meshManager.sendData(label, data, binary)
463
+ return
464
+ }
465
+ if (!sfuManager) throw new Error("Session not active")
466
+ await sfuManager.sendData(label, data, binary)
467
+ },
468
+
469
+ onData(cb) {
470
+ dataListeners.push(cb)
471
+ return () => {
472
+ const idx = dataListeners.indexOf(cb)
473
+ if (idx !== -1) dataListeners.splice(idx, 1)
474
+ }
475
+ },
476
+
477
+ peerStates() {
478
+ return meshManager ? meshManager.peerStates() : new Map()
479
+ },
480
+
481
+ reconnect(did) {
482
+ meshManager?.reconnect(did)
483
+ },
484
+
485
+ async transportOf(did) {
486
+ return meshManager ? meshManager.transportOf(did) : null
487
+ },
488
+
489
+ getState() { return state },
490
+
491
+ on(event, cb) {
492
+ if (!callbacks.has(event)) callbacks.set(event, [])
493
+ callbacks.get(event)!.push(cb)
494
+ },
495
+
496
+ off(event, cb?) {
497
+ if (!cb) { callbacks.delete(event); return }
498
+ const cbs = callbacks.get(event)
499
+ if (cbs) {
500
+ const idx = cbs.indexOf(cb)
501
+ if (idx !== -1) cbs.splice(idx, 1)
502
+ if (cbs.length === 0) callbacks.delete(event)
503
+ }
504
+ },
505
+
506
+ async destroy() {
507
+ // Capture refs before leave() nulls them
508
+ const mesh = meshManager
509
+ const sfu = sfuManager
510
+ if (state === "active" || state === "joining") await session.leave()
511
+ stopRosterPolling()
512
+ if (mesh) { await mesh.destroy() }
513
+ if (sfu) { await sfu.destroy() }
514
+ meshManager = null
515
+ sfuManager = null
516
+ // Emit closed BEFORE clearing listeners
517
+ setState("closed")
518
+ callbacks.clear()
519
+ trackListeners.length = 0
520
+ dataListeners.length = 0
521
+ },
522
+ }
523
+
524
+ return session
525
+ }