@microsoft/agents-hosting 1.6.0-beta.9.gce9d8facd2 → 1.7.0-beta.1.g8bcd4f11a7

package/src/getProductInfo.ts

@@ -1,5 +1,15 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
 import { version } from '../package.json'
 import os from 'os'
+import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from './errorHelper'
+import { HeaderPropagationCollection } from './headerPropagation'
+
+const AGENT_NAME_PATTERN = /^[A-Za-z0-9 _-]+$/
+const AGENT_REGISTRAR = 'A365'
+const DEFAULT_AGENT_NAME = 'Agents-SDK-JS'
 
 /**
  * Generates a string containing information about the SDK version and runtime environment.
@@ -7,4 +17,72 @@ import os from 'os'
  *
  * @returns A formatted string containing the SDK version, Node.js version, and OS details
  */
-export const getProductInfo = () : string => `agents-sdk-js/${version} nodejs/${process.version} ${os.platform()}-${os.arch()}/${os.release()}`
+export const getProductInfo = () : string => `${DEFAULT_AGENT_NAME.toLowerCase()}/${version} nodejs/${process.version} ${os.platform()}-${os.arch()}/${os.release()}`
+
+/**
+ * Applies the SDK product information to the User-Agent header of outgoing requests.
+ * @param headers The HeaderPropagationCollection to which the User-Agent header will be added or updated
+ */
+export function applyUserAgentHeader (headers: HeaderPropagationCollection): void {
+  const userAgentKey = headers.key?.('User-Agent') ?? 'User-Agent'
+  const userAgent = headers.outgoing[userAgentKey] ?? headers.incoming[userAgentKey]
+  const productInfo = getProductInfo()
+  if (!userAgent) {
+    headers.add({ [userAgentKey]: productInfo })
+  } else if (!userAgent.includes(productInfo)) {
+    headers.concat({ [userAgentKey]: productInfo })
+  } else {
+    headers.propagate([userAgentKey])
+  }
+}
+
+/**
+ * Applies standardized agent-related headers for agentic requests.
+ *
+ * @param headers The HeaderPropagationCollection to which the agent headers will be applied.
+ * @param activity The incoming Activity containing agentic request information.
+ * @param agentName An optional human-friendly name for the agent, which will be validated and included in the headers.
+ *
+ * @remarks
+ * The function sets the following headers:
+ * - `AgentRegistrar`: A fixed value indicating the registrar of the agent (e.g., "A365").
+ * - `AgentName`: A human-friendly name for the agent, validated against a pattern to ensure it only contains allowed characters.
+ * - `AgentID`: A unique identifier for the agent instance, resolved from the activity's agentic instance ID or agentic user.
+ * - `Agent-Referrer`: The channel ID from the incoming activity, indicating the source of the request.
+ * The function ensures that the agent headers are consistently applied to outgoing requests for proper identification and tracing.
+ */
+export function applyAgenticHeaders (
+  headers: HeaderPropagationCollection,
+  activity: Activity,
+  agentName?: string
+): void {
+  headers.override({
+    AgentRegistrar: AGENT_REGISTRAR,
+    AgentName: normalizeAgentName(agentName),
+    AgentID: resolveAgentId(activity),
+    'Agent-Referrer': activity.channelId ?? '',
+  })
+}
+
+function resolveAgentId (activity: Activity): string {
+  const agentId = activity.getAgenticInstanceId() ?? activity.getAgenticUser()
+
+  if (!agentId) {
+    throw ExceptionHelper.generateException(Error, Errors.AgentIdRequired)
+  }
+
+  return agentId
+}
+
+function normalizeAgentName (agentName?: string): string {
+  const normalizedAgentName = agentName?.trim()
+  if (!normalizedAgentName) {
+    return DEFAULT_AGENT_NAME
+  }
+
+  if (!AGENT_NAME_PATTERN.test(normalizedAgentName)) {
+    throw ExceptionHelper.generateException(Error, Errors.AgentNameInvalid, undefined, { agentName: normalizedAgentName })
+  }
+
+  return normalizedAgentName
+}

package/src/headerPropagation.ts

