Add *ProvidableContextMetadata types and prox-agent handling

Julianna Langston · kriswest · commit f245e93de8be · 2026-04-23T14:13:19.000+01:00
diff --git a/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts b/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts
@@ -1,6 +1,7 @@
 import {
   AppIdentifier,
   AppMetadata,
+  AppProvidableContextMetadata,
   ContextHandler,
   DesktopAgent,
   EventHandler,
@@ -82,10 +83,10 @@ export class DesktopAgentProxy implements DesktopAgent, Connectable {
     return this.apps.getImplementationMetadata();
   }
 
-  async broadcast(context: Context): Promise<void> {
+  async broadcast(context: Context, metadata?: AppProvidableContextMetadata): Promise<void> {
     const channel = await this.channels.getUserChannel();
     if (channel) {
-      return channel.broadcast(context);
+      return channel.broadcast(context, metadata);
     } else {
       return Promise.resolve();
     }
@@ -169,20 +170,24 @@ export class DesktopAgentProxy implements DesktopAgent, Connectable {
     }
   }
 
-  raiseIntent(intent: string, context: Context, app?: string | AppIdentifier) {
-    return this.intents.raiseIntent(intent, context, this.ensureAppId(app));
+  raiseIntent(intent: string, context: Context, app?: string | AppIdentifier, metadata?: AppProvidableContextMetadata) {
+    return this.intents.raiseIntent(intent, context, this.ensureAppId(app), metadata);
   }
 
   addIntentListener(intent: string, handler: IntentHandler) {
     return this.intents.addIntentListener(intent, handler);
   }
 
-  raiseIntentForContext(context: Context, app?: string | AppIdentifier): Promise<IntentResolution> {
-    return this.intents.raiseIntentForContext(context, this.ensureAppId(app));
+  raiseIntentForContext(
+    context: Context,
+    app?: string | AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution> {
+    return this.intents.raiseIntentForContext(context, this.ensureAppId(app), metadata);
   }
 
-  open(app: string | AppIdentifier, context?: Context | undefined) {
-    return this.apps.open(this.ensureAppId(app)!, context);
+  open(app: string | AppIdentifier, context?: Context, metadata?: AppProvidableContextMetadata) {
+    return this.apps.open(this.ensureAppId(app)!, context, metadata);
   }
 
   findInstances(app: AppIdentifier) {
diff --git a/packages/fdc3-agent-proxy/src/apps/AppSupport.ts b/packages/fdc3-agent-proxy/src/apps/AppSupport.ts
@@ -1,9 +1,9 @@
-import { AppIdentifier, AppMetadata, ImplementationMetadata } from '@finos/fdc3-standard';
+import { AppIdentifier, AppMetadata, AppProvidableContextMetadata, ImplementationMetadata } from '@finos/fdc3-standard';
 import { Context } from '@finos/fdc3-context';
 
 export interface AppSupport {
   findInstances(app: AppIdentifier): Promise<Array<AppIdentifier>>;
   getAppMetadata(app: AppIdentifier): Promise<AppMetadata>;
-  open(app: AppIdentifier, context?: Context): Promise<AppIdentifier>;
+  open(app: AppIdentifier, context?: Context, metadata?: AppProvidableContextMetadata): Promise<AppIdentifier>;
   getImplementationMetadata(): Promise<ImplementationMetadata>;
 }
diff --git a/packages/fdc3-agent-proxy/src/apps/DefaultAppSupport.ts b/packages/fdc3-agent-proxy/src/apps/DefaultAppSupport.ts
@@ -1,4 +1,11 @@
-import { AppIdentifier, AppMetadata, ImplementationMetadata, OpenError, ResolveError } from '@finos/fdc3-standard';
+import {
+  AppIdentifier,
+  AppMetadata,
+  AppProvidableContextMetadata,
+  ImplementationMetadata,
+  OpenError,
+  ResolveError,
+} from '@finos/fdc3-standard';
 import { Context } from '@finos/fdc3-context';
 import { AppSupport } from './AppSupport.js';
 import { Messaging } from '../Messaging.js';
@@ -68,7 +75,11 @@ export class DefaultAppSupport implements AppSupport {
     return response.payload.appMetadata!;
   }
 
-  async open(app: AppIdentifier, context?: Context | undefined): Promise<AppIdentifier> {
+  async open(
+    app: AppIdentifier,
+    context?: Context | undefined,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<AppIdentifier> {
     const request: OpenRequest = {
       type: 'openRequest',
       payload: {
@@ -78,6 +89,7 @@ export class DefaultAppSupport implements AppSupport {
         },
         context,
       },
+      metadata,
       meta: this.messaging.createMeta(),
     };
 
diff --git a/packages/fdc3-agent-proxy/src/intents/DefaultIntentSupport.ts b/packages/fdc3-agent-proxy/src/intents/DefaultIntentSupport.ts
@@ -8,6 +8,7 @@ import {
   IntentResult,
   IntentResolver,
   IntentResolutionChoice,
+  AppProvidableContextMetadata,
 } from '@finos/fdc3-standard';
 import { IntentSupport } from './IntentSupport.js';
 import { Messaging } from '../Messaging.js';
@@ -28,6 +29,7 @@ import {
   RaiseIntentResultResponse,
 } from '@finos/fdc3-schema/dist/generated/api/BrowserTypes.js';
 import { throwIfUndefined } from '../util/throwIfUndefined.js';
+import { v4 } from 'uuid';
 
 const convertIntentResult = async (
   { payload }: RaiseIntentResultResponse,
@@ -130,16 +132,25 @@ export class DefaultIntentSupport implements IntentSupport {
     return ir;
   }
 
-  async raiseIntent(intent: string, context: Context, app: AppIdentifier): Promise<IntentResolution> {
+  async raiseIntent(
+    intent: string,
+    context: Context,
+    app: AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution> {
     const meta = this.messaging.createMeta();
     const request: RaiseIntentRequest = {
       type: 'raiseIntentRequest',
       payload: {
         intent,
         context,
-        app: app,
+        app,
       },
-      meta: meta,
+      metadata: {
+        signature: metadata?.signature,
+        traceId: metadata?.traceId ?? v4(),
+      },
+      meta,
     };
 
     const resultPromise = this.createResultPromise(request);
@@ -163,7 +174,7 @@ export class DefaultIntentSupport implements IntentSupport {
         context
       );
       if (result) {
-        return this.raiseIntent(intent, context, result.appId);
+        return this.raiseIntent(intent, context, result.appId, metadata);
       } else {
         throw new Error(ResolveError.UserCancelled);
       }
@@ -174,14 +185,23 @@ export class DefaultIntentSupport implements IntentSupport {
     }
   }
 
-  async raiseIntentForContext(context: Context, app?: AppIdentifier | undefined): Promise<IntentResolution> {
+  async raiseIntentForContext(
+    context: Context,
+    app?: AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution> {
+    const meta = this.messaging.createMeta();
     const request: RaiseIntentForContextRequest = {
       type: 'raiseIntentForContextRequest',
       payload: {
         context,
-        app: app,
+        app,
       },
-      meta: this.messaging.createMeta(),
+      metadata: {
+        signature: metadata?.signature,
+        traceId: metadata?.traceId ?? v4(),
+      },
+      meta,
     };
 
     const resultPromise = this.createResultPromise(request);
diff --git a/packages/fdc3-agent-proxy/src/intents/IntentSupport.ts b/packages/fdc3-agent-proxy/src/intents/IntentSupport.ts
@@ -1,10 +1,26 @@
-import { AppIdentifier, AppIntent, IntentHandler, IntentResolution, Listener } from '@finos/fdc3-standard';
+import {
+  AppIdentifier,
+  AppIntent,
+  AppProvidableContextMetadata,
+  IntentHandler,
+  IntentResolution,
+  Listener,
+} from '@finos/fdc3-standard';
 import { Context } from '@finos/fdc3-context';
 
 export interface IntentSupport {
   findIntent(intent: string, context: Context, resultType: string | undefined): Promise<AppIntent>;
   findIntentsByContext(context: Context): Promise<AppIntent[]>;
-  raiseIntent(intent: string, context: Context, app?: AppIdentifier): Promise<IntentResolution>;
-  raiseIntentForContext(context: Context, app?: AppIdentifier): Promise<IntentResolution>;
+  raiseIntent(
+    intent: string,
+    context: Context,
+    app?: AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution>;
+  raiseIntentForContext(
+    context: Context,
+    app?: AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution>;
   addIntentListener(intent: string, handler: IntentHandler): Promise<Listener>;
 }
diff --git a/packages/fdc3-agent-proxy/src/listeners/DefaultContextListener.ts b/packages/fdc3-agent-proxy/src/listeners/DefaultContextListener.ts
@@ -1,9 +1,10 @@
-import { AppIdentifier, ContextHandler } from '@finos/fdc3-standard';
+import { ContextHandler, DesktopAgentProvidableContextMetadata } from '@finos/fdc3-standard';
 import { Messaging } from '../Messaging.js';
 import { AbstractListener } from './AbstractListener.js';
 import { AddContextListenerRequest, BroadcastEvent } from '@finos/fdc3-schema/dist/generated/api/BrowserTypes.js';
 import { RegisterableListener } from './RegisterableListener.js';
 
+
 export class DefaultContextListener
   extends AbstractListener<ContextHandler, AddContextListenerRequest>
   implements RegisterableListener
@@ -44,8 +45,12 @@ export class DefaultContextListener
   }
 
   action(m: BroadcastEvent): void {
-    this.handler(m.payload.context, {
-      source: m.payload.originatingApp as AppIdentifier,
-    });
+    const metadata: DesktopAgentProvidableContextMetadata = {
+      source: m.payload.originatingApp,
+      timestamp: m.meta.timestamp,
+      traceId: m.metadata?.traceId,
+      signature: m.metadata?.signature,
+    };
+    this.handler(m.payload.context, metadata);
   }
 }
diff --git a/packages/fdc3-agent-proxy/src/listeners/DefaultIntentListener.ts b/packages/fdc3-agent-proxy/src/listeners/DefaultIntentListener.ts
@@ -9,6 +9,7 @@ import {
   IntentResultResponse,
   //RaiseIntentResponse,
 } from '@finos/fdc3-schema/dist/generated/api/BrowserTypes.js';
+import { v4 } from 'uuid';
 
 export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIntentListenerRequest> {
   readonly intent: string;
@@ -34,6 +35,9 @@ export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIn
   action(m: IntentEvent): void {
     const done = this.handler(m.payload.context, {
       source: m.payload.originatingApp as AppIdentifier,
+      timestamp: m.meta.timestamp,
+      traceId: m.metadata?.traceId ?? v4(),
+      signature: m.metadata?.signature,
     });
 
     this.handleIntentResult(done, m);
@@ -51,6 +55,7 @@ export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIn
         intentEventUuid: m.meta.eventUuid,
         raiseIntentRequestUuid: m.payload.raiseIntentRequestUuid,
       },
+      metadata: m.metadata,
     };
 
     return out;
diff --git a/packages/fdc3-schema/schemas/api/addIntentListenerResponse.schema.json b/packages/fdc3-schema/schemas/api/addIntentListenerResponse.schema.json
@@ -24,6 +24,9 @@
 						}
 					]
 				},
+				"metadata": {
+					"$ref": "api.schema.json#/definitions/DesktopAgentProvidableContextMetadata"
+				},
 				"meta": true
 			},
 			"additionalProperties": false
diff --git a/packages/fdc3-schema/schemas/api/agentEvent.schema.json b/packages/fdc3-schema/schemas/api/agentEvent.schema.json
@@ -27,6 +27,9 @@
       "description": "The message payload contains details of the event that the app is being notified about.",
       "additionalProperties": true
     },
+    "metadata": {
+					"$ref": "api.schema.json#/definitions/DesktopAgentProvidableContextMetadata"
+    },
     "meta": {
       "title": "Event Metadata",
       "description": "Metadata for messages sent by a Desktop Agent to an app notifying it of an event.",
diff --git a/packages/fdc3-schema/schemas/api/api.schema.json b/packages/fdc3-schema/schemas/api/api.schema.json
@@ -283,6 +283,45 @@
                 "source"
             ]
         },
+        "AppProvidableContextMetadata": {
+            "description": "Metadata that can be provided by an app.",
+            "title": "AppProvidableContextMetadata",
+            "type": "object",
+            "properties": {
+                "signature": {
+                    "type": "string"
+                },
+                "traceId": {
+                    "type": "string"
+                },
+                "hostParams": {
+                    "type": "object"
+                }
+            },
+            "additionalProperties": false
+        },
+        "DesktopAgentProvidableContextMetadata": {
+            "description": "Metadata that can be provided by an app.",
+            "title": "DesktopAgentProvidableContextMetadata",
+            "type": "object",
+            "properties": {
+                "signature": {
+                    "type": "string"
+                },
+                "traceId": {
+                    "type": "string"
+                },
+                "timestamp": {
+                    "type": "number"
+                },
+                "source": {
+                    "$ref": "#/definitions/AppIdentifier",
+                    "description": "Identifier for the source app instance",
+                    "title": "source"
+                }
+            },
+            "additionalProperties": false
+        },
         "DesktopAgentIdentifier": {
             "description": "Identifies a particular Desktop Agent in Desktop Agent Bridging scenarios\nwhere a request needs to be directed to a Desktop Agent rather than a specific app, or a\nresponse message is returned by the Desktop Agent (or more specifically its resolver)\nrather than a specific app. Used as a substitute for `AppIdentifier` in cases where no\napp details are available or are appropriate.",
             "title": "DesktopAgentIdentifier",
diff --git a/packages/fdc3-schema/schemas/api/broadcastEvent.schema.json b/packages/fdc3-schema/schemas/api/broadcastEvent.schema.json
@@ -17,6 +17,9 @@
 				"payload": {
 					"$ref": "#/$defs/BroadcastEventPayload"
 				},
+				"metadata": {
+					"$ref": "api.schema.json#/definitions/AppProvidableContextMetadata"
+				},
 				"meta": true
 			},
 			"additionalProperties": false
diff --git a/packages/fdc3-schema/schemas/api/broadcastRequest.schema.json b/packages/fdc3-schema/schemas/api/broadcastRequest.schema.json
@@ -17,6 +17,9 @@
 				"payload": {
 					"$ref": "#/$defs/BroadcastRequestPayload"
 				},
+				"metadata": {
+					"$ref": "api.schema.json#/definitions/AppProvidableContextMetadata"
+				},
 				"meta": true
 			},
 			"additionalProperties": false
diff --git a/packages/fdc3-schema/schemas/api/intentEvent.schema.json b/packages/fdc3-schema/schemas/api/intentEvent.schema.json
@@ -17,6 +17,9 @@
 				"payload": {
 					"$ref": "#/$defs/IntentEventPayload"
 				},
+				"metadata": {
+					"$ref": "api.schema.json#/definitions/DesktopAgentProvidableContextMetadata"
+				},
 				"meta": true
 			},
 			"additionalProperties": false
diff --git a/packages/fdc3-schema/schemas/api/intentResultRequest.schema.json b/packages/fdc3-schema/schemas/api/intentResultRequest.schema.json
@@ -17,6 +17,9 @@
 				"payload": {
 					"$ref": "#/$defs/IntentResultRequestPayload"
 				},
+				"metadata": {
+					"$ref": "api.schema.json#/definitions/AppProvidableContextMetadata"
+				},
 				"meta": true
 			},
 			"additionalProperties": false
diff --git a/packages/fdc3-schema/schemas/api/openRequest.schema.json b/packages/fdc3-schema/schemas/api/openRequest.schema.json
@@ -17,6 +17,9 @@
 				"payload": {
 					"$ref": "#/$defs/OpenRequestPayload"
 				},
+				"metadata": {
+					"$ref": "api.schema.json#/definitions/AppProvidableContextMetadata"
+				},
 				"meta": true
 			},
 			"additionalProperties": false
diff --git a/packages/fdc3-schema/schemas/api/privateChannelAddEventListenerResponse.schema.json b/packages/fdc3-schema/schemas/api/privateChannelAddEventListenerResponse.schema.json
@@ -24,6 +24,9 @@
 						}
 					]
 				},
+				"metadata": {
+					"$ref": "api.schema.json#/definitions/DesktopAgentProvidableContextMetadata"
+				},
 				"meta": true
 			},
 			"additionalProperties": false
diff --git a/packages/fdc3-schema/schemas/api/raiseIntentForContextRequest.schema.json b/packages/fdc3-schema/schemas/api/raiseIntentForContextRequest.schema.json
@@ -17,6 +17,9 @@
 				"payload": {
 					"$ref": "#/$defs/RaiseIntentForContextRequestPayload"
 				},
+				"metadata": {
+					"$ref": "api.schema.json#/definitions/AppProvidableContextMetadata"
+				},
 				"meta": true
 			},
 			"additionalProperties": false
diff --git a/packages/fdc3-schema/schemas/api/raiseIntentForContextResponse.schema.json b/packages/fdc3-schema/schemas/api/raiseIntentForContextResponse.schema.json
diff --git a/packages/fdc3-schema/schemas/api/raiseIntentRequest.schema.json b/packages/fdc3-schema/schemas/api/raiseIntentRequest.schema.json
diff --git a/packages/fdc3-standard/src/api/Channel.ts b/packages/fdc3-standard/src/api/Channel.ts
diff --git a/packages/fdc3-standard/src/api/ContextMetadata.ts b/packages/fdc3-standard/src/api/ContextMetadata.ts
diff --git a/packages/fdc3-standard/src/api/DesktopAgent.ts b/packages/fdc3-standard/src/api/DesktopAgent.ts
diff --git a/packages/fdc3-standard/src/api/Types.ts b/packages/fdc3-standard/src/api/Types.ts
diff --git a/website/docs/api/spec.md b/website/docs/api/spec.md

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`import {`
`2`	`2`	`AppIdentifier,`
`3`	`3`	`AppMetadata,`
	`4`	`+ AppProvidableContextMetadata,`
`4`	`5`	`ContextHandler,`
`5`	`6`	`DesktopAgent,`
`6`	`7`	`EventHandler,`
`@@ -82,10 +83,10 @@ export class DesktopAgentProxy implements DesktopAgent, Connectable {`
`82`	`83`	`return this.apps.getImplementationMetadata();`
`83`	`84`	`}`
`84`	`85`
`85`		`- async broadcast(context: Context): Promise<void> {`
	`86`	`+ async broadcast(context: Context, metadata?: AppProvidableContextMetadata): Promise<void> {`
`86`	`87`	`const channel = await this.channels.getUserChannel();`
`87`	`88`	`if (channel) {`
`88`		`- return channel.broadcast(context);`
	`89`	`+ return channel.broadcast(context, metadata);`
`89`	`90`	`} else {`
`90`	`91`	`return Promise.resolve();`
`91`	`92`	`}`
`@@ -169,20 +170,24 @@ export class DesktopAgentProxy implements DesktopAgent, Connectable {`
`169`	`170`	`}`
`170`	`171`	`}`
`171`	`172`
`172`		`- raiseIntent(intent: string, context: Context, app?: string \| AppIdentifier) {`
`173`		`- return this.intents.raiseIntent(intent, context, this.ensureAppId(app));`
	`173`	`+ raiseIntent(intent: string, context: Context, app?: string \| AppIdentifier, metadata?: AppProvidableContextMetadata) {`
	`174`	`+ return this.intents.raiseIntent(intent, context, this.ensureAppId(app), metadata);`
`174`	`175`	`}`
`175`	`176`
`176`	`177`	`addIntentListener(intent: string, handler: IntentHandler) {`
`177`	`178`	`return this.intents.addIntentListener(intent, handler);`
`178`	`179`	`}`
`179`	`180`
`180`		`- raiseIntentForContext(context: Context, app?: string \| AppIdentifier): Promise<IntentResolution> {`
`181`		`- return this.intents.raiseIntentForContext(context, this.ensureAppId(app));`
	`181`	`+ raiseIntentForContext(`
	`182`	`+ context: Context,`
	`183`	`+ app?: string \| AppIdentifier,`
	`184`	`+ metadata?: AppProvidableContextMetadata`
	`185`	`+ ): Promise<IntentResolution> {`
	`186`	`+ return this.intents.raiseIntentForContext(context, this.ensureAppId(app), metadata);`
`182`	`187`	`}`
`183`	`188`
`184`		`- open(app: string \| AppIdentifier, context?: Context \| undefined) {`
`185`		`- return this.apps.open(this.ensureAppId(app)!, context);`
	`189`	`+ open(app: string \| AppIdentifier, context?: Context, metadata?: AppProvidableContextMetadata) {`
	`190`	`+ return this.apps.open(this.ensureAppId(app)!, context, metadata);`
`186`	`191`	`}`
`187`	`192`
`188`	`193`	`findInstances(app: AppIdentifier) {`
Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,9 @@`
`24`	`24`	`}`
`25`	`25`	`]`
`26`	`26`	`},`
	`27`	`+ "metadata": {`
	`28`	`+ "$ref": "api.schema.json#/definitions/DesktopAgentProvidableContextMetadata"`
	`29`	`+ },`
`27`	`30`	`"meta": true`
`28`	`31`	`},`
`29`	`32`	`"additionalProperties": false`