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

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cjs/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/cjs/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"}

package/dist/cjs/caching/AgenticTokenCache.js

@@ -0,0 +1,214 @@
+"use strict";
+// ------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+// ------------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgenticTokenCacheInstance = exports.AgenticTokenCache = void 0;
+const agents_a365_observability_1 = require("@microsoft/agents-a365-observability");
+/**
+ * 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.
+ */
+class AgenticTokenCache {
+    /**
+     * Construct an AgenticTokenCache.
+     * @param configProvider Optional configuration provider. Defaults to defaultObservabilityConfigurationProvider if not specified.
+     */
+    constructor(configProvider) {
+        this._map = new Map();
+        this._defaultRefreshSkewMs = 60000;
+        this._defaultMaxTokenAgeMs = 3600000;
+        this._keyLocks = new Map();
+        this._configProvider = configProvider ?? agents_a365_observability_1.defaultObservabilityConfigurationProvider;
+    }
+    static makeKey(agentId, tenantId) {
+        return `${agentId}:${tenantId}`;
+    }
+    getObservabilityToken(agentId, tenantId) {
+        const key = AgenticTokenCache.makeKey(agentId, tenantId);
+        const entry = this._map.get(key);
+        if (!entry) {
+            agents_a365_observability_1.logger.error(`[AgenticTokenCache] No cache entry for ${key}`);
+            return null;
+        }
+        if (!entry.token) {
+            agents_a365_observability_1.logger.error(`[AgenticTokenCache] No token cached for ${key}`);
+            return null;
+        }
+        if (this.isExpired(entry)) {
+            agents_a365_observability_1.logger.error(`[AgenticTokenCache] Token expired for ${key}`);
+            return null;
+        }
+        return entry.token;
+    }
+    async RefreshObservabilityToken(agentId, tenantId, turnContext, authorization, scopes) {
+        const key = AgenticTokenCache.makeKey(agentId, tenantId);
+        if (!authorization) {
+            throw new Error('[AgenticTokenCache] Authorization not set');
+        }
+        if (!turnContext) {
+            throw new Error('[AgenticTokenCache] TurnContext not set');
+        }
+        return this.withKeyLock(key, async () => {
+            let entry = this._map.get(key);
+            if (!entry) {
+                const effectiveScopes = (scopes && scopes.length > 0) ? scopes : [...this._configProvider.getConfiguration().observabilityAuthenticationScopes];
+                if (!Array.isArray(effectiveScopes) || effectiveScopes.length === 0) {
+                    agents_a365_observability_1.logger.error('[AgenticTokenCache] No valid scopes');
+                    return;
+                }
+                entry = { scopes: effectiveScopes };
+                this._map.set(key, entry);
+            }
+            if (!Array.isArray(entry.scopes) || entry.scopes.length === 0) {
+                agents_a365_observability_1.logger.error('[AgenticTokenCache] Entry has invalid scopes');
+                return;
+            }
+            if (entry.token && !this.isExpired(entry)) {
+                return;
+            }
+            const maxRetries = 2;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                agents_a365_observability_1.logger.info(`[AgenticTokenCache] Exchanging token attempt ${attempt + 1}/${maxRetries + 1}`);
+                try {
+                    const tokenResponse = await authorization.exchangeToken(turnContext, 'agentic', { scopes: entry.scopes });
+                    if (!tokenResponse?.token) {
+                        agents_a365_observability_1.logger.error('[AgenticTokenCache] Undefined token returned');
+                        entry.token = undefined;
+                        entry.expiresOn = undefined;
+                        break;
+                    }
+                    entry.token = tokenResponse.token;
+                    entry.acquiredOn = Date.now();
+                    const oboExp = this.decodeExp(entry.token);
+                    if (oboExp) {
+                        entry.expiresOn = oboExp * 1000;
+                    }
+                    else {
+                        agents_a365_observability_1.logger.warn('[AgenticTokenCache] No exp claim, fallback TTL');
+                    }
+                    agents_a365_observability_1.logger.info('[AgenticTokenCache] Token cached');
+                    return;
+                }
+                catch (e) {
+                    const retriable = this.isRetriableError(e);
+                    if (retriable && attempt < maxRetries) {
+                        agents_a365_observability_1.logger.warn(`[AgenticTokenCache] Retriable failure attempt ${attempt + 1}`, (0, agents_a365_observability_1.formatError)(e));
+                        await this.sleep(200 * (attempt + 1));
+                        continue;
+                    }
+                    agents_a365_observability_1.logger.error('[AgenticTokenCache] Non-retriable failure', (0, agents_a365_observability_1.formatError)(e));
+                    entry.token = undefined;
+                    entry.expiresOn = undefined;
+                    break;
+                }
+            }
+        });
+    }
+    invalidateToken(agentId, tenantId) {
+        const entry = this._map.get(AgenticTokenCache.makeKey(agentId, tenantId));
+        if (entry) {
+            entry.token = undefined;
+            entry.expiresOn = undefined;
+        }
+    }
+    invalidateAll() {
+        this._map.clear();
+    }
+    decodeExp(jwt) {
+        try {
+            if (!jwt) {
+                return undefined;
+            }
+            const parts = jwt.split('.');
+            if (parts.length < 2) {
+                return undefined;
+            }
+            const payloadSegment = parts[1];
+            const padded = payloadSegment + '='.repeat((4 - (payloadSegment.length % 4)) % 4);
+            const json = JSON.parse(Buffer.from(padded, 'base64').toString('utf8'));
+            return typeof json.exp === 'number' ? json.exp : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    isExpired(entry) {
+        const now = Date.now();
+        if (entry.expiresOn) {
+            return now >= (entry.expiresOn - this._defaultRefreshSkewMs);
+        }
+        if (entry.acquiredOn) {
+            return now >= (entry.acquiredOn + this._defaultMaxTokenAgeMs);
+        }
+        return true;
+    }
+    isRetriableError(err) {
+        const e = err;
+        if (!e) {
+            return false;
+        }
+        const msg = (e.message || '').toLowerCase();
+        if (msg.includes('timeout') || msg.includes('econnreset') || msg.includes('network')) {
+            return true;
+        }
+        if (typeof e.status === 'number') {
+            if (e.status === 408 || e.status === 429) {
+                return true;
+            }
+            if (e.status >= 500 && e.status < 600) {
+                return true;
+            }
+        }
+        return false;
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    async withKeyLock(key, fn) {
+        const previous = this._keyLocks.get(key);
+        if (previous) {
+            try {
+                await previous;
+            }
+            catch (err) {
+                agents_a365_observability_1.logger.warn(`[AgenticTokenCache] previous promise for ${key} rejected:`, (0, agents_a365_observability_1.formatError)(err));
+            }
+        }
+        const currentPromise = fn().finally(() => {
+            if (this._keyLocks.get(key) === currentPromise) {
+                this._keyLocks.delete(key);
+            }
+        });
+        this._keyLocks.set(key, currentPromise);
+        return currentPromise;
+    }
+}
+exports.AgenticTokenCache = AgenticTokenCache;
+/**
+ * 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);
+ * ```
+ */
+exports.AgenticTokenCacheInstance = new AgenticTokenCache();
+exports.default = exports.AgenticTokenCacheInstance;
+//# sourceMappingURL=AgenticTokenCache.js.map

package/dist/cjs/caching/AgenticTokenCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgenticTokenCache.js","sourceRoot":"","sources":["../../../src/caching/AgenticTokenCache.ts"],"names":[],"mappings":";AAAA,iFAAiF;AACjF,uCAAuC;AACvC,kCAAkC;AAClC,iFAAiF;;;AAGjF,oFAAkJ;AAUlJ;;;;;;;;;;GAUG;AACH,MAAa,iBAAiB;IAO1B;;;OAGG;IACH,YAAY,cAAmE;QAV9D,SAAI,GAAG,IAAI,GAAG,EAAsB,CAAC;QACrC,0BAAqB,GAAG,KAAM,CAAC;QAC/B,0BAAqB,GAAG,OAAS,CAAC;QAClC,cAAS,GAAG,IAAI,GAAG,EAA4B,CAAC;QAQ7D,IAAI,CAAC,eAAe,GAAG,cAAc,IAAI,qEAAyC,CAAC;IACvF,CAAC;IAEM,MAAM,CAAC,OAAO,CAAC,OAAe,EAAE,QAAgB;QACnD,OAAO,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAC;IACpC,CAAC;IAEM,qBAAqB,CAAC,OAAe,EAAE,QAAgB;QAC1D,MAAM,GAAG,GAAG,iBAAiB,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,kCAAM,CAAC,KAAK,CAAC,0CAA0C,GAAG,EAAE,CAAC,CAAC;YAC9D,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACf,kCAAM,CAAC,KAAK,CAAC,2CAA2C,GAAG,EAAE,CAAC,CAAC;YAC/D,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,kCAAM,CAAC,KAAK,CAAC,yCAAyC,GAAG,EAAE,CAAC,CAAC;YAC7D,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACvB,CAAC;IAEM,KAAK,CAAC,yBAAyB,CAClC,OAAe,EACf,QAAgB,EAChB,WAAwB,EACxB,aAA4B,EAC5B,MAAgB;QAEhB,MAAM,GAAG,GAAG,iBAAiB,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzD,IAAI,CAAC,aAAa,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,CAAC,WAAW,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAO,GAAG,EAAE,KAAK,IAAI,EAAE;YAC1C,IAAI,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACT,MAAM,eAAe,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC,gBAAgB,EAAE,CAAC,iCAAiC,CAAC,CAAC;gBAChJ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAClE,kCAAM,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;oBACpD,OAAO;gBACX,CAAC;gBACD,KAAK,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;gBACpC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC9B,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5D,kCAAM,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;gBAC7D,OAAO;YACX,CAAC;YAED,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxC,OAAO;YACX,CAAC;YAED,MAAM,UAAU,GAAG,CAAC,CAAC;YACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;gBACrD,kCAAM,CAAC,IAAI,CAAC,gDAAgD,OAAO,GAAG,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC7F,IAAI,CAAC;oBACD,MAAM,aAAa,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;oBAC1G,IAAI,CAAC,aAAa,EAAE,KAAK,EAAE,CAAC;wBACxB,kCAAM,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;wBAC7D,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;wBACxB,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;wBAC5B,MAAM;oBACV,CAAC;oBACD,KAAK,CAAC,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC;oBAClC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;oBAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;oBAC3C,IAAI,MAAM,EAAE,CAAC;wBACT,KAAK,CAAC,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;oBACpC,CAAC;yBAAM,CAAC;wBACJ,kCAAM,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;oBAClE,CAAC;oBACD,kCAAM,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;oBAChD,OAAO;gBACX,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACT,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;oBAC3C,IAAI,SAAS,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;wBACpC,kCAAM,CAAC,IAAI,CAAC,iDAAiD,OAAO,GAAG,CAAC,EAAE,EAAE,IAAA,uCAAW,EAAC,CAAC,CAAC,CAAC,CAAC;wBAC5F,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;wBACtC,SAAS;oBACb,CAAC;oBACD,kCAAM,CAAC,KAAK,CAAC,2CAA2C,EAAE,IAAA,uCAAW,EAAC,CAAC,CAAC,CAAC,CAAC;oBAC1E,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;oBACxB,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;oBAC5B,MAAM;gBACV,CAAC;YACL,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;IAEM,eAAe,CAAC,OAAe,EAAE,QAAgB;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC1E,IAAI,KAAK,EAAE,CAAC;YACR,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;YACxB,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;QAChC,CAAC;IACL,CAAC;IAEM,aAAa;QAChB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAEO,SAAS,CAAC,GAAW;QACzB,IAAI,CAAC;YACD,IAAI,CAAC,GAAG,EAAE,CAAC;gBACP,OAAO,SAAS,CAAC;YACrB,CAAC;YACD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnB,OAAO,SAAS,CAAC;YACrB,CAAC;YACD,MAAM,cAAc,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YAChC,MAAM,MAAM,GAAG,cAAc,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAClF,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAsB,CAAC;YAC7F,OAAO,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACL,OAAO,SAAS,CAAC;QACrB,CAAC;IACL,CAAC;IAEO,SAAS,CAAC,KAAiB;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YAClB,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,qBAAqB,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACnB,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,qBAAqB,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAEO,gBAAgB,CAAC,GAAY;QACjC,MAAM,CAAC,GAAG,GAAuE,CAAC;QAClF,IAAI,CAAC,CAAC,EAAE,CAAC;YACL,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC5C,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACnF,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBACvC,OAAO,IAAI,CAAC;YAChB,CAAC;YACD,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;gBACpC,OAAO,IAAI,CAAC;YAChB,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAEO,KAAK,CAAC,EAAU;QACpB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;IAEO,KAAK,CAAC,WAAW,CAAI,GAAW,EAAE,EAAoB;QAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,QAAQ,EAAE,CAAC;YACX,IAAI,CAAC;gBACD,MAAM,QAAQ,CAAC;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,kCAAM,CAAC,IAAI,CAAC,4CAA4C,GAAG,YAAY,EAAE,IAAA,uCAAW,EAAC,GAAG,CAAC,CAAC,CAAC;YAC/F,CAAC;QACL,CAAC;QACD,MAAM,cAAc,GAAe,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACjD,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,cAAc,EAAE,CAAC;gBAC7C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC/B,CAAC;QACL,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QACxC,OAAO,cAAc,CAAC;IAC1B,CAAC;CACJ;AA9LD,8CA8LC;AAED;;;;;;;;;;;;;;;GAeG;AACU,QAAA,yBAAyB,GAAG,IAAI,iBAAiB,EAAE,CAAC;AACjE,kBAAe,iCAAyB,CAAC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,5 @@
+export * from './utils/BaggageBuilderUtils';
+export * from './utils/ScopeUtils';
+export * from './utils/TurnContextUtils';
+export { AgenticTokenCache, AgenticTokenCacheInstance } from './caching/AgenticTokenCache';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,28 @@
+"use strict";
+// ------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+// ------------------------------------------------------------------------------
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgenticTokenCacheInstance = exports.AgenticTokenCache = void 0;
+__exportStar(require("./utils/BaggageBuilderUtils"), exports);
+__exportStar(require("./utils/ScopeUtils"), exports);
+__exportStar(require("./utils/TurnContextUtils"), exports);
+var AgenticTokenCache_1 = require("./caching/AgenticTokenCache");
+Object.defineProperty(exports, "AgenticTokenCache", { enumerable: true, get: function () { return AgenticTokenCache_1.AgenticTokenCache; } });
+Object.defineProperty(exports, "AgenticTokenCacheInstance", { enumerable: true, get: function () { return AgenticTokenCache_1.AgenticTokenCacheInstance; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA,iFAAiF;AACjF,uCAAuC;AACvC,kCAAkC;AAClC,iFAAiF;;;;;;;;;;;;;;;;;AAEjF,8DAA4C;AAC5C,qDAAmC;AACnC,2DAAyC;AACzC,iEAA2F;AAAlF,sHAAA,iBAAiB,OAAA;AAAE,8HAAA,yBAAyB,OAAA"}

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

@@ -0,0 +1,57 @@
+import { TurnContext } from '@microsoft/agents-hosting';
+import { BaggageBuilder } from '@microsoft/agents-a365-observability';
+/**
+ * Utilities to populate BaggageBuilder from a TurnContext.
+ */
+export declare class BaggageBuilderUtils {
+    /**
+     * Populate all supported baggage pairs from the provided TurnContext.
+     * @param builder The BaggageBuilder instance to populate.
+     * @param turnContext The TurnContext containing activity information.
+     * @returns The updated BaggageBuilder instance.
+     */
+    static fromTurnContext(builder: BaggageBuilder, turnContext: TurnContext): BaggageBuilder;
+    /**
+     * Sets the caller-related baggage values from the TurnContext.
+     * @param builder The BaggageBuilder instance.
+     * @param turnContext The TurnContext containing activity information.
+     * @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.
+     * @param turnContext The TurnContext containing activity information.
+     * @returns The updated BaggageBuilder instance.
+     */
+    static setTargetAgentBaggage(builder: BaggageBuilder, turnContext: TurnContext): BaggageBuilder;
+    /**
+     * Sets the tenant ID baggage value, extracting from ChannelData if necessary.
+     * @param builder The BaggageBuilder instance.
+     * @param turnContext The TurnContext containing activity information.
+     * @returns The updated BaggageBuilder instance.
+     */
+    static setTenantIdBaggage(builder: BaggageBuilder, turnContext: TurnContext): BaggageBuilder;
+    /**
+     * Sets the source metadata 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;
+    /**
+     * Sets the conversation ID and item link baggage values from the TurnContext.
+     * @param builder The BaggageBuilder instance.
+     * @param turnContext The TurnContext containing activity information.
+     * @returns The updated BaggageBuilder instance.
+     */
+    static setConversationIdBaggage(builder: BaggageBuilder, turnContext: TurnContext): BaggageBuilder;
+}
+//# sourceMappingURL=BaggageBuilderUtils.d.ts.map

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

@@ -0,0 +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"}

package/dist/cjs/utils/BaggageBuilderUtils.js

@@ -0,0 +1,93 @@
+"use strict";
+// ------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+// ------------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaggageBuilderUtils = void 0;
+const TurnContextUtils_1 = require("./TurnContextUtils");
+/**
+ * Utilities to populate BaggageBuilder from a TurnContext.
+ */
+class BaggageBuilderUtils {
+    /**
+     * Populate all supported baggage pairs from the provided TurnContext.
+     * @param builder The BaggageBuilder instance to populate.
+     * @param turnContext The TurnContext containing activity information.
+     * @returns The updated BaggageBuilder instance.
+     */
+    static fromTurnContext(builder, turnContext) {
+        if (!turnContext) {
+            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.setConversationIdBaggage(builder, turnContext);
+        return builder;
+    }
+    /**
+     * Sets the caller-related baggage values from the TurnContext.
+     * @param builder The BaggageBuilder instance.
+     * @param turnContext The TurnContext containing activity information.
+     * @returns The updated BaggageBuilder instance.
+     */
+    static setCallerBaggage(builder, turnContext) {
+        builder.setPairs((0, TurnContextUtils_1.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((0, TurnContextUtils_1.getExecutionTypePair)(turnContext));
+        return builder;
+    }
+    /**
+     * Sets the target agent-related baggage values from the TurnContext.
+     * @param builder The BaggageBuilder instance.
+     * @param turnContext The TurnContext containing activity information.
+     * @returns The updated BaggageBuilder instance.
+     */
+    static setTargetAgentBaggage(builder, turnContext) {
+        builder.setPairs((0, TurnContextUtils_1.getTargetAgentBaggagePairs)(turnContext));
+        return builder;
+    }
+    /**
+     * Sets the tenant ID baggage value, extracting from ChannelData if necessary.
+     * @param builder The BaggageBuilder instance.
+     * @param turnContext The TurnContext containing activity information.
+     * @returns The updated BaggageBuilder instance.
+     */
+    static setTenantIdBaggage(builder, turnContext) {
+        builder.setPairs((0, TurnContextUtils_1.getTenantIdPair)(turnContext));
+        return builder;
+    }
+    /**
+     * Sets the source metadata 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((0, TurnContextUtils_1.getSourceMetadataBaggagePairs)(turnContext));
+        return builder;
+    }
+    /**
+     * Sets the conversation ID and item link baggage values from the TurnContext.
+     * @param builder The BaggageBuilder instance.
+     * @param turnContext The TurnContext containing activity information.
+     * @returns The updated BaggageBuilder instance.
+     */
+    static setConversationIdBaggage(builder, turnContext) {
+        builder.setPairs((0, TurnContextUtils_1.getConversationIdAndItemLinkPairs)(turnContext));
+        return builder;
+    }
+}
+exports.BaggageBuilderUtils = BaggageBuilderUtils;
+//# sourceMappingURL=BaggageBuilderUtils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BaggageBuilderUtils.js","sourceRoot":"","sources":["../../../src/utils/BaggageBuilderUtils.ts"],"names":[],"mappings":";AAAA,iFAAiF;AACjF,uCAAuC;AACvC,kCAAkC;AAClC,iFAAiF;;;AAGjF,yDAO4B;AAK5B;;GAEG;AACH,MAAa,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,IAAA,wCAAqB,EAAC,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,IAAA,uCAAoB,EAAC,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,IAAA,6CAA0B,EAAC,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,IAAA,kCAAe,EAAC,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,IAAA,gDAA6B,EAAC,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,IAAA,oDAAiC,EAAC,WAAW,CAAC,CAAC,CAAC;QACjE,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AA1FD,kDA0FC"}

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

@@ -0,0 +1,83 @@
+import { TurnContext } from '@microsoft/agents-hosting';
+import { InvokeAgentScope, InferenceScope, ExecuteToolScope, AgentDetails, TenantDetails, CallerDetails, InferenceDetails, InvokeAgentDetails, ToolCallDetails } 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.
+     * @param turnContext Activity context
+     * @returns Agent details built from recipient properties; otherwise undefined.
+     */
+    static deriveAgentDetails(turnContext: TurnContext): AgentDetails | undefined;
+    /**
+     * 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: TurnContext): AgentDetails | undefined;
+    /**
+     * 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: TurnContext): CallerDetails | undefined;
+    /**
+     * Derive conversation id from the TurnContext.
+     * @param turnContext Activity context
+     * @returns Conversation id when present; otherwise undefined.
+     */
+    static deriveConversationId(turnContext: TurnContext): string | undefined;
+    /**
+     * 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: 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.
+     * 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: InferenceDetails, turnContext: TurnContext): 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.
+     * @param turnContext The current activity context to derive scope parameters from.
+     * @returns A started `InvokeAgentScope` enriched with context-derived parameters.
+     */
+    static populateInvokeAgentScopeFromTurnContext(details: InvokeAgentDetails, turnContext: TurnContext): 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
+     * @param turnContext Activity context
+     * @returns New InvokeAgentDetails suitable for starting an InvokeAgentScope.
+     */
+    static buildInvokeAgentDetails(details: InvokeAgentDetails, turnContext: TurnContext): InvokeAgentDetails;
+    /**
+     * 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: ToolCallDetails, turnContext: TurnContext): ExecuteToolScope;
+}
+//# sourceMappingURL=ScopeUtils.d.ts.map

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

@@ -0,0 +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"}