@@ -8,10 +8,11 @@
  * It filters the incoming request headers based on the definition provided and loads them into the outgoing headers collection.
  */
 export class HeaderPropagation implements HeaderPropagationCollection {
+  private _keys: string[] = []
   private _incomingRequests: Record<string, string>
   private _outgoingHeaders: Record<string, string> = {}
 
-  private _headersToPropagate = ['x-ms-correlation-id']
+  private _protectedHeaders = ['x-ms-correlation-id']
 
   public get incoming (): Record<string, string> {
     return this._incomingRequests
@@ -27,54 +28,78 @@ export class HeaderPropagation implements HeaderPropagationCollection {
     }
 
     this._incomingRequests = this.normalizeHeaders(headers)
-    this.propagate(this._headersToPropagate)
+
+    // Ensure protected headers are propagated from incoming to outgoing by default without allowing modifications.
+    const protectedHeaders = [...this._protectedHeaders]
+    this._protectedHeaders = [] // Temporarily clear protected headers to allow propagation without restriction
+    this.propagate(protectedHeaders)
+    this._protectedHeaders = protectedHeaders // Restore protected headers list after propagation
   }
 
   propagate (headers: string[]) {
-    for (const key of headers ?? []) {
-      const lowerKey = key.toLowerCase()
-      if (this._incomingRequests[lowerKey] && !this._outgoingHeaders[lowerKey]) {
-        this._outgoingHeaders[lowerKey] = this._incomingRequests[lowerKey]
+    this.process(headers.map(h => [h, '']), key => {
+      if (this._incomingRequests[key] && !this._outgoingHeaders[key]) {
+        this._outgoingHeaders[key] = this._incomingRequests[key]
       }
-    }
+    })
   }
 
   add (headers: Record<string, string>) {
-    for (const [key, value] of Object.entries(headers ?? {})) {
-      const lowerKey = key.toLowerCase()
-      if (!this._incomingRequests[lowerKey] && !this._outgoingHeaders[lowerKey]) {
-        this._outgoingHeaders[lowerKey] = value
+    this.process(Object.entries(headers ?? {}), (key, value) => {
+      if (!this._incomingRequests[key] && !this._outgoingHeaders[key]) {
+        this._outgoingHeaders[key] = value
       }
-    }
+    })
   }
 
   concat (headers: Record<string, string>) {
-    for (const [key, value] of Object.entries(headers ?? {})) {
-      const lowerKey = key.toLowerCase()
-      if (this._incomingRequests[lowerKey] && !this._headersToPropagate.includes(lowerKey)) {
-        this._outgoingHeaders[lowerKey] = `${this._outgoingHeaders[lowerKey] ?? this._incomingRequests[lowerKey]} ${value}`.trim()
+    this.process(Object.entries(headers ?? {}), (key, value) => {
+      if (this._incomingRequests[key] || this._outgoingHeaders[key]) {
+        this._outgoingHeaders[key] = `${this._outgoingHeaders[key] ?? this._incomingRequests[key]} ${value}`.trim()
       }
-    }
+    })
   }
 
   override (headers: Record<string, string>) {
-    for (const [key, value] of Object.entries(headers ?? {})) {
-      const lowerKey = key.toLowerCase()
-      if (!this._headersToPropagate.includes(lowerKey)) {
-        this._outgoingHeaders[lowerKey] = value
+    this.process(Object.entries(headers ?? {}), (key, value) => {
+      this._outgoingHeaders[key] = value
+    })
+  }
+
+  key (key: string) {
+    return this._keys.find(k => k.toLowerCase() === key.toLowerCase())
+  }
+
+  /**
+   * A helper method to process headers based on a provided callback function. It iterates over the headers and applies the callback to each header key and value.
+   * @param headers An array of header key-value pairs to process.
+   * @param callback A function that takes a header key and value, allowing for custom processing logic to be applied to each header.
+   */
+  private process (headers: [string, string][], callback: (key: string, value: string) => void) {
+    for (const [key, value] of headers) {
+      const savedKey = this.key(key)
+      const realKey = savedKey ?? key
+      if (!savedKey) {
+        this._keys.push(realKey)
+      }
+      if (!this._protectedHeaders.includes(key.toLowerCase())) {
+        callback(realKey, value)
       }
     }
   }
 
   /**
-   * Normalizes the headers by lowercasing the keys and ensuring the values are strings.
+   * Normalizes the headers by ensuring the values are strings.
    * @param headers The headers to normalize.
    * @returns A new object with normalized headers.
    */
   private normalizeHeaders (headers: Record<string, string | string[] | undefined>) {
     return Object.entries(headers).reduce((acc, [key, value]) => {
       if (value) {
-        acc[key.toLowerCase()] = Array.isArray(value) ? value.join(' ') : value
+        acc[key] = Array.isArray(value) ? value.join(' ') : value
+        if (!this._keys.includes(key)) {
+          this._keys.push(key) // Store the original casing of the header keys
+        }
       }
       return acc
     }, {} as Record<string, string>)
@@ -138,4 +163,11 @@ export interface HeaderPropagationCollection {
    * If the header does not exist in the incoming headers, it will be added to the outgoing collection.
    */
   override(headers: Record<string, string>): void
+  /**
+   * Resolves the actual header key in a case-insensitive manner.
+   * This is useful for ensuring that headers are accessed correctly regardless of their case in the incoming request.
+   * @param key The header key to resolve.
+   * @returns The resolved header key or undefined if not found.
+   */
+  key?(key: string): string | undefined
 }

package/src/httpClient.ts

@@ -0,0 +1,223 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Readable } from 'node:stream'
+import { Errors } from './errorHelper'
+
+/**
+ * Configuration for an HTTP request.
+ */
+export interface HttpRequestConfig {
+  method: string
+  url: string
+  headers?: Record<string, string>
+  data?: unknown
+  params?: Record<string, string | undefined>
+  responseType?: 'json' | 'arraybuffer' | 'stream'
+  timeout?: number
+  signal?: AbortSignal
+}
+
+/**
+ * Represents an HTTP response.
+ */
+export interface HttpResponse<T = unknown> {
+  data: T
+  status: number
+  statusText: string
+  headers: Headers
+  config: HttpRequestConfig
+}
+
+/**
+ * Options for creating an HttpClient instance.
+ */
+export interface HttpClientOptions {
+  baseURL?: string
+  headers?: Record<string, string>
+}
+
+/**
+ * A lightweight HTTP client built on native fetch.
+ */
+export class HttpClient {
+  private _baseURL: string
+  private _defaultHeaders: Record<string, string>
+
+  constructor (options: HttpClientOptions = {}) {
+    this._baseURL = options.baseURL ?? ''
+    this._defaultHeaders = this.normalizeHeaders(options.headers)
+  }
+
+  get baseURL (): string {
+    return this._baseURL
+  }
+
+  get defaultHeaders (): Record<string, string> {
+    return this._defaultHeaders
+  }
+
+  set defaultHeaders (headers: Record<string, string>) {
+    this._defaultHeaders = this.normalizeHeaders(headers)
+  }
+
+  setHeader (name: string, value: string): void {
+    this._defaultHeaders[name.toLowerCase()] = value
+  }
+
+  async request<T = unknown> (config: HttpRequestConfig): Promise<HttpResponse<T>> {
+    const url = this.buildUrl(config.url, config.params)
+    const headers = this.normalizeHeaders({ ...this._defaultHeaders, ...config.headers })
+    const requestHeaders = new Headers(headers)
+    const fetchOptions: RequestInit = {
+      method: config.method.toUpperCase(),
+      headers: requestHeaders,
+      signal: config.signal ??
+    (config.timeout ? AbortSignal.timeout(config.timeout) : undefined)
+    }
+
+    if (config.data !== undefined && config.data !== null) {
+      const contentType = requestHeaders.get('content-type') ?? ''
+      if (contentType.includes('application/x-www-form-urlencoded')) {
+        fetchOptions.body = new URLSearchParams(config.data as Record<string, string>).toString()
+      } else if (config.data instanceof URLSearchParams) {
+        if (!contentType) {
+          requestHeaders.set('content-type', 'application/x-www-form-urlencoded;charset=utf-8')
+        }
+        fetchOptions.body = config.data.toString()
+      } else if (typeof config.data === 'string') {
+        fetchOptions.body = config.data
+      } else if (config.data instanceof Uint8Array || config.data instanceof ArrayBuffer ||
+            config.data instanceof Blob || config.data instanceof FormData ||
+            config.data instanceof ReadableStream) {
+        fetchOptions.body = config.data
+      } else {
+        if (!contentType) {
+          requestHeaders.set('content-type', 'application/json')
+        }
+        fetchOptions.body = JSON.stringify(config.data)
+      }
+    }
+
+    const response = await fetch(url, fetchOptions)
+
+    let data: T
+    if (config.responseType === 'stream') {
+      if (!response.ok) {
+        data = await response.text() as T
+      } else {
+        data = Readable.fromWeb(response.body ?? new ReadableStream()) as T
+      }
+    } else if (config.responseType === 'arraybuffer') {
+      data = await response.arrayBuffer() as T
+    } else {
+      const text = await response.text()
+      try {
+        data = JSON.parse(text) as T
+      } catch {
+        data = text as T
+      }
+    }
+
+    const httpResponse: HttpResponse<T> = {
+      data,
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+      config,
+    }
+
+    if (!response.ok) {
+      const error: HttpError = new HttpError(
+        `Request failed with status ${response.status}`,
+        httpResponse,
+        config
+      )
+      throw error
+    }
+
+    return httpResponse
+  }
+
+  async get<T = unknown> (url: string, options?: Partial<HttpRequestConfig>): Promise<HttpResponse<T>> {
+    return this.request<T>({ method: 'get', url, ...options })
+  }
+
+  private buildUrl (path: string, params?: Record<string, string | undefined>): string {
+    let url: string
+    if (path.startsWith('http://') || path.startsWith('https://')) {
+      url = path
+    } else {
+      if (!this._baseURL) {
+        throw ExceptionHelper.generateException(Error, Errors.HttpClientRelativeUrlRequiresBaseUrl, undefined, { url: path })
+      }
+
+      const base = this._baseURL.endsWith('/') ? this._baseURL.slice(0, -1) : this._baseURL
+      const cleanPath = path.startsWith('/') ? path : `/${path}`
+      url = `${base}${cleanPath}`
+    }
+
+    if (params) {
+      const searchParams = new URLSearchParams()
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+          searchParams.set(key, value)
+        }
+      }
+      const queryString = searchParams.toString()
+      if (queryString) {
+        url += `${url.includes('?') ? '&' : '?'}${queryString}`
+      }
+    }
+
+    return url
+  }
+
+  private normalizeHeaders (headers?: Record<string, string>): Record<string, string> {
+    if (!headers) {
+      return {}
+    }
+
+    return Object.entries(headers).reduce((normalized, [name, value]) => {
+      normalized[name.toLowerCase()] = value
+      return normalized
+    }, {} as Record<string, string>)
+  }
+}
+
+/**
+ * Error thrown when an HTTP request fails.
+ */
+export class HttpError extends Error {
+  public readonly response: HttpResponse
+  public readonly config: HttpRequestConfig
+  public readonly status: number
+
+  constructor (message: string, response: HttpResponse, config: HttpRequestConfig) {
+    super(message)
+    this.name = 'HttpError'
+    this.response = response
+    this.config = config
+    this.status = response.status
+  }
+
+  toJSON (): Record<string, unknown> {
+    return {
+      message: this.message,
+      status: this.status,
+      config: {
+        url: this.config.url,
+        method: this.config.method,
+        data: this.config.data,
+      },
+      response: {
+        status: this.response.status,
+        statusText: this.response.statusText,
+        data: this.response.data,
+      },
+    }
+  }
+}

package/src/index.ts

@@ -4,7 +4,7 @@
  */
 
 export * from './auth/'
-export { authorizeJWT, buildJwksUri } from './auth/jwt-middleware'
+export { authorizeJWT, buildJwksUri, clearJwksClients } from './auth/jwt-middleware'
 
 export * from './app'
 export * from './cards'
@@ -18,7 +18,10 @@ export * from './transcript'
 
 export * from './activityHandler'
 export * from './baseAdapter'
-export * from './cloudAdapter'
+// Note: re-export the public surface of `cloudAdapter` explicitly so the
+// test-only internals (e.g., the per-process warning dedup set) do not leak
+// into the package's public API.
+export { CloudAdapter, type CloudAdapterOptions } from './cloudAdapter'
 export * from './middlewareSet'
 export * from './messageFactory'
 export * from './statusCodes'
@@ -26,5 +29,6 @@ export * from './turnContext'
 export * from './turnContextStateCollection'
 export * from './storage/storage'
 export * from './headerPropagation'
+export * from './httpClient'
 
 export * from './agent-client'