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

package/dist/esm/utils/ScopeUtils.js

@@ -0,0 +1,194 @@
+// ------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+// ------------------------------------------------------------------------------
+import { InvokeAgentScope, InferenceScope, ExecuteToolScope } from '@microsoft/agents-a365-observability';
+import { getExecutionTypePair, } from './TurnContextUtils';
+/**
+ * Unified utilities to populate scope tags from a TurnContext.
+ * Provides common tag population and scope-specific helpers.
+ */
+export 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 = 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 = 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 = 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 = ExecuteToolScope.start(details, agent, tenant, conversationId, sourceMetadata);
+        return scope;
+    }
+}
+//# sourceMappingURL=ScopeUtils.js.map

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

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

package/dist/esm/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/esm/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/esm/utils/TurnContextUtils.js

@@ -0,0 +1,136 @@
+// ------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+// ------------------------------------------------------------------------------
+import { ExecutionType, OpenTelemetryConstants } from '@microsoft/agents-a365-observability';
+import { RoleTypes } from '@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
+ */
+export function getCallerBaggagePairs(turnContext) {
+    if (!turnContext || !turnContext.activity?.from) {
+        return [];
+    }
+    const from = turnContext.activity.from;
+    const upn = from.agenticUserId;
+    const pairs = [
+        [OpenTelemetryConstants.GEN_AI_CALLER_ID_KEY, from.aadObjectId],
+        [OpenTelemetryConstants.GEN_AI_CALLER_NAME_KEY, from.name],
+        [OpenTelemetryConstants.GEN_AI_CALLER_UPN_KEY, upn],
+        [OpenTelemetryConstants.GEN_AI_CALLER_TENANT_ID_KEY, from.tenantId],
+        [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
+ */
+export function getExecutionTypePair(turnContext) {
+    if (!turnContext || !turnContext.activity?.from || !turnContext.activity?.recipient) {
+        return [];
+    }
+    const from = turnContext.activity.from;
+    let executionType = ExecutionType.HumanToAgent;
+    if (from.role) {
+        switch (from.role) {
+            case RoleTypes.AgenticUser:
+                executionType = ExecutionType.Agent2Agent;
+                break;
+            case RoleTypes.User:
+                executionType = ExecutionType.HumanToAgent;
+                break;
+        }
+    }
+    return [[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
+ */
+export 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 = [
+        [OpenTelemetryConstants.GEN_AI_AGENT_ID_KEY, agentId],
+        [OpenTelemetryConstants.GEN_AI_AGENT_NAME_KEY, agentName],
+        [OpenTelemetryConstants.GEN_AI_AGENT_DESCRIPTION_KEY, agentDescription],
+        [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
+ */
+export 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 ? [[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
+ */
+export function getSourceMetadataBaggagePairs(turnContext) {
+    if (!turnContext) {
+        return [];
+    }
+    const pairs = [
+        [OpenTelemetryConstants.GEN_AI_EXECUTION_SOURCE_NAME_KEY, turnContext.activity?.channelId],
+        [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
+ */
+export function getConversationIdAndItemLinkPairs(turnContext) {
+    if (!turnContext) {
+        return [];
+    }
+    const conversationId = turnContext.activity?.conversation?.id;
+    const itemLink = turnContext.activity?.serviceUrl;
+    const pairs = [
+        [OpenTelemetryConstants.GEN_AI_CONVERSATION_ID_KEY, conversationId],
+        [OpenTelemetryConstants.GEN_AI_CONVERSATION_ITEM_LINK_KEY, itemLink]
+    ];
+    return normalizePairs(pairs);
+}
+//# sourceMappingURL=TurnContextUtils.js.map

package/dist/esm/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/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@microsoft/agents-a365-observability-hosting",
+  "version": "0.1.0-preview.103",
+  "description": "Hosting & Observability utilities for Agent365 (Node.js): token caching, baggage builder, hosting registration.",
+  "keywords": [
+    "agent365",
+    "observability",
+    "telemetry",
+    "token",
+    "cache"
+  ],
+  "homepage": "https://github.com/microsoft/Agent365-nodejs",
+  "bugs": {
+    "url": "https://github.com/microsoft/Agent365-nodejs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/Agent365-nodejs.git",
+    "directory": "packages/agents-a365-observability-hosting"
+  },
+  "license": "MIT",
+  "author": "Microsoft",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@microsoft/agents-a365-observability": "0.1.0-preview.103",
+    "@microsoft/agents-a365-runtime": "0.1.0-preview.103",
+    "@microsoft/agents-hosting": "^1.1.0-alpha.85"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.17.0",
+    "@typescript-eslint/eslint-plugin": "^8.47.0",
+    "@typescript-eslint/parser": "^8.47.0",
+    "eslint": "^9.39.1",
+    "jest": "^30.2.0",
+    "rimraf": "^6.0.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.47.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm",
+    "build:cjs": "npx tsc --project tsconfig.cjs.json",
+    "build:esm": "npx tsc --project tsconfig.esm.json",
+    "build:watch": "npx tsc --watch",
+    "clean": "npx rimraf dist",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "pack": "node ../../copyFiles.js . && pnpm pack --pack-destination=../"
+  }
+}