@microsoft/agents-a365-observability-hosting 0.1.0-preview.103

package/dist/cjs/utils/ScopeUtils.js

@@ -0,0 +1,198 @@
+"use strict";
+// ------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+// ------------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeUtils = void 0;
+const agents_a365_observability_1 = require("@microsoft/agents-a365-observability");
+const TurnContextUtils_1 = require("./TurnContextUtils");
+/**
+ * Unified utilities to populate scope tags from a TurnContext.
+ * Provides common tag population and scope-specific helpers.
+ */
+class ScopeUtils {
+    static setInputMessageTags(scope, turnContext) {
+        if (turnContext?.activity?.text) {
+            scope.recordInputMessages([turnContext.activity.text]);
+        }
+        return scope;
+    }
+    // ----------------------
+    // 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.
+     * @param turnContext Activity context
+     * @returns Agent details built from recipient properties; otherwise undefined.
+     */
+    static deriveAgentDetails(turnContext) {
+        const recipient = turnContext?.activity?.recipient;
+        if (!recipient)
+            return undefined;
+        return {
+            agentId: recipient.agenticAppId,
+            agentName: recipient.name,
+            agentAUID: recipient.aadObjectId,
+            agentDescription: recipient.role,
+            tenantId: recipient.tenantId
+        };
+    }
+    /**
+     * Derive caller agent details from the activity from.
+     * @param turnContext Activity context
+     * @returns Agent details built from caller (from) properties; otherwise undefined.
+     */
+    static deriveCallerAgent(turnContext) {
+        const from = turnContext?.activity?.from;
+        if (!from)
+            return undefined;
+        return {
+            agentBlueprintId: from.agenticAppBlueprintId,
+            agentName: from.name,
+            agentAUID: from.aadObjectId,
+            agentDescription: from.role,
+            tenantId: from.tenantId,
+            agentId: from.agenticAppId
+        };
+    }
+    /**
+     * Derive caller identity details (id, upn, name, tenant, client ip) from the activity from.
+     * @param turnContext Activity context
+     * @returns Caller 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,
+            tenantId: from.tenantId,
+        };
+    }
+    /**
+     * Derive conversation id from the TurnContext.
+     * @param turnContext Activity context
+     * @returns Conversation id when present; otherwise undefined.
+     */
+    static deriveConversationId(turnContext) {
+        return turnContext?.activity?.conversation?.id;
+    }
+    /**
+     * Derive source metadata (channel name and description/link) from the TurnContext.
+     * @param turnContext Activity context
+     * @returns Object with optional name and description fields.
+     */
+    static deriveSourceMetadataObject(turnContext) {
+        return {
+            name: turnContext?.activity?.channelId,
+            description: turnContext?.activity?.channelIdSubChannel
+        };
+    }
+    /**
+     * Create an `InferenceScope` using `details` and values derived from the provided `TurnContext`.
+     * Derives `agentDetails`, `tenantDetails`, `conversationId`, and `sourceMetadata` (channel name/link) 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.
+     * @returns A started `InferenceScope` enriched with context-derived parameters.
+     */
+    static populateInferenceScopeFromTurnContext(details, turnContext) {
+        const agent = ScopeUtils.deriveAgentDetails(turnContext);
+        const tenant = ScopeUtils.deriveTenantDetails(turnContext);
+        const conversationId = ScopeUtils.deriveConversationId(turnContext);
+        const sourceMetadata = ScopeUtils.deriveSourceMetadataObject(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 = agents_a365_observability_1.InferenceScope.start(details, agent, tenant, conversationId, sourceMetadata);
+        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.
+     * @param turnContext The current activity context to derive scope parameters from.
+     * @returns A started `InvokeAgentScope` enriched with context-derived parameters.
+     */
+    static populateInvokeAgentScopeFromTurnContext(details, turnContext) {
+        const tenant = ScopeUtils.deriveTenantDetails(turnContext);
+        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 = agents_a365_observability_1.InvokeAgentScope.start(invokeAgentDetails, tenant, callerAgent, caller);
+        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
+     * @param turnContext Activity context
+     * @returns New InvokeAgentDetails suitable for starting an InvokeAgentScope.
+     */
+    static buildInvokeAgentDetails(details, turnContext) {
+        const agent = ScopeUtils.deriveAgentDetails(turnContext);
+        const srcMetaFromContext = ScopeUtils.deriveSourceMetadataObject(turnContext);
+        const executionTypePair = (0, TurnContextUtils_1.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 {
+            ...details,
+            ...agent,
+            conversationId: ScopeUtils.deriveConversationId(turnContext),
+            request: {
+                ...baseRequest,
+                executionType: executionTypePair.length > 0 ? executionTypePair[0][1] : baseRequest.executionType,
+                sourceMetadata: mergedSourceMetadata
+            }
+        };
+    }
+    /**
+     * Create an `ExecuteToolScope` using `details` and values derived from the provided `TurnContext`.
+     * Derives `agentDetails`, `tenantDetails`, `conversationId`, and `sourceMetadata` (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.
+     * @returns A started `ExecuteToolScope` enriched with context-derived parameters.
+     */
+    static populateExecuteToolScopeFromTurnContext(details, turnContext) {
+        const agent = ScopeUtils.deriveAgentDetails(turnContext);
+        const tenant = ScopeUtils.deriveTenantDetails(turnContext);
+        const conversationId = ScopeUtils.deriveConversationId(turnContext);
+        const sourceMetadata = ScopeUtils.deriveSourceMetadataObject(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 = agents_a365_observability_1.ExecuteToolScope.start(details, agent, tenant, conversationId, sourceMetadata);
+        return scope;
+    }
+}
+exports.ScopeUtils = ScopeUtils;
+//# sourceMappingURL=ScopeUtils.js.map

package/dist/cjs/utils/ScopeUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeUtils.js","sourceRoot":"","sources":["../../../src/utils/ScopeUtils.ts"],"names":[],"mappings":";AAAA,iFAAiF;AACjF,uCAAuC;AACvC,kCAAkC;AAClC,iFAAiF;;;AAGjF,oFAW8C;AAC9C,yDAE4B;AAE5B;;;GAGG;AACH,MAAa,UAAU;IAGb,MAAM,CAAC,mBAAmB,CAAC,KAAwC,EAAE,WAAwB;QACnG,IAAI,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;YAChC,KAAK,CAAC,mBAAmB,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yBAAyB;IACzB,0BAA0B;IAC1B,yBAAyB;IACzB;;;;OAIG;IACI,MAAM,CAAC,mBAAmB,CAAC,WAAwB;QACxD,MAAM,QAAQ,GAAG,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC;QAC5D,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7C,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,kBAAkB,CAAC,WAAwB;QACvD,MAAM,SAAS,GAAG,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC;QACnD,IAAI,CAAC,SAAS;YAAE,OAAO,SAAS,CAAC;QACjC,OAAO;YACL,OAAO,EAAE,SAAS,CAAC,YAAY;YAC/B,SAAS,EAAE,SAAS,CAAC,IAAI;YACzB,SAAS,EAAE,SAAS,CAAC,WAAW;YAChC,gBAAgB,EAAE,SAAS,CAAC,IAAI;YAChC,QAAQ,EAAE,SAAS,CAAC,QAAQ;SACb,CAAC;IACpB,CAAC;IAGD;;;;OAIG;IACI,MAAM,CAAC,iBAAiB,CAAC,WAAwB;QACtD,MAAM,IAAI,GAAG,WAAW,EAAE,QAAQ,EAAE,IAAI,CAAC;QACzC,IAAI,CAAC,IAAI;YAAE,OAAO,SAAS,CAAC;QAC5B,OAAO;YACL,gBAAgB,EAAE,IAAI,CAAC,qBAAqB;YAC5C,SAAS,EAAE,IAAI,CAAC,IAAI;YACpB,SAAS,EAAE,IAAI,CAAC,WAAW;YAC3B,gBAAgB,EAAE,IAAI,CAAC,IAAI;YAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,OAAO,EAAE,IAAI,CAAC,YAAY;SACX,CAAC;IACpB,CAAC;IAGD;;;;OAIG;IACI,MAAM,CAAC,mBAAmB,CAAC,WAAwB;QACxD,MAAM,IAAI,GAAG,WAAW,EAAE,QAAQ,EAAE,IAAI,CAAC;QACzC,IAAI,CAAC,IAAI;YAAE,OAAO,SAAS,CAAC;QAC5B,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,WAAW;YAC1B,SAAS,EAAE,IAAI,CAAC,aAAa;YAC7B,UAAU,EAAE,IAAI,CAAC,IAAI;YACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACP,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,oBAAoB,CAAC,WAAwB;QACzD,OAAO,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,CAAC;IACjD,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,0BAA0B,CAAC,WAAwB;QAC/D,OAAO;YACL,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS;YACtC,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,mBAAyC;SAC9E,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,qCAAqC,CAC1C,OAAyB,EACzB,WAAwB;QAExB,MAAM,KAAK,GAAG,UAAU,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,UAAU,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;QAC3D,MAAM,cAAc,GAAG,UAAU,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC;QACpE,MAAM,cAAc,GAAG,UAAU,CAAC,0BAA0B,CAAC,WAAW,CAAC,CAAC;QAE1E,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAC;QAC7G,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,0FAA0F,CAAC,CAAC;QAC9G,CAAC;QAED,MAAM,KAAK,GAAG,0CAAc,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,cAAc,CAAC,CAAC;QAC3F,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAC7C,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,uCAAuC,CAC5C,OAA2B,EAC3B,WAAwB;QAExB,MAAM,MAAM,GAAG,UAAU,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,UAAU,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,UAAU,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;QAC3D,MAAM,kBAAkB,GAAG,UAAU,CAAC,uBAAuB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAEpF,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,4FAA4F,CAAC,CAAC;QAChH,CAAC;QAED,MAAM,KAAK,GAAG,4CAAgB,CAAC,KAAK,CAAC,kBAAkB,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;QACtF,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAC7C,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,uBAAuB,CAAC,OAA2B,EAAE,WAAwB;QACzF,MAAM,KAAK,GAAG,UAAU,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC;QACzD,MAAM,kBAAkB,GAAG,UAAU,CAAC,0BAA0B,CAAC,WAAW,CAAC,CAAC;QAC9E,MAAM,iBAAiB,GAAG,IAAA,uCAAoB,EAAC,WAAW,CAAC,CAAC;QAC5D,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QAC1C,MAAM,UAAU,GAAG,WAAW,CAAC,cAAc,IAAI,EAAE,CAAC;QACpD,MAAM,oBAAoB,GAAG;YAC3B,GAAG,UAAU;YACb,GAAG,CAAC,kBAAkB,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,kBAAkB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnF,GAAG,CAAC,kBAAkB,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,kBAAkB,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzG,CAAC;QACF,OAAO;YACL,GAAG,OAAO;YACV,GAAG,KAAK;YACR,cAAc,EAAE,UAAU,CAAC,oBAAoB,CAAC,WAAW,CAAC;YAC5D,OAAO,EAAE;gBACP,GAAG,WAAW;gBACd,aAAa,EAAE,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAmB,CAAC,CAAC,CAAC,WAAW,CAAC,aAAa;gBACpH,cAAc,EAAE,oBAAoB;aACrC;SACF,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,uCAAuC,CAC5C,OAAwB,EACxB,WAAwB;QAExB,MAAM,KAAK,GAAG,UAAU,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,UAAU,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;QAC3D,MAAM,cAAc,GAAG,UAAU,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC;QACpE,MAAM,cAAc,GAAG,UAAU,CAAC,0BAA0B,CAAC,WAAW,CAAC,CAAC;QAC1E,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,2FAA2F,CAAC,CAAC;QAC/G,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,4FAA4F,CAAC,CAAC;QAChH,CAAC;QACD,MAAM,KAAK,GAAG,4CAAgB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,cAAc,CAAC,CAAC;QAC7F,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AA9MD,gCA8MC"}

package/dist/cjs/utils/TurnContextUtils.d.ts

@@ -0,0 +1,38 @@
+import { TurnContext } from '@microsoft/agents-hosting';
+/**
+ * Extracts caller-related OpenTelemetry baggage pairs from the TurnContext.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] pairs for caller identity and tenant
+ */
+export declare function getCallerBaggagePairs(turnContext: TurnContext): Array<[string, string]>;
+/**
+ * Extracts the execution type baggage key-value pair based on caller and recipient agentic status.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] for execution type
+ */
+export declare function getExecutionTypePair(turnContext: TurnContext): Array<[string, string]>;
+/**
+ * Extracts agent/recipient-related OpenTelemetry baggage pairs from the TurnContext.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] pairs for agent identity and description
+ */
+export declare function getTargetAgentBaggagePairs(turnContext: TurnContext): Array<[string, string]>;
+/**
+ * Extracts the tenant ID baggage key-value pair, attempting to retrieve from ChannelData if necessary.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] for tenant ID
+ */
+export declare function getTenantIdPair(turnContext: TurnContext): Array<[string, string]>;
+/**
+ * Extracts source metadata baggage pairs from the TurnContext.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] pairs for channel name and link
+ */
+export declare function getSourceMetadataBaggagePairs(turnContext: TurnContext): Array<[string, string]>;
+/**
+ * Extracts conversation ID and item link baggage key-value pairs from the provided turn context.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] pairs for conversation ID and item link
+ */
+export declare function getConversationIdAndItemLinkPairs(turnContext: TurnContext): Array<[string, string]>;
+//# sourceMappingURL=TurnContextUtils.d.ts.map

package/dist/cjs/utils/TurnContextUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TurnContextUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/TurnContextUtils.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAcxD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAevF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAkBtF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAgB5F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAoBjF;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAS/F;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAAC,WAAW,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAWnG"}

package/dist/cjs/utils/TurnContextUtils.js

@@ -0,0 +1,144 @@
+"use strict";
+// ------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+// ------------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCallerBaggagePairs = getCallerBaggagePairs;
+exports.getExecutionTypePair = getExecutionTypePair;
+exports.getTargetAgentBaggagePairs = getTargetAgentBaggagePairs;
+exports.getTenantIdPair = getTenantIdPair;
+exports.getSourceMetadataBaggagePairs = getSourceMetadataBaggagePairs;
+exports.getConversationIdAndItemLinkPairs = getConversationIdAndItemLinkPairs;
+const agents_a365_observability_1 = require("@microsoft/agents-a365-observability");
+const agents_activity_1 = require("@microsoft/agents-activity");
+/**
+ * TurnContext utility methods.
+ */
+function normalizePairs(pairs) {
+    return pairs
+        .filter(([, v]) => v != null && String(v).trim() !== '')
+        .map(([k, v]) => [k, String(v)]);
+}
+/**
+ * Extracts caller-related OpenTelemetry baggage pairs from the TurnContext.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] pairs for caller identity and tenant
+ */
+function getCallerBaggagePairs(turnContext) {
+    if (!turnContext || !turnContext.activity?.from) {
+        return [];
+    }
+    const from = turnContext.activity.from;
+    const upn = from.agenticUserId;
+    const pairs = [
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_CALLER_ID_KEY, from.aadObjectId],
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_CALLER_NAME_KEY, from.name],
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_CALLER_UPN_KEY, upn],
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_CALLER_TENANT_ID_KEY, from.tenantId],
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_AGENT_BLUEPRINT_ID_KEY, from.agenticAppBlueprintId]
+    ];
+    return normalizePairs(pairs);
+}
+/**
+ * Extracts the execution type baggage key-value pair based on caller and recipient agentic status.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] for execution type
+ */
+function getExecutionTypePair(turnContext) {
+    if (!turnContext || !turnContext.activity?.from || !turnContext.activity?.recipient) {
+        return [];
+    }
+    const from = turnContext.activity.from;
+    let executionType = agents_a365_observability_1.ExecutionType.HumanToAgent;
+    if (from.role) {
+        switch (from.role) {
+            case agents_activity_1.RoleTypes.AgenticUser:
+                executionType = agents_a365_observability_1.ExecutionType.Agent2Agent;
+                break;
+            case agents_activity_1.RoleTypes.User:
+                executionType = agents_a365_observability_1.ExecutionType.HumanToAgent;
+                break;
+        }
+    }
+    return [[agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_EXECUTION_TYPE_KEY, executionType]];
+}
+/**
+ * Extracts agent/recipient-related OpenTelemetry baggage pairs from the TurnContext.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] pairs for agent identity and description
+ */
+function getTargetAgentBaggagePairs(turnContext) {
+    if (!turnContext || !turnContext.activity?.recipient) {
+        return [];
+    }
+    const recipient = turnContext.activity.recipient;
+    const agentId = recipient.agenticAppId;
+    const agentName = recipient.name;
+    const aadObjectId = recipient.aadObjectId;
+    const agentDescription = recipient.role;
+    const pairs = [
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_AGENT_ID_KEY, agentId],
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_AGENT_NAME_KEY, agentName],
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_AGENT_DESCRIPTION_KEY, agentDescription],
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_AGENT_AUID_KEY, aadObjectId],
+    ];
+    return normalizePairs(pairs);
+}
+/**
+ * Extracts the tenant ID baggage key-value pair, attempting to retrieve from ChannelData if necessary.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] for tenant ID
+ */
+function getTenantIdPair(turnContext) {
+    let tenantId = turnContext.activity?.recipient?.tenantId;
+    // If not found, try to extract from channelData. Accepts both object and JSON string.
+    if (!tenantId && turnContext.activity?.channelData) {
+        try {
+            let channelData = turnContext.activity.channelData;
+            if (typeof channelData === 'string') {
+                channelData = JSON.parse(channelData);
+            }
+            if (typeof channelData === 'object' && channelData !== null) {
+                tenantId = channelData?.tenant?.id;
+            }
+        }
+        catch (_err) {
+            // ignore JSON parse errors
+        }
+    }
+    return tenantId ? [[agents_a365_observability_1.OpenTelemetryConstants.TENANT_ID_KEY, tenantId]] : [];
+}
+/**
+ * Extracts source metadata baggage pairs from the TurnContext.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] pairs for channel name and link
+ */
+function getSourceMetadataBaggagePairs(turnContext) {
+    if (!turnContext) {
+        return [];
+    }
+    const pairs = [
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_EXECUTION_SOURCE_NAME_KEY, turnContext.activity?.channelId],
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY, turnContext.activity?.channelIdSubChannel]
+    ];
+    return normalizePairs(pairs);
+}
+/**
+ * Extracts conversation ID and item link baggage key-value pairs from the provided turn context.
+ * @param turnContext The current TurnContext (activity context)
+ * @returns Array of [key, value] pairs for conversation ID and item link
+ */
+function getConversationIdAndItemLinkPairs(turnContext) {
+    if (!turnContext) {
+        return [];
+    }
+    const conversationId = turnContext.activity?.conversation?.id;
+    const itemLink = turnContext.activity?.serviceUrl;
+    const pairs = [
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_CONVERSATION_ID_KEY, conversationId],
+        [agents_a365_observability_1.OpenTelemetryConstants.GEN_AI_CONVERSATION_ITEM_LINK_KEY, itemLink]
+    ];
+    return normalizePairs(pairs);
+}
+//# sourceMappingURL=TurnContextUtils.js.map

