finos · kriswest · Apr 17, 2025 · Apr 17, 2025 · Apr 17, 2025 · Roaders
@@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 
 ### Added
+<!-- TODO: add details of the getSubAgent changes to the changelog -->
 
 ### Changed
 

@@ -547,6 +547,9 @@ export interface DesktopAgent {
    */
   getAppMetadata(app: AppIdentifier): Promise<AppMetadata>;
 
+  // TODO: add getSubAgent definition
-  // TODO: add getSubAgent definition
+ * @param {string} params Required parameters object, which must include  
+ * at least a fully qualified appId or appD URL for the application to 
+ * indicate the app's identity. 
+ * @param {string} params.appId The fully qualified appId 
+ * (in the form appid@<appd origin> for the application 
+ * @param {URL} params.appDUrl The URL to the appD record providing the  
+ * app's identity, used as an alternative to a fully qualified appId. 
+ *  
+ * @return A promise that resolves to a DesktopAgent implementation or  
+ * rejects if the app identity could not be validated. 
+ */ 
+  getSubAgent (params: GetSubAgentParams): Promise<DesktopAgent>;
-  // TODO: add getSubAgent definition
+ * @param {string} params Required parameters object, which must include  
+ * at least a fully qualified appId or appD URL for the application to 
+ * indicate the app's identity. 
+ * @param {string} params.appId The fully qualified appId 
+ * (in the form appid@<appd origin> for the application 
+ * @param {URL} params.appDUrl The URL to the appD record providing the  
+ * app's identity, used as an alternative to a fully qualified appId. 
+ *  
+ * @return A promise that resolves to a DesktopAgent implementation or  
+ * rejects if the app identity could not be validated. 
+ */ 
+  getSubAgent (params: GetSubAgentParams): Promise<DesktopAgent>;
+  // TODO: add close or disconnect definition
+
   //---------------------------------------------------------------------------------------------
   // Deprecated function signatures
   //---------------------------------------------------------------------------------------------

@@ -25,6 +25,8 @@ interface DesktopAgent {
   open(app: AppIdentifier, context?: Context): Promise<AppIdentifier>;
   findInstances(app: AppIdentifier): Promise<Array<AppIdentifier>>;
   getAppMetadata(app: AppIdentifier): Promise<AppMetadata>;
+  // TODO: add getSubAgent
-  // TODO: add getSubAgent
+getSubAgent (params: GetSubAgentParams): Promise<DesktopAgent>;
-  // TODO: add getSubAgent
+getSubAgent (params: GetSubAgentParams): Promise<DesktopAgent>;
+  // TODO: add a close or disconnect function (for subAgents or maybe all agents?)
 
   // context
   broadcast(context: Context): Promise<void>;
@@ -412,6 +414,10 @@ _desktopAgent.Broadcast(instrument);
 
 - [addContextListener](#addcontextlistener)
 
+### `close`
+
+ <!-- TODO: add close or disconnect content -->
+
 ### `createPrivateChannel`
 
 <Tabs groupId="lang">
@@ -1105,6 +1111,10 @@ var redChannel = userChannels.First(c => c.Id == "red");
 
 - [`Channel`](Channel)
 
+### `getSubAgent`
+
+ <!-- TODO: add getSubAgent content -->
+
 ### `joinUserChannel`
 
 <Tabs groupId="lang">

@@ -121,6 +121,8 @@ An FDC3 Standard compliant Desktop Agent implementation **MUST**:
 - Provide details of whether they implement optional features of the Desktop Agent API in the `optionalFeatures` property of the [`ImplementationMetadata`](ref/Metadata#implementationmetadata) object returned by the [`fdc3.getInfo()`](ref/DesktopAgent#getinfo) function.
 - Allow, by default, at least a 15 second timeout for an application, launched via [`fdc3.open`](../api/ref/DesktopAgent#open), [`fdc3.raiseIntent`](../api/ref/DesktopAgent#raiseintent) or [`fdc3.raiseIntentForContext`](../api/ref/DesktopAgent#raiseintentforcontext) to add any context listener (via [`fdc3.addContextListener`](../api/ref/DesktopAgent#addcontextlistener)) or intent listener (via [`fdc3.addIntentListener`](../api/ref/DesktopAgent#addintentlistener)) necessary to deliver context or intent and context to it on launch. This timeout only applies to listeners needed to receive context on launch; further intent and context listeners not required on launch MAY be added later.
 
+<!-- TODO: add any new requirements for subAgents or disconnection functions -->
+
 An FDC3 Standard compliant Desktop Agent implementation **SHOULD**:
 
 - Support connection to one or more App Directories meeting the [FDC3 App Directory Standard](../app-directory/overview).
@@ -132,6 +134,8 @@ An FDC3 Standard compliant Desktop Agent implementation **SHOULD**:
 - Prevent external apps from listening or publishing on a [`PrivateChannel`](ref/PrivateChannel) that they did not request or provide.
 - Enforce compliance with the expected behavior of intents (where Intents specify a contract that is enforceable by schema, for example, return object types) and return an error if the interface is not met.
 
+<!-- TODO: add any new recommendations for subAgents or disconnection functions -->
+
 An FDC3 Standard compliant Desktop Agent implementation **MAY**:
 
 - Make the Desktop Agent API available through modules, imports, or other means.
@@ -234,6 +238,12 @@ Additional metadata for an application can be retrieved via the [`fdc3.getAppMet
 
 Identifiers for instances of an application may be retrieved via the [`fdc3.findInstances(appIdentifier)`](ref/DesktopAgent#findinstances) function.
 
+### Start sub-applications with their own identity
+
+<!-- TODO: Describe the use-case for sub-agents without being overly focused on a particular platform (could make sense in web apps and monolithic apps built in other languages.
+Ensure routing of channel messages and intent resolution are covered.
+-->
+
-
+In some scenarios, it may be necessary to load more than one `DesktopAgent` into the context of a single application or browser window (for web-based applications). This is particularly relevant in the context of micro-frontends, where different applications within the same window may need to communicate with each other.
+
+Using a single `DesktopAgent` per window does not allow separate applications within the same browser window to communicate with each other (this limitation does not apply if the application is loaded into an iframe which is considered to be a different browser window).
+
+To address this, sub-applications can use **sub-agents**. Sub-agents allow different sub-applications within a single window to communicate with each other. Here's an example of how to create and use a sub-agent:
+
+```ts
+const subAgent: DesktopAgent = await (await getAgent()).getSubAgent({appId: "[email protected]"});
+
+subAgent.raiseIntent("StartChat", context);
-
+In some scenarios, it may be necessary to load more than one `DesktopAgent` into the context of a single application or browser window (for web-based applications). This is particularly relevant in the context of micro-frontends, where different applications within the same window may need to communicate with each other.
+
+Using a single `DesktopAgent` per window does not allow separate applications within the same browser window to communicate with each other (this limitation does not apply if the application is loaded into an iframe which is considered to be a different browser window).
+
+To address this, sub-applications can use **sub-agents**. Sub-agents allow different sub-applications within a single window to communicate with each other. Here's an example of how to create and use a sub-agent:
+
+```ts
+const subAgent: DesktopAgent = await (await getAgent()).getSubAgent({appId: "[email protected]"});
+
+subAgent.raiseIntent("StartChat", context);
 ## Raising Intents
 
 Raising an Intent is a method for an application to request functionality from another application and, if desired, defer the discovery and launching of the destination app to the Desktop Agent.
@@ -843,3 +853,7 @@ To facilitate context linking in such situations it is recommended that applicat
 ### Originating App Metadata
 
 Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation to registered context handlers on all types of channel. As this metadata is optional, apps making use of it MUST handle cases where it is not provided.
+
+## Sub-applications
+
+<!-- Add content describing how sub applications are created with their own identity -->
@@ -263,3 +263,7 @@ Communication between the `DesktopAgentProxy` and the iframes it injects is achi
 A further set of messages are provided for working with the injected user interfaces over their `MessageChannel` as part of the DACP, these are: `Fdc3UserInterfaceRestyle`, `Fdc3UserInterfaceDrag`, `Fdc3UserInterfaceChannels`, `Fdc3UserInterfaceChannelSelected`, `Fdc3UserInterfaceResolve` and `Fdc3UserInterfaceResolveAction`.
 
 See the [Desktop Agent Communication Protocol](./desktopAgentCommunicationProtocol) (DACP) for more details.
+
+## Requesting a sub-agent for an embedded application
+
+<!-- Add content on how sub agent requests are handled through the WCP and DACP - include a diagram of the process -->
@@ -280,6 +280,10 @@ Request and response used to implement the [`getUserChannels()`](../ref/DesktopA
 - [`getUserChannelsRequest`](pathname:///schemas/next/api/getUserChannelsRequest.schema.json)
 - [`getUserChannelsResponse`](pathname:///schemas/next/api/getUserChannelsResponse.schema.json)
 
+#### `getSubAgent()`
+
+<!-- Add details of any DACP messages used by getSubAgent -->
+
 #### `joinUserChannel()`
 
 Request and response used to implement the [`joinUserChannel()`](../ref/DesktopAgent#joinuserchannel) API call:
@@ -463,6 +467,10 @@ Additional procedures are defined in the [Browser Resident Desktop Agents specif
 
 :::
 
+### Requesting a sub-agent
+
+<!-- Discuss DACP role in requesting a subagent and attachment of of another port to the message, before switching to WCP. Other languages will need to handle that handover somehow -->
+
 ### Controlling Injected User Interfaces
 
 Desktop Agent implementations, such as those based on the [Browser Resident Desktop Agents specification](./browserResidentDesktopAgents) and [Web Connection Protocol](./webConnectionProtocol), may either provide their own user interfaces (or other appropriate mechanisms) for the selection of User Channels or Intent Resolution, or they may work with implementations injected into the application (for example, as described in the [Web Connection Protocol](./webConnectionProtocol#providing-channel-selector-and-intent-resolver-uis) and implemented in [`getAgent()`](../ref/GetAgent)).

@@ -26,3 +26,7 @@ However, implementors SHOULD also ensure that the global is made available as so
 Prior to FDC3 2.2, apps were advised to check for the existence of the FDC3 API at `window.fdc3` and then add a listener for the `fdc3Ready` event if it was not found. This has since been superseded by the recommendation to use `getAgent()`, which handles those steps internally, alongside supporting FDC3 in web browsers ( via the [Browser Resident Desktop Agent spec](./browserResidentDesktopAgents)).
 
 :::
+
+## Requesting a sub-agent for an embedded application
+
+<!-- Add content on how sub agent requests should be handled by preload DAs -->
@@ -393,3 +393,7 @@ The WCP allows applications to indicate to the `getAgent()` implementation wheth
 - [`WCP3Handshake`](pathname:///schemas/next/api/WCP3Handshake.schema.json): Response sent by the Desktop Agent and incorporating `payload.intentResolverUrl` and `payload.channelSelectorUrl` fields, which should be set to the URL for each UI implementation that should be loaded into an iframe to provide the UI (defaults to URLs for reference UI implementations provided by the FDC3 project), or set to `false` to indicate that the respective UI is not needed. Setting these fields to `true` will cause the `getAgent()` implementation to use its default URLs representing a reference implementation of each UI.
 
 When UI iframes are created, the user interfaces may use the `Fdc3UserInterface` messages incorporated into the [Desktop Agent Communication Protocol (DACP)](./desktopAgentCommunicationProtocol#controlling-injected-user-interfaces) to communicate with the `getAgent()` implementation and through it the Desktop Agent.
+
+### Requesting a sub-agent
+
+<!-- Add content on WCP message (re)use in requesting and connecting a subagent -->