Add support for returning context with Intent results

Includes docs & specs, types, tests, ref implementation and conformance tests)

Author: kriswest

CHANGELOG.md

@@ -17,6 +17,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added `ContextMetadata` and `AppProvidableContextMetadata` types, replacing the optional `OriginatingAppMetadata` feature with required metadata support on `ContextHandler` and `IntentHandler` callbacks. Desktop Agents MUST provide `source` and `timestamp` metadata, and MUST forward app-supplied `traceId`, `signature` and `custom` fields, supporting observability and security use cases. ([#1728](https://github.com/finos/FDC3/pull/1728))
 * Added `version-check` script and integrated it into the `syncpack` script and Publish To NPM workflow to prevent version mismatches causing incorrect npm dist-tags. ([#1864](https://github.com/finos/FDC3/pull/1864))
 * Added Channel Interface Compliance and PrivateChannel Interface Compliance subsections to the Desktop Agent API Standard Compliance section in the API spec, enumerating MUST/SHOULD/MAY requirements for all `Channel` and `PrivateChannel` functions including `getCurrentContextWithMetadata`. ([#1728](https://github.com/finos/FDC3/pull/1728))
+* Added `getResultMetadata()` to `IntentResolution` to allow the raising app to retrieve `ContextMetadata` for an intent result. Updated `IntentHandler` to allow returning `ContextWithMetadata` so that handlers can include app-provided metadata (e.g. `traceId`, `signature`) alongside a context result. The Desktop Agent merges app-provided metadata with its own generated fields before delivering to the raising app. For `Channel` or `void` results, only Desktop Agent generated metadata is returned. ([#1728](https://github.com/finos/FDC3/pull/1728))
 
 ### Changed
 

packages/fdc3-agent-proxy/src/intents/DefaultIntentResolution.ts

@@ -1,23 +1,36 @@
-import { AppIdentifier, IntentResolution, IntentResult } from '@finos/fdc3-standard';
+import { AppIdentifier, ContextMetadata, IntentResolution, IntentResult } from '@finos/fdc3-standard';
 import { Messaging } from '../Messaging.js';
 
 export class DefaultIntentResolution implements IntentResolution {
   readonly messaging: Messaging;
   readonly source: AppIdentifier;
   readonly intent: string;
   readonly result: Promise<IntentResult>;
+  readonly resultMetadata: Promise<ContextMetadata>;
 
-  constructor(messaging: Messaging, result: Promise<IntentResult>, source: AppIdentifier, intent: string) {
+  constructor(
+    messaging: Messaging,
+    result: Promise<IntentResult>,
+    resultMetadata: Promise<ContextMetadata>,
+    source: AppIdentifier,
+    intent: string
+  ) {
     this.messaging = messaging;
     this.result = result;
+    this.resultMetadata = resultMetadata;
     this.source = source;
     this.intent = intent;
 
     //bind all functions to allow destructuring
     this.getResult = this.getResult.bind(this);
+    this.getResultMetadata = this.getResultMetadata.bind(this);
   }
 
   getResult(): Promise<IntentResult> {
     return this.result;
   }
+
+  getResultMetadata(): Promise<ContextMetadata> {
+    return this.resultMetadata;
+  }
 }

packages/fdc3-agent-proxy/src/intents/DefaultIntentSupport.ts

@@ -1,6 +1,7 @@
 import {
   AppIntent,
   AppIdentifier,
+  ContextMetadata,
   IntentResolution,
   IntentHandler,
   Listener,
@@ -56,6 +57,17 @@ const convertIntentResult = async (
   }
 };
 
+const extractResultMetadata = ({ payload }: RaiseIntentResultResponse, source: AppIdentifier): ContextMetadata => {
+  const rm = payload.resultMetadata;
+  return {
+    source,
+    timestamp: rm?.timestamp ?? new Date(),
+    traceId: rm?.traceId ?? '',
+    ...(rm?.signature !== undefined && { signature: rm.signature }),
+    ...(rm?.custom !== undefined && { custom: rm.custom }),
+  };
+};
+
 export class DefaultIntentSupport implements IntentSupport {
   readonly messaging: Messaging;
   readonly intentResolver: IntentResolver;
@@ -123,13 +135,25 @@ export class DefaultIntentSupport implements IntentSupport {
     }
   }
 
-  private async createResultPromise(request: RaiseIntentRequest | RaiseIntentForContextRequest): Promise<IntentResult> {
-    const rp = await this.messaging.waitFor<RaiseIntentResultResponse>(
-      m => m.type == 'raiseIntentResultResponse' && m.meta.requestUuid == request.meta.requestUuid
-    );
+  private createResultPromises(
+    request: RaiseIntentRequest | RaiseIntentForContextRequest,
+    source: AppIdentifier
+  ): { result: Promise<IntentResult>; resultMetadata: Promise<ContextMetadata> } {
+    let resolveMetadata!: (m: ContextMetadata) => void;
+    const resultMetadata = new Promise<ContextMetadata>(resolve => {
+      resolveMetadata = resolve;
+    });
+
+    const result = this.messaging
+      .waitFor<RaiseIntentResultResponse>(
+        m => m.type == 'raiseIntentResultResponse' && m.meta.requestUuid == request.meta.requestUuid
+      )
+      .then(async rp => {
+        resolveMetadata(extractResultMetadata(rp, source));
+        return convertIntentResult(rp, this.messaging, this.messageExchangeTimeout);
+      });
 
-    const ir = await convertIntentResult(rp, this.messaging, this.messageExchangeTimeout);
-    return ir;
+    return { result, resultMetadata };
   }
 
   async raiseIntent(
@@ -154,7 +178,6 @@ export class DefaultIntentSupport implements IntentSupport {
       meta,
     };
 
-    const resultPromise = this.createResultPromise(request);
     const response = await this.messaging.exchange<RaiseIntentResponse>(
       request,
       'raiseIntentResponse',
@@ -170,19 +193,29 @@ export class DefaultIntentSupport implements IntentSupport {
 
     if (response.payload.appIntent) {
       // Needs further resolution, we need to invoke the resolver
-      const result: IntentResolutionChoice | void = await this.intentResolver.chooseIntent(
+      const choice: IntentResolutionChoice | void = await this.intentResolver.chooseIntent(
         [response.payload.appIntent],
         context
       );
-      if (result) {
-        return this.raiseIntent(intent, context, result.appId, metadata);
+      if (choice) {
+        return this.raiseIntent(intent, context, choice.appId, metadata);
       } else {
         throw new Error(ResolveError.UserCancelled);
       }
     } else {
       // Was resolved
       const details = response.payload.intentResolution!;
-      return new DefaultIntentResolution(this.messaging, resultPromise, details.source, details.intent);
+      const { result: resolvedResult, resultMetadata: resolvedMetadata } = this.createResultPromises(
+        request,
+        details.source
+      );
+      return new DefaultIntentResolution(
+        this.messaging,
+        resolvedResult,
+        resolvedMetadata,
+        details.source,
+        details.intent
+      );
     }
   }
 
@@ -206,7 +239,6 @@ export class DefaultIntentSupport implements IntentSupport {
       meta,
     };
 
-    const resultPromise = this.createResultPromise(request);
     const response = await this.messaging.exchange<RaiseIntentForContextResponse>(
       request,
       'raiseIntentForContextResponse',
@@ -222,19 +254,29 @@ export class DefaultIntentSupport implements IntentSupport {
 
     if (response.payload.appIntents) {
       // Needs further resolution, we need to invoke the resolver
-      const result: IntentResolutionChoice | void = await this.intentResolver.chooseIntent(
+      const choice: IntentResolutionChoice | void = await this.intentResolver.chooseIntent(
         response.payload.appIntents,
         context
       );
-      if (result) {
-        return this.raiseIntent(result.intent, context, result.appId, metadata);
+      if (choice) {
+        return this.raiseIntent(choice.intent, context, choice.appId, metadata);
       } else {
         throw new Error(ResolveError.UserCancelled);
       }
     } else {
       // Was resolved
       const details = response.payload.intentResolution!;
-      return new DefaultIntentResolution(this.messaging, resultPromise, details.source, details.intent);
+      const { result: resolvedResult, resultMetadata: resolvedMetadata } = this.createResultPromises(
+        request,
+        details.source
+      );
+      return new DefaultIntentResolution(
+        this.messaging,
+        resolvedResult,
+        resolvedMetadata,
+        details.source,
+        details.intent
+      );
     }
   }
 

packages/fdc3-agent-proxy/src/listeners/DefaultIntentListener.ts

@@ -1,4 +1,10 @@
-import { IntentHandler, IntentResult, AppIdentifier } from '@finos/fdc3-standard';
+import {
+  IntentHandler,
+  IntentResult,
+  AppIdentifier,
+  AppProvidableContextMetadata,
+  ContextWithMetadata,
+} from '@finos/fdc3-standard';
 import { Context } from '@finos/fdc3-context';
 import { Messaging } from '../Messaging.js';
 import { AbstractListener } from './AbstractListener.js';
@@ -44,7 +50,11 @@ export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIn
     this.handleIntentResult(done, m);
   }
 
-  private intentResultRequestMessage(ir: IntentResult, m: IntentEvent): IntentResultRequest {
+  private intentResultRequestMessage(
+    ir: IntentResult,
+    appMetadata: AppProvidableContextMetadata | undefined,
+    m: IntentEvent
+  ): IntentResultRequest {
     const out: IntentResultRequest = {
       type: 'intentResultRequest',
       meta: {
@@ -55,25 +65,25 @@ export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIn
         intentResult: convertIntentResult(ir),
         intentEventUuid: m.meta.eventUuid,
         raiseIntentRequestUuid: m.payload.raiseIntentRequestUuid,
+        ...(appMetadata !== undefined && { metadata: appMetadata }),
       },
     };
 
     return out;
   }
 
-  private handleIntentResult(done: Promise<IntentResult> | void, m: IntentEvent) {
+  private handleIntentResult(done: Promise<IntentResult | ContextWithMetadata> | void, m: IntentEvent) {
     if (done == null) {
-      // send an empty intent result response
       return this.messaging.exchange<IntentResultResponse>(
-        this.intentResultRequestMessage(undefined, m),
+        this.intentResultRequestMessage(undefined, undefined, m),
         'intentResultResponse',
         this.messageExchangeTimeout
       );
     } else {
-      // respond after promise completes
-      return done.then(ir => {
+      return done.then(raw => {
+        const { result, appMetadata } = unwrapIntentResult(raw);
         return this.messaging.exchange<IntentResultResponse>(
-          this.intentResultRequestMessage(ir, m),
+          this.intentResultRequestMessage(result, appMetadata, m),
           'intentResultResponse',
           this.messageExchangeTimeout
         );
@@ -82,6 +92,18 @@ export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIn
   }
 }
 
+function unwrapIntentResult(raw: IntentResult | ContextWithMetadata): {
+  result: IntentResult;
+  appMetadata: AppProvidableContextMetadata | undefined;
+} {
+  if (raw && typeof raw === 'object' && 'context' in raw && 'metadata' in raw && !('type' in raw) && !('id' in raw)) {
+    // It's a ContextWithMetadata — unwrap it
+    const cwm = raw as ContextWithMetadata;
+    return { result: cwm.context, appMetadata: cwm.metadata };
+  }
+  return { result: raw as IntentResult, appMetadata: undefined };
+}
+
 function convertIntentResult(intentResult: IntentResult): IntentResultRequest['payload']['intentResult'] {
   if (!intentResult) {
     //consider any falsy result to be void...

packages/fdc3-agent-proxy/test/features/intent-results.feature

@@ -126,3 +126,35 @@ Feature: Intents Can Return Different Results
     And messaging will have posts
       | payload.intent | payload.context.type | payload.context.id.ticker | matches_type       |
       | OrderFood      | fdc3.instrument      | AAPL                      | raiseIntentRequest |
+
+  Scenario: getResultMetadata returns DA-generated metadata for a context result
+    Given Raise Intent returns a context of "{instrumentContext}"
+    When I call "{api}" with "raiseIntent" with parameters "OrderFood" and "{instrumentContext}"
+    And I call "{result}" with "getResultMetadata"
+    Then "{result}" is an object with the following contents
+      | source.appId | source.instanceId |
+      | some-app     | abc123            |
+
+  Scenario: getResultMetadata returns merged metadata when ContextWithMetadata is returned
+    Given Raise Intent returns a context of "{instrumentContext}" with traceId "my-trace-123" and signature "sig-abc"
+    When I call "{api}" with "raiseIntent" with parameters "OrderFood" and "{instrumentContext}"
+    And I call "{result}" with "getResultMetadata"
+    Then "{result}" is an object with the following contents
+      | source.appId | source.instanceId | traceId       | signature |
+      | some-app     | abc123            | my-trace-123  | sig-abc   |
+
+  Scenario: getResultMetadata returns DA-generated metadata for a channel result
+    Given Raise Intent returns a private channel
+    When I call "{api}" with "raiseIntent" with parameters "OrderFood" and "{instrumentContext}"
+    And I call "{result}" with "getResultMetadata"
+    Then "{result}" is an object with the following contents
+      | source.appId | source.instanceId |
+      | some-app     | abc123            |
+
+  Scenario: getResultMetadata returns DA-generated metadata for a void result
+    Given Raise Intent returns no result
+    When I call "{api}" with "raiseIntent" with parameters "OrderFood" and "{instrumentContext}"
+    And I call "{result}" with "getResultMetadata"
+    Then "{result}" is an object with the following contents
+      | source.appId | source.instanceId |
+      | some-app     | abc123            |

packages/fdc3-agent-proxy/test/step-definitions/intents.steps.ts

@@ -82,6 +82,22 @@ Given('Raise Intent returns a context of {string}', (world: CustomWorld, result:
   });
 });
 
+Given(
+  'Raise Intent returns a context of {string} with traceId {string} and signature {string}',
+  (world: CustomWorld, result: string, traceId: string, signature: string) => {
+    world.messaging?.setIntentResult({
+      context: handleResolve(result, world),
+      resultMetadata: {
+        source: { appId: 'some-app', instanceId: 'abc123' },
+        timestamp: new Date('2024-01-01T00:00:00Z'),
+        traceId,
+        signature,
+        custom: { priority: 'high' },
+      },
+    });
+  }
+);
+
 Given('Raise Intent will throw a {string} error', (world: CustomWorld, error: ResolveError) => {
   world.messaging?.setIntentResult({
     error,

packages/fdc3-agent-proxy/test/support/TestMessaging.ts

@@ -1,4 +1,4 @@
-import { AppIdentifier, ResolveError } from '@finos/fdc3-standard';
+import { AppIdentifier, ContextMetadata, ResolveError } from '@finos/fdc3-standard';
 import { Context } from '@finos/fdc3-context';
 import { v4 as uuidv4 } from 'uuid';
 import { AbstractMessaging } from '../../src/messaging/AbstractMessaging.js';
@@ -45,6 +45,7 @@ export interface PossibleIntentResult {
   channel?: Channel;
   error?: ResolveError;
   timeout?: boolean;
+  resultMetadata?: ContextMetadata;
 }
 
 function matchStringOrUndefined(expected: string | undefined, actual: string | undefined) {

packages/fdc3-agent-proxy/test/support/responses/RaiseIntent.ts

@@ -121,6 +121,7 @@ export class RaiseIntent implements AutomaticResponse {
         meta: createResponseMeta(intentRequest.meta),
         payload: {
           intentResult: result,
+          ...(result.resultMetadata && { resultMetadata: result.resultMetadata }),
         },
         type: 'raiseIntentResultResponse',
       };

packages/fdc3-agent-proxy/test/support/responses/RaiseIntentForContext.ts

@@ -130,6 +130,7 @@ export class RaiseIntentForContext implements AutomaticResponse {
         },
         payload: {
           intentResult: result,
+          ...(result.resultMetadata && { resultMetadata: result.resultMetadata }),
         },
         type: 'raiseIntentResultResponse',
       };