@microsoft/agents-a365-observability-hosting 0.1.0-preview.95 → 0.2.0-preview.1

package/dist/esm/middleware/OutputLoggingMiddleware.js

@@ -0,0 +1,91 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { OutputScope, logger, isPerRequestExportEnabled, } from '@microsoft/agents-a365-observability';
+import { ScopeUtils } from '../utils/ScopeUtils';
+import { AgenticTokenCacheInstance } from '../caching/AgenticTokenCache';
+/**
+ * TurnState key for the parent span reference.
+ * Set this in `turnState` to link OutputScope spans as children of an InvokeAgentScope.
+ */
+export const A365_PARENT_SPAN_KEY = 'A365ParentSpanId';
+/**
+ * TurnState key for the auth token.
+ * Set this in `turnState` so middleware can resolve the agent blueprint ID
+ * from token claims (used for embodied/agentic requests).
+ */
+export const A365_AUTH_TOKEN_KEY = 'A365AuthToken';
+/**
+ * Middleware that creates {@link OutputScope} spans for outgoing messages.
+ * Links to a parent span when {@link A365_PARENT_SPAN_KEY} is set in turnState.
+ *
+ * **Privacy note:** Outgoing message content is captured verbatim
+ * as span attributes and exported to the configured telemetry backend.
+ */
+export class OutputLoggingMiddleware {
+    async onTurn(context, next) {
+        const authToken = this.resolveAuthToken(context);
+        const agentDetails = ScopeUtils.deriveAgentDetails(context, authToken);
+        if (!agentDetails || !agentDetails.tenantId) {
+            await next();
+            return;
+        }
+        const userDetails = ScopeUtils.deriveCallerDetails(context);
+        const conversationId = ScopeUtils.deriveConversationId(context);
+        const channel = ScopeUtils.deriveChannelObject(context);
+        const request = {
+            conversationId,
+            channel,
+        };
+        context.onSendActivities(this._createSendHandler(context, agentDetails, userDetails, request));
+        await next();
+    }
+    /**
+     * Resolve the auth token for agent identity resolution.
+     * When per-request export is enabled, reads from turnState.
+     * Otherwise, reads from the cached observability token.
+     */
+    resolveAuthToken(context) {
+        if (isPerRequestExportEnabled()) {
+            return context.turnState.get(A365_AUTH_TOKEN_KEY) ?? '';
+        }
+        const agentId = context.activity?.getAgenticInstanceId?.() ?? '';
+        const tenantId = context.activity?.getAgenticTenantId?.() ?? '';
+        if (agentId && tenantId) {
+            return AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId) ?? '';
+        }
+        return '';
+    }
+    /**
+     * Creates a send handler that wraps outgoing messages in OutputScope spans.
+     * Reads parent span ref lazily so the agent handler can set it during `next()`.
+     */
+    _createSendHandler(turnContext, agentDetails, userDetails, request) {
+        return async (_ctx, activities, sendNext) => {
+            const messages = activities
+                .filter((a) => a.type === 'message' && a.text)
+                .map((a) => a.text);
+            if (messages.length === 0) {
+                return await sendNext();
+            }
+            const parentSpanRef = turnContext.turnState.get(A365_PARENT_SPAN_KEY);
+            if (!parentSpanRef) {
+                logger.warn(`[OutputLoggingMiddleware] No parent span ref in turnState under '${A365_PARENT_SPAN_KEY}'. OutputScope will not be linked to a parent.`);
+            }
+            const spanDetails = parentSpanRef
+                ? { parentContext: parentSpanRef }
+                : undefined;
+            const outputScope = OutputScope.start(request ?? {}, { messages }, agentDetails, userDetails, spanDetails);
+            try {
+                return await sendNext();
+            }
+            catch (error) {
+                outputScope.recordError(error instanceof Error ? error : new Error(typeof error === 'string' ? error : JSON.stringify(error)));
+                throw error;
+            }
+            finally {
+                outputScope.dispose();
+            }
+        };
+    }
+}
+//# sourceMappingURL=OutputLoggingMiddleware.js.map

package/dist/esm/middleware/OutputLoggingMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OutputLoggingMiddleware.js","sourceRoot":"","sources":["../../../src/middleware/OutputLoggingMiddleware.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/BaggageBuilderUtils.d.ts