package/dist/cjs/utils/TurnContextUtils.js.map

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

package/dist/esm/caching/AgenticTokenCache.d.ts

@@ -0,0 +1,55 @@
+import { TurnContext, Authorization } from '@microsoft/agents-hosting';
+import { ObservabilityConfiguration } from '@microsoft/agents-a365-observability';
+import { IConfigurationProvider } from '@microsoft/agents-a365-runtime';
+/**
+ * Cache for agentic authentication tokens used by observability services.
+ *
+ * For custom configuration, create a new instance with your own configuration provider:
+ * ```typescript
+ * const customCache = new AgenticTokenCache(myConfigProvider);
+ * ```
+ *
+ * For default configuration using environment variables, use the exported
+ * `AgenticTokenCacheInstance` singleton.
+ */
+export declare class AgenticTokenCache {
+    private readonly _map;
+    private readonly _defaultRefreshSkewMs;
+    private readonly _defaultMaxTokenAgeMs;
+    private readonly _keyLocks;
+    private readonly _configProvider;
+    /**
+     * Construct an AgenticTokenCache.
+     * @param configProvider Optional configuration provider. Defaults to defaultObservabilityConfigurationProvider if not specified.
+     */
+    constructor(configProvider?: IConfigurationProvider<ObservabilityConfiguration>);
+    static makeKey(agentId: string, tenantId: string): string;
+    getObservabilityToken(agentId: string, tenantId: string): string | null;
+    RefreshObservabilityToken(agentId: string, tenantId: string, turnContext: TurnContext, authorization: Authorization, scopes: string[]): Promise<void>;
+    invalidateToken(agentId: string, tenantId: string): void;
+    invalidateAll(): void;
+    private decodeExp;
+    private isExpired;
+    private isRetriableError;
+    private sleep;
+    private withKeyLock;
+}
+/**
+ * Default singleton instance of AgenticTokenCache using the default configuration provider.
+ *
+ * This instance uses `defaultObservabilityConfigurationProvider` which reads from
+ * environment variables. It is suitable for:
+ * - Single-tenant deployments
+ * - Multi-tenant deployments using dynamic override functions in the configuration
+ *
+ * **For custom configuration:** Create a new `AgenticTokenCache` instance with your
+ * own `IConfigurationProvider<ObservabilityConfiguration>`:
+ * ```typescript
+ * import { AgenticTokenCache } from '@microsoft/agents-a365-observability-hosting';
+ *
+ * const customCache = new AgenticTokenCache(myCustomConfigProvider);
+ * ```
+ */
+export declare const AgenticTokenCacheInstance: AgenticTokenCache;
+export default AgenticTokenCacheInstance;
+//# sourceMappingURL=AgenticTokenCache.d.ts.map

package/dist/esm/caching/AgenticTokenCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgenticTokenCache.d.ts","sourceRoot":"","sources":["../../../src/caching/AgenticTokenCache.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAuB,0BAA0B,EAA6C,MAAM,sCAAsC,CAAC;AAClJ,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AASxE;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAU;IAChD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAa;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IACjE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqD;IAErF;;;OAGG;gBACS,cAAc,CAAC,EAAE,sBAAsB,CAAC,0BAA0B,CAAC;WAIjE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIzD,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAkBjE,yBAAyB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,IAAI,CAAC;IAiET,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQxD,aAAa,IAAI,IAAI;IAI5B,OAAO,CAAC,SAAS;IAkBjB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,KAAK;YAIC,WAAW;CAiB5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,yBAAyB,mBAA0B,CAAC;AACjE,eAAe,yBAAyB,CAAC"}