@@ -18,13 +18,6 @@ export declare class BaggageBuilderUtils {
      * @returns The updated BaggageBuilder instance.
      */
     static setCallerBaggage(builder: BaggageBuilder, turnContext: TurnContext): BaggageBuilder;
-    /**
-     * Sets the execution type baggage value based on caller and recipient agentic status.
-     * @param builder The BaggageBuilder instance.
-     * @param turnContext The TurnContext containing activity information.
-     * @returns The updated BaggageBuilder instance.
-     */
-    static setExecutionTypeBaggage(builder: BaggageBuilder, turnContext: TurnContext): BaggageBuilder;
     /**
      * Sets the target agent-related baggage values from the TurnContext.
      * @param builder The BaggageBuilder instance.
@@ -40,12 +33,12 @@ export declare class BaggageBuilderUtils {
      */
     static setTenantIdBaggage(builder: BaggageBuilder, turnContext: TurnContext): BaggageBuilder;
     /**
-     * Sets the source metadata baggage values from the TurnContext.
+     * Sets the channel baggage values from the TurnContext.
      * @param builder The BaggageBuilder instance.
      * @param turnContext The TurnContext containing activity information.
      * @returns The updated BaggageBuilder instance.
      */
-    static setSourceMetadataBaggage(builder: BaggageBuilder, turnContext: TurnContext): BaggageBuilder;
+    static setChannelBaggage(builder: BaggageBuilder, turnContext: TurnContext): BaggageBuilder;
     /**
      * Sets the conversation ID and item link baggage values from the TurnContext.
      * @param builder The BaggageBuilder instance.

package/dist/esm/utils/BaggageBuilderUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaggageBuilderUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/BaggageBuilderUtils.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AASxD,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAItE;;GAEG;AACH,qBAAa,mBAAmB;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAazF;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAM1F;;;;;OAKG;IACH,MAAM,CAAC,uBAAuB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAMjG;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAM/F;;;;;OAKG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAM5F;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAMlG;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;CAInG"}
+{"version":3,"file":"BaggageBuilderUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/BaggageBuilderUtils.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAQxD,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAItE;;GAEG;AACH,qBAAa,mBAAmB;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAYzF;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAM1F;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAM/F;;;;;OAKG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAM5F;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;IAM3F;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,cAAc;CAInG"}

package/dist/esm/utils/BaggageBuilderUtils.js

@@ -2,7 +2,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 // ------------------------------------------------------------------------------
-import { getCallerBaggagePairs, getExecutionTypePair, getTargetAgentBaggagePairs, getTenantIdPair, getSourceMetadataBaggagePairs, getConversationIdAndItemLinkPairs } from './TurnContextUtils';
+import { getCallerBaggagePairs, getTargetAgentBaggagePairs, getTenantIdPair, getChannelBaggagePairs, getConversationIdAndItemLinkPairs } from './TurnContextUtils';
 /**
  * Utilities to populate BaggageBuilder from a TurnContext.
  */
@@ -18,10 +18,9 @@ export class BaggageBuilderUtils {
             throw new Error('turnContext is required');
         }
         this.setCallerBaggage(builder, turnContext);
-        this.setExecutionTypeBaggage(builder, turnContext);
         this.setTargetAgentBaggage(builder, turnContext);
         this.setTenantIdBaggage(builder, turnContext);
-        this.setSourceMetadataBaggage(builder, turnContext);
+        this.setChannelBaggage(builder, turnContext);
         this.setConversationIdBaggage(builder, turnContext);
         return builder;
     }
@@ -35,16 +34,6 @@ export class BaggageBuilderUtils {
         builder.setPairs(getCallerBaggagePairs(turnContext));
         return builder;
     }
-    /**
-     * Sets the execution type baggage value based on caller and recipient agentic status.
-     * @param builder The BaggageBuilder instance.
-     * @param turnContext The TurnContext containing activity information.
-     * @returns The updated BaggageBuilder instance.
-     */
-    static setExecutionTypeBaggage(builder, turnContext) {
-        builder.setPairs(getExecutionTypePair(turnContext));
-        return builder;
-    }
     /**
      * Sets the target agent-related baggage values from the TurnContext.
      * @param builder The BaggageBuilder instance.
@@ -66,13 +55,13 @@ export class BaggageBuilderUtils {
         return builder;
     }
     /**
-     * Sets the source metadata baggage values from the TurnContext.
+     * Sets the channel baggage values from the TurnContext.
      * @param builder The BaggageBuilder instance.
      * @param turnContext The TurnContext containing activity information.
      * @returns The updated BaggageBuilder instance.
      */
-    static setSourceMetadataBaggage(builder, turnContext) {
-        builder.setPairs(getSourceMetadataBaggagePairs(turnContext));
+    static setChannelBaggage(builder, turnContext) {
+        builder.setPairs(getChannelBaggagePairs(turnContext));
         return builder;
     }
     /**

package/dist/esm/utils/BaggageBuilderUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"BaggageBuilderUtils.js","sourceRoot":"","sources":["../../../src/utils/BaggageBuilderUtils.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,uCAAuC;AACvC,kCAAkC;AAClC,iFAAiF;AAGjF,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,eAAe,EACf,6BAA6B,EAC7B,iCAAiC,EAClC,MAAM,oBAAoB,CAAC;AAK5B;;GAEG;AACH,MAAM,OAAO,mBAAmB;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,OAAuB,EAAE,WAAwB;QACtE,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC5C,IAAI,CAAC,uBAAuB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,qBAAqB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACjD,IAAI,CAAC,kBAAkB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC9C,IAAI,CAAC,wBAAwB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACpD,IAAI,CAAC,wBAAwB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACpD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAuB,EAAE,WAAwB;QACvE,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC,CAAC;QACrD,OAAO,OAAO,CAAC;IACjB,CAAC;IAGD;;;;;OAKG;IACH,MAAM,CAAC,uBAAuB,CAAC,OAAuB,EAAE,WAAwB;QAC9E,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,CAAC;QACpD,OAAO,OAAO,CAAC;IACjB,CAAC;IAGD;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,OAAuB,EAAE,WAAwB;QAC5E,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAC,WAAW,CAAC,CAAC,CAAC;QAC1D,OAAO,OAAO,CAAC;IACjB,CAAC;IAGD;;;;;OAKG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAuB,EAAE,WAAwB;QACzE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC;QAC/C,OAAO,OAAO,CAAC;IACjB,CAAC;IAGD;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,OAAuB,EAAE,WAAwB;QAC/E,OAAO,CAAC,QAAQ,CAAC,6BAA6B,CAAC,WAAW,CAAC,CAAC,CAAC;QAC7D,OAAO,OAAO,CAAC;IACjB,CAAC;IAGD;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,OAAuB,EAAE,WAAwB;QAC/E,OAAO,CAAC,QAAQ,CAAC,iCAAiC,CAAC,WAAW,CAAC,CAAC,CAAC;QACjE,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}
+{"version":3,"file":"BaggageBuilderUtils.js","sourceRoot":"","sources":["../../../src/utils/BaggageBuilderUtils.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,uCAAuC;AACvC,kCAAkC;AAClC,iFAAiF;AAGjF,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,eAAe,EACf,sBAAsB,EACtB,iCAAiC,EAClC,MAAM,oBAAoB,CAAC;AAK5B;;GAEG;AACH,MAAM,OAAO,mBAAmB;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,OAAuB,EAAE,WAAwB;QACtE,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC5C,IAAI,CAAC,qBAAqB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACjD,IAAI,CAAC,kBAAkB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC9C,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC7C,IAAI,CAAC,wBAAwB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACpD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAuB,EAAE,WAAwB;QACvE,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC,CAAC;QACrD,OAAO,OAAO,CAAC;IACjB,CAAC;IAGD;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,OAAuB,EAAE,WAAwB;QAC5E,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAC,WAAW,CAAC,CAAC,CAAC;QAC1D,OAAO,OAAO,CAAC;IACjB,CAAC;IAGD;;;;;OAKG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAuB,EAAE,WAAwB;QACzE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC;QAC/C,OAAO,OAAO,CAAC;IACjB,CAAC;IAGD;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAuB,EAAE,WAAwB;QACxE,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,WAAW,CAAC,CAAC,CAAC;QACtD,OAAO,OAAO,CAAC;IACjB,CAAC;IAGD;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,OAAuB,EAAE,WAAwB;QAC/E,OAAO,CAAC,QAAQ,CAAC,iCAAiC,CAAC,WAAW,CAAC,CAAC,CAAC;QACjE,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/dist/esm/utils/ScopeUtils.d.ts

@@ -1,23 +1,21 @@
 import { TurnContext } from '@microsoft/agents-hosting';
-import { InvokeAgentScope, InferenceScope, ExecuteToolScope, AgentDetails, TenantDetails, CallerDetails, InferenceDetails, InvokeAgentDetails, ToolCallDetails } from '@microsoft/agents-a365-observability';
+import { SpanKind, TimeInput } from '@opentelemetry/api';
+import { InvokeAgentScope, InferenceScope, ExecuteToolScope, AgentDetails, UserDetails, InferenceDetails, ToolCallDetails, InvokeAgentScopeDetails } from '@microsoft/agents-a365-observability';
 /**
  * Unified utilities to populate scope tags from a TurnContext.
  * Provides common tag population and scope-specific helpers.
  */
 export declare class ScopeUtils {
     private static setInputMessageTags;
-    /**
-     * Derive tenant details from the TurnContext.
-     * @param turnContext Activity context
-     * @returns Tenant details if a recipient tenant id is present; otherwise undefined.
-     */
-    static deriveTenantDetails(turnContext: TurnContext): TenantDetails | undefined;
     /**
      * Derive target agent details from the activity recipient.
+     * Uses {@link resolveEmbodiedAgentIds} to resolve the agent ID and blueprint ID, which are only
+     * set for embodied (agentic) agents — see that function for the rationale.
      * @param turnContext Activity context
+     * @param authToken Auth token for resolving agent identity from token claims.
      * @returns Agent details built from recipient properties; otherwise undefined.
      */
-    static deriveAgentDetails(turnContext: TurnContext): AgentDetails | undefined;
+    static deriveAgentDetails(turnContext: TurnContext, authToken: string): AgentDetails | undefined;
     /**
      * Derive caller agent details from the activity from.
      * @param turnContext Activity context
@@ -25,11 +23,11 @@ export declare class ScopeUtils {
      */
     static deriveCallerAgent(turnContext: TurnContext): AgentDetails | undefined;
     /**
-     * Derive caller identity details (id, upn, name, tenant, client ip) from the activity from.
+     * Derive caller identity details (id, email, name, tenant) from the activity from.
      * @param turnContext Activity context
-     * @returns Caller details when available; otherwise undefined.
+     * @returns User details when available; otherwise undefined.
      */
-    static deriveCallerDetails(turnContext: TurnContext): CallerDetails | undefined;
+    static deriveCallerDetails(turnContext: TurnContext): UserDetails | undefined;
     /**
      * Derive conversation id from the TurnContext.
      * @param turnContext Activity context
@@ -37,47 +35,62 @@ export declare class ScopeUtils {
      */
     static deriveConversationId(turnContext: TurnContext): string | undefined;
     /**
-     * Derive source metadata (channel name and description/link) from the TurnContext.
+     * Derive channel (name and description) from the TurnContext.
      * @param turnContext Activity context
      * @returns Object with optional name and description fields.
      */
-    static deriveSourceMetadataObject(turnContext: TurnContext): {
+    static deriveChannelObject(turnContext: TurnContext): {
         name?: string;
         description?: string;
     };
     /**
      * Create an `InferenceScope` using `details` and values derived from the provided `TurnContext`.
-     * Derives `agentDetails`, `tenantDetails`, `conversationId`, and `sourceMetadata` (channel name/link) from context.
+     * Derives `conversationId` and `channel` (name/description) from context.
      * Also records input messages from the context if present.
      * @param details The inference call details (model, provider, tokens, etc.).
      * @param turnContext The current activity context to derive scope parameters from.
+     * @param authToken Auth token for resolving agent identity from token claims.
+     * @param startTime Optional explicit start time (ms epoch, Date, or HrTime).
+     * @param endTime Optional explicit end time (ms epoch, Date, or HrTime).
      * @returns A started `InferenceScope` enriched with context-derived parameters.
      */
-    static populateInferenceScopeFromTurnContext(details: InferenceDetails, turnContext: TurnContext): InferenceScope;
+    static populateInferenceScopeFromTurnContext(details: InferenceDetails, turnContext: TurnContext, authToken: string, startTime?: TimeInput, endTime?: TimeInput): InferenceScope;
     /**
      * Create an `InvokeAgentScope` using `details` and values derived from the provided `TurnContext`.
-     * Populates `conversationId` and `request.sourceMetadata` (channel name/link) in `details` from the `TurnContext`, overriding any existing values.
-     * Derives `tenantDetails`, `callerAgentDetails` (from caller), and `callerDetails` (from user).
-     * Also sets execution type and input messages from the context if present.
-     * @param details The invoke-agent call details to be augmented and used for the scope.
+     * Builds a separate `Request` with `conversationId` and `channel` from context.
+     * Merges agent identity from context into `details` via `buildInvokeAgentDetailsCore`.
+     * Derives `callerAgentDetails` (from caller) and `userDetails` (human caller).
+     * Also records input messages from the context if present.
+     * @param details The agent details to be augmented with context-derived identity.
      * @param turnContext The current activity context to derive scope parameters from.
+     * @param authToken Auth token for resolving agent identity from token claims.
+     * @param startTime Optional explicit start time (ms epoch, Date, or HrTime).
+     * @param endTime Optional explicit end time (ms epoch, Date, or HrTime).
+     * @param spanKind Optional span kind override. Defaults to `SpanKind.CLIENT`.
      * @returns A started `InvokeAgentScope` enriched with context-derived parameters.
      */
-    static populateInvokeAgentScopeFromTurnContext(details: InvokeAgentDetails, turnContext: TurnContext): InvokeAgentScope;
+    static populateInvokeAgentScopeFromTurnContext(details: AgentDetails, scopeDetails: InvokeAgentScopeDetails, turnContext: TurnContext, authToken: string, startTime?: TimeInput, endTime?: TimeInput, spanKind?: SpanKind): InvokeAgentScope;
     /**
-     * Build InvokeAgentDetails by merging provided details with agent info, conversation id and source metadata from the TurnContext.
-     * @param details Base invoke-agent details to augment
+     * Build agent details by merging provided details with agent info from the TurnContext.
+     * @param details Base agent details to augment
      * @param turnContext Activity context
-     * @returns New InvokeAgentDetails suitable for starting an InvokeAgentScope.
+     * @param authToken Auth token for resolving agent identity from token claims.
+     * @returns Merged AgentDetails with context-derived identity.
      */
-    static buildInvokeAgentDetails(details: InvokeAgentDetails, turnContext: TurnContext): InvokeAgentDetails;
+    static buildInvokeAgentDetails(details: AgentDetails, turnContext: TurnContext, authToken: string): AgentDetails;
+    private static buildInvokeAgentDetailsCore;
     /**
      * Create an `ExecuteToolScope` using `details` and values derived from the provided `TurnContext`.
-     * Derives `agentDetails`, `tenantDetails`, `conversationId`, and `sourceMetadata` (channel name/link) from context.
+     * Derives `conversationId` and `channel` (name/link) from context.
      * @param details The tool call details (name, type, args, call id, etc.).
      * @param turnContext The current activity context to derive scope parameters from.
+     * @param authToken Auth token for resolving agent identity from token claims.
+     * @param startTime Optional explicit start time (ms epoch, Date, or HrTime). Useful when recording a
+     *        tool call after execution has already completed.
+     * @param endTime Optional explicit end time (ms epoch, Date, or HrTime).
+     * @param spanKind Optional span kind override. Defaults to `SpanKind.INTERNAL`.
      * @returns A started `ExecuteToolScope` enriched with context-derived parameters.
      */
-    static populateExecuteToolScopeFromTurnContext(details: ToolCallDetails, turnContext: TurnContext): ExecuteToolScope;
+    static populateExecuteToolScopeFromTurnContext(details: ToolCallDetails, turnContext: TurnContext, authToken: string, startTime?: TimeInput, endTime?: TimeInput, spanKind?: SpanKind): ExecuteToolScope;
 }
 //# sourceMappingURL=ScopeUtils.d.ts.map

package/dist/esm/utils/ScopeUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScopeUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/ScopeUtils.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAEhB,MAAM,sCAAsC,CAAC;AAK9C;;;GAGG;AACH,qBAAa,UAAU;IAGrB,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAUlC;;;;OAIG;WACW,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS;IAKtF;;;;OAIG;WACW,kBAAkB,CAAC,WAAW,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS;IAapF;;;;OAIG;WACW,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS;IAcnF;;;;OAIG;WACW,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS;IAWtF;;;;OAIG;WACW,oBAAoB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS;IAIhF;;;;OAIG;WACW,0BAA0B,CAAC,WAAW,EAAE,WAAW,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE;IAO3G;;;;;;;OAOG;IACH,MAAM,CAAC,qCAAqC,CAC1C,OAAO,EAAE,gBAAgB,EACzB,WAAW,EAAE,WAAW,GACvB,cAAc;IAkBjB;;;;;;;;OAQG;IACH,MAAM,CAAC,uCAAuC,CAC5C,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,WAAW,GACvB,gBAAgB;IAenB;;;;;OAKG;WACW,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,GAAG,kBAAkB;IAuBhH;;;;;;OAMG;IACH,MAAM,CAAC,uCAAuC,CAC5C,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,WAAW,GACvB,gBAAgB;CAcpB"}
+{"version":3,"file":"ScopeUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/ScopeUtils.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAEX,gBAAgB,EAChB,eAAe,EAGf,uBAAuB,EACxB,MAAM,sCAAsC,CAAC;AAG9C;;;GAGG;AACH,qBAAa,UAAU;IAGrB,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAalC;;;;;;;OAOG;WACW,kBAAkB,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAgBvG;;;;OAIG;WACW,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS;IAenF;;;;OAIG;WACW,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS;IAWpF;;;;OAIG;WACW,oBAAoB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS;IAIhF;;;;OAIG;WACW,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE;IAOpG;;;;;;;;;;OAUG;IACH,MAAM,CAAC,qCAAqC,CAC1C,OAAO,EAAE,gBAAgB,EACzB,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE,SAAS,GAClB,cAAc;IAyBjB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,uCAAuC,CAC5C,OAAO,EAAE,YAAY,EACrB,YAAY,EAAE,uBAAuB,EACrC,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE,SAAS,EACnB,QAAQ,CAAC,EAAE,QAAQ,GAClB,gBAAgB;IA+BnB;;;;;;OAMG;WACW,uBAAuB,CAAC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY;IAIvH,OAAO,CAAC,MAAM,CAAC,2BAA2B;IAY1C;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,uCAAuC,CAC5C,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE,SAAS,EACnB,QAAQ,CAAC,EAAE,QAAQ,GAClB,gBAAgB;CAwBpB"}

package/dist/esm/utils/ScopeUtils.js

@@ -2,8 +2,8 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 // ------------------------------------------------------------------------------
-import { InvokeAgentScope, InferenceScope, ExecuteToolScope } from '@microsoft/agents-a365-observability';
-import { getExecutionTypePair, } from './TurnContextUtils';
+import { InvokeAgentScope, InferenceScope, ExecuteToolScope, } from '@microsoft/agents-a365-observability';
+import { resolveEmbodiedAgentIds } from './TurnContextUtils';
 /**
  * Unified utilities to populate scope tags from a TurnContext.
  * Provides common tag population and scope-specific helpers.
@@ -18,30 +18,27 @@ export class ScopeUtils {
     // ----------------------
     // Context-derived helpers
     // ----------------------
-    /**
-     * Derive tenant details from the TurnContext.
-     * @param turnContext Activity context
-     * @returns Tenant details if a recipient tenant id is present; otherwise undefined.
-     */
-    static deriveTenantDetails(turnContext) {
-        const tenantId = turnContext?.activity?.recipient?.tenantId;
-        return tenantId ? { tenantId } : undefined;
-    }
     /**
      * Derive target agent details from the activity recipient.
+     * Uses {@link resolveEmbodiedAgentIds} to resolve the agent ID and blueprint ID, which are only
+     * set for embodied (agentic) agents — see that function for the rationale.
      * @param turnContext Activity context
+     * @param authToken Auth token for resolving agent identity from token claims.
      * @returns Agent details built from recipient properties; otherwise undefined.
      */
-    static deriveAgentDetails(turnContext) {
+    static deriveAgentDetails(turnContext, authToken) {
         const recipient = turnContext?.activity?.recipient;
         if (!recipient)
             return undefined;
+        const { agentId, agentBlueprintId } = resolveEmbodiedAgentIds(turnContext, authToken);
         return {
-            agentId: recipient.agenticAppId,
+            agentId,
             agentName: recipient.name,
             agentAUID: recipient.aadObjectId,
+            agentBlueprintId,
+            agentEmail: turnContext?.activity?.getAgenticUser?.(),
             agentDescription: recipient.role,
-            tenantId: recipient.tenantId
+            tenantId: turnContext?.activity?.getAgenticTenantId?.()
         };
     }
     /**
@@ -59,22 +56,23 @@ export class ScopeUtils {
             agentAUID: from.aadObjectId,
             agentDescription: from.role,
             tenantId: from.tenantId,
-            agentId: from.agenticAppId
+            agentId: from.agenticAppId,
+            agentEmail: from.agenticUserId
         };
     }
     /**
-     * Derive caller identity details (id, upn, name, tenant, client ip) from the activity from.
+     * Derive caller identity details (id, email, name, tenant) from the activity from.
      * @param turnContext Activity context
-     * @returns Caller details when available; otherwise undefined.
+     * @returns User details when available; otherwise undefined.
      */
     static deriveCallerDetails(turnContext) {
         const from = turnContext?.activity?.from;
         if (!from)
             return undefined;
         return {
-            callerId: from.aadObjectId,
-            callerUpn: from.agenticUserId,
-            callerName: from.name,
+            userId: from.aadObjectId,
+            userEmail: from.agenticUserId,
+            userName: from.name,
             tenantId: from.tenantId,
         };
     }
@@ -87,11 +85,11 @@ export class ScopeUtils {
         return turnContext?.activity?.conversation?.id;
     }
     /**
-     * Derive source metadata (channel name and description/link) from the TurnContext.
+     * Derive channel (name and description) from the TurnContext.
      * @param turnContext Activity context
      * @returns Object with optional name and description fields.
      */
-    static deriveSourceMetadataObject(turnContext) {
+    static deriveChannelObject(turnContext) {
         return {
             name: turnContext?.activity?.channelId,
             description: turnContext?.activity?.channelIdSubChannel
@@ -99,95 +97,122 @@ export class ScopeUtils {
     }
     /**
      * Create an `InferenceScope` using `details` and values derived from the provided `TurnContext`.
-     * Derives `agentDetails`, `tenantDetails`, `conversationId`, and `sourceMetadata` (channel name/link) from context.
+     * Derives `conversationId` and `channel` (name/description) from context.
      * Also records input messages from the context if present.
      * @param details The inference call details (model, provider, tokens, etc.).
      * @param turnContext The current activity context to derive scope parameters from.
+     * @param authToken Auth token for resolving agent identity from token claims.
+     * @param startTime Optional explicit start time (ms epoch, Date, or HrTime).
+     * @param endTime Optional explicit end time (ms epoch, Date, or HrTime).
      * @returns A started `InferenceScope` enriched with context-derived parameters.
      */
-    static populateInferenceScopeFromTurnContext(details, turnContext) {
-        const agent = ScopeUtils.deriveAgentDetails(turnContext);
-        const tenant = ScopeUtils.deriveTenantDetails(turnContext);
+    static populateInferenceScopeFromTurnContext(details, turnContext, authToken, startTime, endTime) {
+        const agent = ScopeUtils.deriveAgentDetails(turnContext, authToken);
+        const caller = ScopeUtils.deriveCallerDetails(turnContext);
         const conversationId = ScopeUtils.deriveConversationId(turnContext);
-        const sourceMetadata = ScopeUtils.deriveSourceMetadataObject(turnContext);
+        const channel = ScopeUtils.deriveChannelObject(turnContext);
         if (!agent) {
             throw new Error('populateInferenceScopeFromTurnContext: Missing agent details on TurnContext (recipient)');
         }
-        if (!tenant) {
-            throw new Error('populateInferenceScopeFromTurnContext: Missing tenant details on TurnContext (recipient)');
-        }
-        const scope = InferenceScope.start(details, agent, tenant, conversationId, sourceMetadata);
+        const hasChannel = channel.name !== undefined || channel.description !== undefined;
+        const request = {
+            conversationId,
+            ...(hasChannel ? { channel: { name: channel.name, description: channel.description } } : {}),
+        };
+        const spanDetails = (startTime || endTime)
+            ? { startTime, endTime }
+            : undefined;
+        const scope = InferenceScope.start(request, details, agent, caller, spanDetails);
         this.setInputMessageTags(scope, turnContext);
         return scope;
     }
     /**
      * Create an `InvokeAgentScope` using `details` and values derived from the provided `TurnContext`.
-     * Populates `conversationId` and `request.sourceMetadata` (channel name/link) in `details` from the `TurnContext`, overriding any existing values.
-     * Derives `tenantDetails`, `callerAgentDetails` (from caller), and `callerDetails` (from user).
-     * Also sets execution type and input messages from the context if present.
-     * @param details The invoke-agent call details to be augmented and used for the scope.
+     * Builds a separate `Request` with `conversationId` and `channel` from context.
+     * Merges agent identity from context into `details` via `buildInvokeAgentDetailsCore`.
+     * Derives `callerAgentDetails` (from caller) and `userDetails` (human caller).
+     * Also records input messages from the context if present.
+     * @param details The agent details to be augmented with context-derived identity.
      * @param turnContext The current activity context to derive scope parameters from.
+     * @param authToken Auth token for resolving agent identity from token claims.
+     * @param startTime Optional explicit start time (ms epoch, Date, or HrTime).
+     * @param endTime Optional explicit end time (ms epoch, Date, or HrTime).
+     * @param spanKind Optional span kind override. Defaults to `SpanKind.CLIENT`.
      * @returns A started `InvokeAgentScope` enriched with context-derived parameters.
      */
-    static populateInvokeAgentScopeFromTurnContext(details, turnContext) {
-        const tenant = ScopeUtils.deriveTenantDetails(turnContext);
+    static populateInvokeAgentScopeFromTurnContext(details, scopeDetails, turnContext, authToken, startTime, endTime, spanKind) {
         const callerAgent = ScopeUtils.deriveCallerAgent(turnContext);
         const caller = ScopeUtils.deriveCallerDetails(turnContext);
-        const invokeAgentDetails = ScopeUtils.buildInvokeAgentDetails(details, turnContext);
-        if (!tenant) {
-            throw new Error('populateInvokeAgentScopeFromTurnContext: Missing tenant details on TurnContext (recipient)');
-        }
-        const scope = InvokeAgentScope.start(invokeAgentDetails, tenant, callerAgent, caller);
+        const conversationId = ScopeUtils.deriveConversationId(turnContext);
+        const channel = ScopeUtils.deriveChannelObject(turnContext);
+        // Merge agent identity from TurnContext into details.details
+        const agentDetails = ScopeUtils.buildInvokeAgentDetailsCore(details, turnContext, authToken);
+        // Build the request with channel and conversationId from context
+        const hasChannel = channel.name !== undefined || channel.description !== undefined;
+        const request = {
+            conversationId,
+            ...(hasChannel ? { channel: { name: channel.name, description: channel.description } } : {}),
+        };
+        // Build caller info with both human caller and caller agent details
+        const callerDetails = {
+            userDetails: caller,
+            callerAgentDetails: callerAgent,
+        };
+        const spanDetailsObj = (startTime || endTime || spanKind)
+            ? { startTime, endTime, spanKind }
+            : undefined;
+        const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, callerDetails, spanDetailsObj);
         this.setInputMessageTags(scope, turnContext);
         return scope;
     }
     /**
-     * Build InvokeAgentDetails by merging provided details with agent info, conversation id and source metadata from the TurnContext.
-     * @param details Base invoke-agent details to augment
+     * Build agent details by merging provided details with agent info from the TurnContext.
+     * @param details Base agent details to augment
      * @param turnContext Activity context
-     * @returns New InvokeAgentDetails suitable for starting an InvokeAgentScope.
+     * @param authToken Auth token for resolving agent identity from token claims.
+     * @returns Merged AgentDetails with context-derived identity.
      */
-    static buildInvokeAgentDetails(details, turnContext) {
-        const agent = ScopeUtils.deriveAgentDetails(turnContext);
-        const srcMetaFromContext = ScopeUtils.deriveSourceMetadataObject(turnContext);
-        const executionTypePair = getExecutionTypePair(turnContext);
-        const baseRequest = details.request ?? {};
-        const baseSource = baseRequest.sourceMetadata ?? {};
-        const mergedSourceMetadata = {
-            ...baseSource,
-            ...(srcMetaFromContext.name !== undefined ? { name: srcMetaFromContext.name } : {}),
-            ...(srcMetaFromContext.description !== undefined ? { description: srcMetaFromContext.description } : {}),
-        };
-        return {
+    static buildInvokeAgentDetails(details, turnContext, authToken) {
+        return ScopeUtils.buildInvokeAgentDetailsCore(details, turnContext, authToken);
+    }
+    static buildInvokeAgentDetailsCore(details, turnContext, authToken) {
+        const derivedAgentDetails = ScopeUtils.deriveAgentDetails(turnContext, authToken);
+        // Merge derived agent identity into details
+        const mergedAgent = {
             ...details,
-            ...agent,
-            conversationId: ScopeUtils.deriveConversationId(turnContext),
-            request: {
-                ...baseRequest,
-                executionType: executionTypePair.length > 0 ? executionTypePair[0][1] : baseRequest.executionType,
-                sourceMetadata: mergedSourceMetadata
-            }
+            ...(derivedAgentDetails ?? {}),
         };
+        return mergedAgent;
     }
     /**
      * Create an `ExecuteToolScope` using `details` and values derived from the provided `TurnContext`.
-     * Derives `agentDetails`, `tenantDetails`, `conversationId`, and `sourceMetadata` (channel name/link) from context.
+     * Derives `conversationId` and `channel` (name/link) from context.
      * @param details The tool call details (name, type, args, call id, etc.).
      * @param turnContext The current activity context to derive scope parameters from.
+     * @param authToken Auth token for resolving agent identity from token claims.
+     * @param startTime Optional explicit start time (ms epoch, Date, or HrTime). Useful when recording a
+     *        tool call after execution has already completed.
+     * @param endTime Optional explicit end time (ms epoch, Date, or HrTime).
+     * @param spanKind Optional span kind override. Defaults to `SpanKind.INTERNAL`.
      * @returns A started `ExecuteToolScope` enriched with context-derived parameters.
      */
-    static populateExecuteToolScopeFromTurnContext(details, turnContext) {
-        const agent = ScopeUtils.deriveAgentDetails(turnContext);
-        const tenant = ScopeUtils.deriveTenantDetails(turnContext);
+    static populateExecuteToolScopeFromTurnContext(details, turnContext, authToken, startTime, endTime, spanKind) {
+        const agent = ScopeUtils.deriveAgentDetails(turnContext, authToken);
+        const caller = ScopeUtils.deriveCallerDetails(turnContext);
         const conversationId = ScopeUtils.deriveConversationId(turnContext);
-        const sourceMetadata = ScopeUtils.deriveSourceMetadataObject(turnContext);
+        const channel = ScopeUtils.deriveChannelObject(turnContext);
         if (!agent) {
             throw new Error('populateExecuteToolScopeFromTurnContext: Missing agent details on TurnContext (recipient)');
         }
-        if (!tenant) {
-            throw new Error('populateExecuteToolScopeFromTurnContext: Missing tenant details on TurnContext (recipient)');
-        }
-        const scope = ExecuteToolScope.start(details, agent, tenant, conversationId, sourceMetadata);
+        const hasChannel = channel.name !== undefined || channel.description !== undefined;
+        const request = {
+            conversationId,
+            ...(hasChannel ? { channel: { name: channel.name, description: channel.description } } : {}),
+        };
+        const spanDetailsObj = (startTime || endTime || spanKind)
+            ? { startTime, endTime, spanKind }
+            : undefined;
+        const scope = ExecuteToolScope.start(request, details, agent, caller, spanDetailsObj);
         return scope;
     }
 }