@cuylabs/agent-a365-observability 4.5.0 → 4.6.0

package/dist/index.js

@@ -1,3 +1,10 @@
+// src/types.ts
+var A365_EXPORTER_EVENT_NAMES = {
+  export: "agent365-export",
+  exportGroup: "export-group",
+  exportPartitionSpanMissingIdentity: "export-partition-span-missing-identity"
+};
+
 // src/errors.ts
 var A365ObservabilityModuleLoadError = class extends Error {
   constructor(message, options) {
@@ -5,41 +12,14 @@ var A365ObservabilityModuleLoadError = class extends Error {
     this.name = "A365ObservabilityModuleLoadError";
   }
 };
-
-// src/baggage-keys.ts
-var A365_BAGGAGE_KEYS = {
-  tenantId: "microsoft.tenant.id",
-  agentId: "gen_ai.agent.id",
-  agentName: "gen_ai.agent.name",
-  agentDescription: "gen_ai.agent.description",
-  agentVersion: "gen_ai.agent.version",
-  agentPlatformId: "microsoft.a365.agent.platform.id",
-  agentAuid: "microsoft.agent.user.id",
-  agentEmail: "microsoft.agent.user.email",
-  agentBlueprintId: "microsoft.a365.agent.blueprint.id",
-  sessionId: "microsoft.session.id",
-  sessionDescription: "microsoft.session.description",
-  conversationId: "gen_ai.conversation.id",
-  conversationItemLink: "microsoft.conversation.item.link",
-  channelName: "microsoft.channel.name",
-  channelLink: "microsoft.channel.link",
-  userId: "user.id",
-  userName: "user.name",
-  userEmail: "user.email",
-  callerClientIp: "client.address",
-  callerAgentId: "microsoft.a365.caller.agent.id",
-  callerAgentName: "microsoft.a365.caller.agent.name",
-  callerAgentAuid: "microsoft.a365.caller.agent.user.id",
-  callerAgentEmail: "microsoft.a365.caller.agent.user.email",
-  callerAgentBlueprintId: "microsoft.a365.caller.agent.blueprint.id",
-  callerAgentPlatformId: "microsoft.a365.caller.agent.platform.id",
-  callerAgentVersion: "microsoft.a365.caller.agent.version",
-  serviceName: "service.name",
-  serverAddress: "server.address",
-  serverPort: "server.port"
+var A365ObservabilityHostingModuleLoadError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "A365ObservabilityHostingModuleLoadError";
+  }
 };
 
-// src/internal/parsing.ts
+// src/internal/values.ts
 function setPair(target, key, value) {
   if (value === null || value === void 0) {
     return;
@@ -115,7 +95,480 @@ function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
 
-// src/baggage.ts
+// src/auth/oauth-token-endpoint.ts
+var CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+var DEFAULT_TOKEN_LIFETIME_MS = 55 * 60 * 1e3;
+async function requestClientSecretToken(client, request, extra) {
+  const body = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: request.clientId,
+    client_secret: request.clientSecret,
+    scope: request.scope
+  });
+  if (extra?.fmiPath) {
+    body.set("fmi_path", extra.fmiPath);
+  }
+  return await requestToken(client, body);
+}
+async function requestClientAssertionToken(client, request, extra) {
+  const body = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: request.clientId,
+    client_assertion: request.clientAssertion,
+    client_assertion_type: CLIENT_ASSERTION_TYPE,
+    scope: request.scope
+  });
+  if (extra?.fmiPath) {
+    body.set("fmi_path", extra.fmiPath);
+  }
+  return await requestToken(client, body);
+}
+async function requestToken(client, body) {
+  const response = await client.fetch(
+    `https://login.microsoftonline.com/${encodeURIComponent(
+      client.tenantId
+    )}/oauth2/v2.0/token`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString()
+    }
+  );
+  const payload = parseTokenEndpointResponse(await response.text());
+  if (!response.ok || !payload.access_token) {
+    throw new Error(
+      payload.error_description || payload.error || `token endpoint returned HTTP ${response.status}`
+    );
+  }
+  const expiresInMs = typeof payload.expires_in === "number" && payload.expires_in > 0 ? payload.expires_in * 1e3 : DEFAULT_TOKEN_LIFETIME_MS;
+  return {
+    accessToken: payload.access_token,
+    expiresAtMs: Date.now() + expiresInMs
+  };
+}
+function parseTokenEndpointResponse(body) {
+  if (!body) {
+    return {};
+  }
+  try {
+    return JSON.parse(body);
+  } catch {
+    return { error_description: body };
+  }
+}
+
+// src/auth/s2s-token-resolver.ts
+var DEFAULT_FMI_SCOPE = "api://AzureADTokenExchange/.default";
+var DEFAULT_OBSERVABILITY_SCOPE = "api://9b975845-388f-4429-889e-eab1ef63949c/.default";
+var DEFAULT_REFRESH_SKEW_MS = 5 * 60 * 1e3;
+function createA365S2STokenResolver(options) {
+  const normalized = normalizeOptions(options);
+  const cache = /* @__PURE__ */ new Map();
+  return async (agentId, tenantId) => {
+    const request = {
+      ...normalized,
+      agentId: firstNonEmpty(agentId, normalized.agentId) ?? "",
+      tenantId: firstNonEmpty(tenantId, normalized.tenantId) ?? ""
+    };
+    const cacheKey = `${request.tenantId}:${request.agentId}`;
+    const cached = cache.get(cacheKey);
+    if (cached && cached.expiresAtMs - request.refreshSkewMs > Date.now()) {
+      return cached.accessToken;
+    }
+    try {
+      const token = await acquireObservabilityToken(request);
+      cache.set(cacheKey, token);
+      return token.accessToken;
+    } catch (error) {
+      request.logger?.warn("Failed to acquire Agent 365 S2S token", {
+        error: error instanceof Error ? error.message : String(error),
+        useManagedIdentity: request.useManagedIdentity
+      });
+      return null;
+    }
+  };
+}
+function normalizeOptions(options) {
+  return {
+    tenantId: requireNonEmpty("tenantId", options.tenantId),
+    agentId: requireNonEmpty("agentId", options.agentId),
+    blueprintClientId: requireNonEmpty(
+      "blueprintClientId",
+      options.blueprintClientId
+    ),
+    ...options.blueprintClientSecret ? { blueprintClientSecret: options.blueprintClientSecret } : {},
+    useManagedIdentity: options.useManagedIdentity ?? false,
+    ...options.managedIdentityAssertionProvider ? {
+      managedIdentityAssertionProvider: options.managedIdentityAssertionProvider
+    } : {},
+    allowManagedIdentityClientSecretFallback: options.allowManagedIdentityClientSecretFallback ?? true,
+    observabilityScope: options.observabilityScope ?? DEFAULT_OBSERVABILITY_SCOPE,
+    fmiScope: options.fmiScope ?? DEFAULT_FMI_SCOPE,
+    refreshSkewMs: options.refreshSkewMs ?? DEFAULT_REFRESH_SKEW_MS,
+    ...options.logger ? { logger: options.logger } : {},
+    fetch: options.fetch ?? globalThis.fetch.bind(globalThis)
+  };
+}
+async function acquireObservabilityToken(options) {
+  const t1Token = await acquireFmiToken(options);
+  return await requestClientAssertionToken(options, {
+    clientId: options.agentId,
+    clientAssertion: t1Token.accessToken,
+    scope: options.observabilityScope
+  });
+}
+async function acquireFmiToken(options) {
+  if (options.useManagedIdentity) {
+    try {
+      const assertion = await options.managedIdentityAssertionProvider?.();
+      if (!assertion) {
+        throw new Error(
+          "managed identity assertion provider returned no token"
+        );
+      }
+      return await requestClientAssertionToken(
+        options,
+        {
+          clientId: options.blueprintClientId,
+          clientAssertion: assertion,
+          scope: options.fmiScope
+        },
+        { fmiPath: options.agentId }
+      );
+    } catch (error) {
+      if (!options.allowManagedIdentityClientSecretFallback || !options.blueprintClientSecret) {
+        throw error;
+      }
+      options.logger?.warn(
+        "Managed identity FMI token exchange failed; falling back to blueprint client secret",
+        { error: error instanceof Error ? error.message : String(error) }
+      );
+    }
+  }
+  return await requestClientSecretToken(
+    options,
+    {
+      clientId: options.blueprintClientId,
+      clientSecret: requireNonEmpty(
+        "blueprintClientSecret",
+        options.blueprintClientSecret
+      ),
+      scope: options.fmiScope
+    },
+    { fmiPath: options.agentId }
+  );
+}
+function requireNonEmpty(name, value) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    throw new Error(`${name} is required`);
+  }
+  return normalized;
+}
+
+// src/auth/env.ts
+var TRUE_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "y", "on"]);
+var FALSE_VALUES = /* @__PURE__ */ new Set(["0", "false", "no", "n", "off"]);
+function resolveA365ObservabilityEnvironment(env = process.env) {
+  const reader = createEnvReader(env);
+  return {
+    tenantId: reader(
+      "A365_OBSERVABILITY_TENANT_ID",
+      "agent365Observability__tenantId"
+    ),
+    agentId: reader(
+      "A365_OBSERVABILITY_AGENT_ID",
+      "agent365Observability__agentId"
+    ),
+    agentName: reader(
+      "A365_OBSERVABILITY_AGENT_NAME",
+      "agent365Observability__agentName"
+    ),
+    agentDescription: reader(
+      "A365_OBSERVABILITY_AGENT_DESCRIPTION",
+      "agent365Observability__agentDescription"
+    ),
+    blueprintClientId: reader(
+      "A365_OBSERVABILITY_BLUEPRINT_CLIENT_ID",
+      "A365_OBSERVABILITY_CLIENT_ID",
+      "agent365Observability__clientId",
+      "agent365Observability__agentBlueprintId"
+    ),
+    blueprintClientSecret: reader(
+      "A365_OBSERVABILITY_BLUEPRINT_CLIENT_SECRET",
+      "A365_OBSERVABILITY_CLIENT_SECRET",
+      "agent365Observability__clientSecret"
+    ),
+    useManagedIdentity: readBoolean(
+      reader(
+        "A365_OBSERVABILITY_USE_MANAGED_IDENTITY",
+        "agent365Observability__useManagedIdentity"
+      )
+    ),
+    observabilityScope: reader(
+      "A365_OBSERVABILITY_SCOPE",
+      "A365_OBSERVABILITY_SCOPES",
+      "agent365Observability__observabilityScope"
+    ),
+    fmiScope: reader(
+      "A365_OBSERVABILITY_FMI_SCOPE",
+      "A365_FMI_SCOPE",
+      "agent365Observability__fmiScope"
+    ),
+    configuration: {
+      exporterEnabled: readBoolean(
+        reader(
+          "ENABLE_A365_OBSERVABILITY_EXPORTER",
+          "agent365Observability__exporterEnabled"
+        )
+      ),
+      domainOverride: reader(
+        "A365_OBSERVABILITY_DOMAIN_OVERRIDE",
+        "agent365Observability__domainOverride"
+      ),
+      logLevel: reader(
+        "A365_OBSERVABILITY_LOG_LEVEL",
+        "agent365Observability__logLevel"
+      ),
+      authenticationScopes: splitScopes(
+        reader(
+          "A365_OBSERVABILITY_AUTHENTICATION_SCOPES",
+          "A365_OBSERVABILITY_SCOPES_OVERRIDE",
+          "agent365Observability__authenticationScopes"
+        )
+      ),
+      perRequest: {
+        enabled: readBoolean(
+          reader(
+            "ENABLE_A365_OBSERVABILITY_PER_REQUEST_EXPORT",
+            "agent365Observability__perRequestExportEnabled"
+          )
+        ),
+        maxTraces: readNumber(
+          reader(
+            "A365_PER_REQUEST_MAX_TRACES",
+            "agent365Observability__perRequestMaxTraces"
+          )
+        ),
+        maxSpansPerTrace: readNumber(
+          reader(
+            "A365_PER_REQUEST_MAX_SPANS_PER_TRACE",
+            "agent365Observability__perRequestMaxSpansPerTrace"
+          )
+        ),
+        maxConcurrentExports: readNumber(
+          reader(
+            "A365_PER_REQUEST_MAX_CONCURRENT_EXPORTS",
+            "agent365Observability__perRequestMaxConcurrentExports"
+          )
+        ),
+        flushGraceMs: readNumber(
+          reader(
+            "A365_PER_REQUEST_FLUSH_GRACE_MS",
+            "agent365Observability__perRequestFlushGraceMs"
+          )
+        ),
+        maxTraceAgeMs: readNumber(
+          reader(
+            "A365_PER_REQUEST_MAX_TRACE_AGE_MS",
+            "agent365Observability__perRequestMaxTraceAgeMs"
+          )
+        )
+      }
+    }
+  };
+}
+function createA365S2STokenResolverFromEnv(options = {}) {
+  const env = resolveA365ObservabilityEnvironment(options.env);
+  return createA365S2STokenResolver({
+    ...options,
+    tenantId: requireValue(
+      "tenantId",
+      firstNonEmpty(options.tenantId, env.tenantId)
+    ),
+    agentId: requireValue(
+      "agentId",
+      firstNonEmpty(options.agentId, env.agentId)
+    ),
+    blueprintClientId: requireValue(
+      "blueprintClientId",
+      firstNonEmpty(options.blueprintClientId, env.blueprintClientId)
+    ),
+    blueprintClientSecret: firstNonEmpty(
+      options.blueprintClientSecret,
+      env.blueprintClientSecret
+    ),
+    useManagedIdentity: options.useManagedIdentity ?? env.useManagedIdentity ?? Boolean(options.managedIdentityAssertionProvider),
+    observabilityScope: firstNonEmpty(
+      options.observabilityScope,
+      env.observabilityScope
+    ),
+    fmiScope: firstNonEmpty(options.fmiScope, env.fmiScope)
+  });
+}
+function createEnvReader(env) {
+  const normalized = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== void 0) {
+      normalized.set(key.toLowerCase(), value);
+    }
+  }
+  return (...names) => {
+    for (const name of names) {
+      const value = firstNonEmpty(
+        env[name],
+        normalized.get(name.toLowerCase())
+      );
+      if (value) {
+        return value;
+      }
+    }
+    return void 0;
+  };
+}
+function readBoolean(value) {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) {
+    return void 0;
+  }
+  if (TRUE_VALUES.has(normalized)) {
+    return true;
+  }
+  if (FALSE_VALUES.has(normalized)) {
+    return false;
+  }
+  return void 0;
+}
+function readNumber(value) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    return void 0;
+  }
+  const parsed = Number(normalized);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function splitScopes(value) {
+  const scopes = value?.split(/\s+/).filter(Boolean);
+  return scopes && scopes.length > 0 ? scopes : void 0;
+}
+function requireValue(name, value) {
+  if (!value) {
+    throw new Error(`${name} is required`);
+  }
+  return value;
+}
+
+// src/runtime/module-loader.ts
+var OBSERVABILITY_PACKAGE = "@microsoft/agents-a365-observability";
+var OBSERVABILITY_HOSTING_PACKAGE = "@microsoft/agents-a365-observability-hosting";
+async function loadObservabilityModule(options = {}) {
+  try {
+    if (options.getObservabilityModule) {
+      return await options.getObservabilityModule();
+    }
+    return await import(OBSERVABILITY_PACKAGE);
+  } catch (error) {
+    throw new A365ObservabilityModuleLoadError(
+      `Unable to load ${OBSERVABILITY_PACKAGE}. Install @microsoft/agents-a365-observability and @microsoft/agents-a365-runtime before using @cuylabs/agent-a365-observability.`,
+      { cause: error }
+    );
+  }
+}
+async function loadObservabilityHostingModule(options = {}) {
+  try {
+    if (options.getObservabilityHostingModule) {
+      return await options.getObservabilityHostingModule();
+    }
+    return await import(OBSERVABILITY_HOSTING_PACKAGE);
+  } catch (error) {
+    throw new A365ObservabilityHostingModuleLoadError(
+      `Unable to load ${OBSERVABILITY_HOSTING_PACKAGE}. Install @microsoft/agents-a365-observability-hosting before using OBO Agent 365 observability helpers.`,
+      { cause: error }
+    );
+  }
+}
+
+// src/auth/obo-token-cache.ts
+function createA365OboTokenResolver(options = {}) {
+  let cachePromise;
+  return async (agentId, tenantId) => {
+    cachePromise ??= getAgenticTokenCache(options);
+    const cache = await cachePromise;
+    return cache.getObservabilityToken(agentId, tenantId);
+  };
+}
+async function refreshA365OboObservabilityToken(options) {
+  const cache = await getAgenticTokenCache(options);
+  await cache.RefreshObservabilityToken(
+    options.agentId,
+    options.tenantId,
+    options.turnContext,
+    options.authorization,
+    options.scopes ?? [],
+    options.authHandlerName
+  );
+}
+async function invalidateA365OboObservabilityToken(agentId, tenantId, options = {}) {
+  const cache = await getAgenticTokenCache(options);
+  cache.invalidateToken?.(agentId, tenantId);
+}
+async function invalidateAllA365OboObservabilityTokens(options = {}) {
+  const cache = await getAgenticTokenCache(options);
+  cache.invalidateAll?.();
+}
+async function getAgenticTokenCache(options) {
+  if (options.cache) {
+    return options.cache;
+  }
+  const module = await loadObservabilityHostingModule(options);
+  return getCacheFromModule(module);
+}
+function getCacheFromModule(module) {
+  if (module.AgenticTokenCacheInstance) {
+    return module.AgenticTokenCacheInstance;
+  }
+  if (module.AgenticTokenCache) {
+    return new module.AgenticTokenCache();
+  }
+  throw new Error(
+    "Agent 365 observability hosting module does not export AgenticTokenCache."
+  );
+}
+
+// src/context/baggage-keys.ts
+var A365_BAGGAGE_KEYS = {
+  tenantId: "microsoft.tenant.id",
+  agentId: "gen_ai.agent.id",
+  agentName: "gen_ai.agent.name",
+  agentDescription: "gen_ai.agent.description",
+  agentVersion: "gen_ai.agent.version",
+  agentPlatformId: "microsoft.a365.agent.platform.id",
+  agentAuid: "microsoft.agent.user.id",
+  agentEmail: "microsoft.agent.user.email",
+  agentBlueprintId: "microsoft.a365.agent.blueprint.id",
+  sessionId: "microsoft.session.id",
+  sessionDescription: "microsoft.session.description",
+  conversationId: "gen_ai.conversation.id",
+  conversationItemLink: "microsoft.conversation.item.link",
+  channelName: "microsoft.channel.name",
+  channelLink: "microsoft.channel.link",
+  userId: "user.id",
+  userName: "user.name",
+  userEmail: "user.email",
+  callerClientIp: "client.address",
+  callerAgentId: "microsoft.a365.caller.agent.id",
+  callerAgentName: "microsoft.a365.caller.agent.name",
+  callerAgentAuid: "microsoft.a365.caller.agent.user.id",
+  callerAgentEmail: "microsoft.a365.caller.agent.user.email",
+  callerAgentBlueprintId: "microsoft.a365.caller.agent.blueprint.id",
+  callerAgentPlatformId: "microsoft.a365.caller.agent.platform.id",
+  callerAgentVersion: "microsoft.a365.caller.agent.version",
+  serviceName: "service.name",
+  serverAddress: "server.address",
+  serverPort: "server.port"
+};
+
+// src/context/baggage.ts
 function buildA365BaggagePairs(context) {
   const pairs = {};
   for (const [key, value] of Object.entries(context.extraBaggage ?? {})) {
@@ -173,28 +626,7 @@ function buildA365BaggagePairs(context) {
   return pairs;
 }
 
-// src/tracing-config.ts
-function createA365TracingConfig(options = {}) {
-  const spanAttributes = {
-    ...options.spanAttributes ?? {}
-  };
-  if (isNonEmpty(options.tenantId)) {
-    spanAttributes[A365_BAGGAGE_KEYS.tenantId] = options.tenantId.trim();
-  }
-  return {
-    ...isNonEmpty(options.agentId) ? { agentId: options.agentId.trim() } : {},
-    ...isNonEmpty(options.agentDescription) ? { agentDescription: options.agentDescription.trim() } : {},
-    ...isNonEmpty(options.agentVersion) ? { agentVersion: options.agentVersion.trim() } : {},
-    ...options.useGenAIOpenTelemetry !== void 0 ? { useGenAIOpenTelemetry: options.useGenAIOpenTelemetry } : {},
-    ...options.telemetryIntegrations ? { telemetryIntegrations: options.telemetryIntegrations } : {},
-    ...options.useGlobalTelemetryIntegrations !== void 0 ? {
-      useGlobalTelemetryIntegrations: options.useGlobalTelemetryIntegrations
-    } : {},
-    ...Object.keys(spanAttributes).length > 0 ? { spanAttributes } : {}
-  };
-}
-
-// src/turn-context.ts
+// src/context/turn-context.ts
 function createA365ContextFromTurnContext(turnContext, options = {}) {
   const { serviceUrl, useRecipientIdAsAgentId, ...requestOptions } = options;
   const activity = turnContext.activity ?? {};
@@ -215,132 +647,144 @@ function createA365ContextFromTurnContext(turnContext, options = {}) {
     readPath(channelData, ["tenant", "id"]),
     readPath(channelData, ["tenantId"])
   );
-  return {
-    ...requestOptions,
-    ...tenantId ? { tenantId } : {},
-    ...agentId ? { agentId } : {},
-    ...firstNonEmpty(requestOptions.agentName, activity.recipient?.name) ? {
-      agentName: firstNonEmpty(
-        requestOptions.agentName,
-        activity.recipient?.name
-      )
-    } : {},
-    // Mirrors Microsoft's A365 observability-hosting helper, which maps
-    // recipient.role to gen_ai.agent.description.
-    ...firstNonEmpty(requestOptions.agentDescription, activity.recipient?.role) ? {
-      agentDescription: firstNonEmpty(
-        requestOptions.agentDescription,
-        activity.recipient?.role
-      )
-    } : {},
-    ...firstNonEmpty(requestOptions.agentAuid, activity.recipient?.aadObjectId) ? {
-      agentAuid: firstNonEmpty(
-        requestOptions.agentAuid,
-        activity.recipient?.aadObjectId
-      )
-    } : {},
-    ...firstNonEmpty(
+  const agentName = firstNonEmpty(
+    requestOptions.agentName,
+    activity.recipient?.name
+  );
+  const agentDescription = firstNonEmpty(
+    requestOptions.agentDescription,
+    activity.recipient?.role
+  );
+  const conversationId = firstNonEmpty(
+    requestOptions.conversationId,
+    activity.conversation?.id
+  );
+  const conversationItemLink = firstNonEmpty(
+    requestOptions.conversationItemLink,
+    activity.serviceUrl
+  );
+  const sessionId = firstNonEmpty(
+    requestOptions.sessionId,
+    requestOptions.conversationId,
+    activity.conversation?.id
+  );
+  const userId = firstNonEmpty(
+    requestOptions.userId,
+    activity.from?.aadObjectId,
+    activity.from?.id,
+    readPath(turnContext.identity, ["oid"]),
+    readPath(turnContext.identity, ["sub"])
+  );
+  const userEmail = firstNonEmpty(
+    requestOptions.userEmail,
+    activity.from?.email,
+    activity.from?.userPrincipalName,
+    activity.from?.agenticUserId,
+    readPath(channelData, ["from", "userPrincipalName"]),
+    readPath(turnContext.identity, ["preferred_username"]),
+    readPath(turnContext.identity, ["upn"])
+  );
+  const context = { ...requestOptions };
+  setIfDefined(context, "tenantId", tenantId);
+  setIfDefined(context, "agentId", agentId);
+  setIfDefined(context, "agentName", agentName);
+  setIfDefined(context, "agentDescription", agentDescription);
+  setIfDefined(
+    context,
+    "agentAuid",
+    firstNonEmpty(requestOptions.agentAuid, activity.recipient?.aadObjectId)
+  );
+  setIfDefined(
+    context,
+    "agentBlueprintId",
+    firstNonEmpty(
       requestOptions.agentBlueprintId,
       activity.recipient?.agenticAppBlueprintId
-    ) ? {
-      agentBlueprintId: firstNonEmpty(
-        requestOptions.agentBlueprintId,
-        activity.recipient?.agenticAppBlueprintId
-      )
-    } : {},
-    ...firstNonEmpty(requestOptions.conversationId, activity.conversation?.id) ? {
-      conversationId: firstNonEmpty(
-        requestOptions.conversationId,
-        activity.conversation?.id
-      )
-    } : {},
-    // Mirrors Microsoft's A365 observability-hosting helper, which maps the
-    // Activity serviceUrl to microsoft.conversation.item.link.
-    ...firstNonEmpty(requestOptions.conversationItemLink, activity.serviceUrl) ? {
-      conversationItemLink: firstNonEmpty(
-        requestOptions.conversationItemLink,
-        activity.serviceUrl
-      )
-    } : {},
-    ...firstNonEmpty(
-      requestOptions.sessionId,
-      requestOptions.conversationId,
-      activity.conversation?.id
-    ) ? {
-      sessionId: firstNonEmpty(
-        requestOptions.sessionId,
-        requestOptions.conversationId,
-        activity.conversation?.id
-      )
-    } : {},
-    ...firstNonEmpty(requestOptions.channelName, activity.channelId) ? {
-      channelName: firstNonEmpty(
-        requestOptions.channelName,
-        activity.channelId
-      )
-    } : {},
-    ...firstNonEmpty(requestOptions.channelLink, activity.channelIdSubChannel) ? {
-      channelLink: firstNonEmpty(
-        requestOptions.channelLink,
-        activity.channelIdSubChannel
-      )
-    } : {},
-    ...firstNonEmpty(
-      requestOptions.userId,
-      activity.from?.aadObjectId,
-      activity.from?.id,
-      readPath(turnContext.identity, ["oid"]),
-      readPath(turnContext.identity, ["sub"])
-    ) ? {
-      userId: firstNonEmpty(
-        requestOptions.userId,
-        activity.from?.aadObjectId,
-        activity.from?.id,
-        readPath(turnContext.identity, ["oid"]),
-        readPath(turnContext.identity, ["sub"])
-      )
-    } : {},
-    ...firstNonEmpty(requestOptions.userName, activity.from?.name) ? {
-      userName: firstNonEmpty(requestOptions.userName, activity.from?.name)
-    } : {},
-    // Mirrors Microsoft's A365 observability-hosting helper, which treats
-    // agenticUserId as the caller UPN/email value.
-    ...firstNonEmpty(
-      requestOptions.userEmail,
-      activity.from?.email,
-      activity.from?.userPrincipalName,
-      activity.from?.agenticUserId,
-      readPath(channelData, ["from", "userPrincipalName"]),
-      readPath(turnContext.identity, ["preferred_username"]),
-      readPath(turnContext.identity, ["upn"])
-    ) ? {
-      userEmail: firstNonEmpty(
-        requestOptions.userEmail,
-        activity.from?.email,
-        activity.from?.userPrincipalName,
-        activity.from?.agenticUserId,
-        readPath(channelData, ["from", "userPrincipalName"]),
-        readPath(turnContext.identity, ["preferred_username"]),
-        readPath(turnContext.identity, ["upn"])
-      )
-    } : {},
-    ...firstNonEmpty(
+    )
+  );
+  setIfDefined(context, "conversationId", conversationId);
+  setIfDefined(context, "conversationItemLink", conversationItemLink);
+  setIfDefined(context, "sessionId", sessionId);
+  setIfDefined(
+    context,
+    "channelName",
+    firstNonEmpty(requestOptions.channelName, activity.channelId)
+  );
+  setIfDefined(
+    context,
+    "channelLink",
+    firstNonEmpty(requestOptions.channelLink, activity.channelIdSubChannel)
+  );
+  setIfDefined(context, "userId", userId);
+  setIfDefined(
+    context,
+    "userName",
+    firstNonEmpty(requestOptions.userName, activity.from?.name)
+  );
+  setIfDefined(context, "userEmail", userEmail);
+  setIfDefined(
+    context,
+    "callerAgentBlueprintId",
+    firstNonEmpty(
       requestOptions.callerAgentBlueprintId,
       activity.from?.agenticAppBlueprintId
-    ) ? {
-      callerAgentBlueprintId: firstNonEmpty(
-        requestOptions.callerAgentBlueprintId,
-        activity.from?.agenticAppBlueprintId
-      )
-    } : {},
-    ...requestOptions.serverAddress ? { serverAddress: requestOptions.serverAddress } : endpoint?.serverAddress ? { serverAddress: endpoint.serverAddress } : {},
-    ...requestOptions.serverPort !== void 0 ? { serverPort: requestOptions.serverPort } : endpoint?.serverPort !== void 0 ? { serverPort: endpoint.serverPort } : {}
-  };
+    )
+  );
+  setIfDefined(
+    context,
+    "serverAddress",
+    firstNonEmpty(requestOptions.serverAddress, endpoint?.serverAddress)
+  );
+  setIfDefined(
+    context,
+    "serverPort",
+    requestOptions.serverPort ?? endpoint?.serverPort
+  );
+  return context;
+}
+function setIfDefined(context, key, value) {
+  if (value !== void 0) {
+    context[key] = value;
+  }
 }
 
-// src/lifecycle.ts
-var OBSERVABILITY_PACKAGE = "@microsoft/agents-a365-observability";
+// src/runtime/per-request-config.ts
+var PER_REQUEST_ENV = {
+  enabled: "ENABLE_A365_OBSERVABILITY_PER_REQUEST_EXPORT",
+  maxTraces: "A365_PER_REQUEST_MAX_TRACES",
+  maxSpansPerTrace: "A365_PER_REQUEST_MAX_SPANS_PER_TRACE",
+  maxConcurrentExports: "A365_PER_REQUEST_MAX_CONCURRENT_EXPORTS",
+  flushGraceMs: "A365_PER_REQUEST_FLUSH_GRACE_MS",
+  maxTraceAgeMs: "A365_PER_REQUEST_MAX_TRACE_AGE_MS"
+};
+function applyA365PerRequestEnvironment(configuration, env = process.env) {
+  if (!configuration) {
+    return;
+  }
+  setEnv(env, PER_REQUEST_ENV.enabled, formatBoolean(configuration.enabled));
+  setEnv(env, PER_REQUEST_ENV.maxTraces, configuration.maxTraces);
+  setEnv(env, PER_REQUEST_ENV.maxSpansPerTrace, configuration.maxSpansPerTrace);
+  setEnv(
+    env,
+    PER_REQUEST_ENV.maxConcurrentExports,
+    configuration.maxConcurrentExports
+  );
+  setEnv(env, PER_REQUEST_ENV.flushGraceMs, configuration.flushGraceMs);
+  setEnv(env, PER_REQUEST_ENV.maxTraceAgeMs, configuration.maxTraceAgeMs);
+}
+function setEnv(env, key, value) {
+  if (value === void 0) {
+    return;
+  }
+  env[key] = String(value);
+}
+function formatBoolean(value) {
+  return value === void 0 ? void 0 : value ? "true" : "false";
+}
+
+// src/runtime/lifecycle.ts
 async function initA365Observability(options) {
+  applyA365PerRequestEnvironment(options.configuration?.perRequest);
   const module = await loadObservabilityModule(options);
   const configProvider = createConfigurationProvider(
     module,
@@ -385,19 +829,6 @@ async function updateA365ExportToken(token, options = {}) {
   const module = await loadObservabilityModule(options);
   return module.updateExportToken?.(token) ?? false;
 }
-async function loadObservabilityModule(options = {}) {
-  try {
-    if (options.getObservabilityModule) {
-      return await options.getObservabilityModule();
-    }
-    return await import(OBSERVABILITY_PACKAGE);
-  } catch (error) {
-    throw new A365ObservabilityModuleLoadError(
-      `Unable to load ${OBSERVABILITY_PACKAGE}. Install @microsoft/agents-a365-observability and @microsoft/agents-a365-runtime before using @cuylabs/agent-a365-observability.`,
-      { cause: error }
-    );
-  }
-}
 function createConfigurationProvider(module, configuration) {
   if (!configuration) {
     return void 0;
@@ -430,7 +861,7 @@ function normalizeCustomLogger(customLogger) {
   };
 }
 
-// src/turn-runner.ts
+// src/context/turn-runner.ts
 async function runWithA365TurnContext(turnContext, optionsOrFn, maybeFnOrRuntime, maybeRuntime) {
   const options = typeof optionsOrFn === "function" ? {} : optionsOrFn ?? {};
   const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFnOrRuntime;
@@ -444,14 +875,187 @@ async function runWithA365TurnContext(turnContext, optionsOrFn, maybeFnOrRuntime
     runtimeOptions
   );
 }
+
+// src/runtime/s2s.ts
+async function initA365S2SObservability(options) {
+  const env = resolveA365ObservabilityEnvironment(options.s2s?.env);
+  const tokenResolver = createA365S2STokenResolverFromEnv(options.s2s);
+  return await initA365Observability({
+    ...options,
+    tokenResolver,
+    exporterOptions: {
+      ...options.exporterOptions,
+      useS2SEndpoint: true
+    },
+    configuration: {
+      ...env.configuration,
+      ...options.configuration,
+      exporterEnabled: options.configuration?.exporterEnabled ?? env.configuration.exporterEnabled ?? true,
+      perRequest: {
+        ...env.configuration.perRequest,
+        ...options.configuration?.perRequest
+      }
+    }
+  });
+}
+
+// src/tracing/tracing-config.ts
+function createA365TracingConfig(options = {}) {
+  const spanAttributes = {
+    ...options.spanAttributes ?? {}
+  };
+  if (isNonEmpty(options.tenantId)) {
+    spanAttributes[A365_BAGGAGE_KEYS.tenantId] = options.tenantId.trim();
+  }
+  return {
+    ...isNonEmpty(options.agentId) ? { agentId: options.agentId.trim() } : {},
+    ...isNonEmpty(options.agentDescription) ? { agentDescription: options.agentDescription.trim() } : {},
+    ...isNonEmpty(options.agentVersion) ? { agentVersion: options.agentVersion.trim() } : {},
+    ...options.useGenAIOpenTelemetry !== void 0 ? { useGenAIOpenTelemetry: options.useGenAIOpenTelemetry } : {},
+    ...options.telemetryIntegrations ? { telemetryIntegrations: options.telemetryIntegrations } : {},
+    ...options.useGlobalTelemetryIntegrations !== void 0 ? {
+      useGlobalTelemetryIntegrations: options.useGlobalTelemetryIntegrations
+    } : {},
+    ...Object.keys(spanAttributes).length > 0 ? { spanAttributes } : {}
+  };
+}
+
+// src/tracing/trace-context.ts
+async function injectA365TraceContextToHeaders(headers = {}, options = {}) {
+  const module = await loadObservabilityModule(options);
+  if (!module.injectContextToHeaders) {
+    throw new Error(
+      "Agent 365 observability module does not export injectContextToHeaders."
+    );
+  }
+  return module.injectContextToHeaders(headers, options.context);
+}
+async function extractA365TraceContextFromHeaders(headers, options = {}) {
+  const module = await loadObservabilityModule(options);
+  if (!module.extractContextFromHeaders) {
+    throw new Error(
+      "Agent 365 observability module does not export extractContextFromHeaders."
+    );
+  }
+  return module.extractContextFromHeaders(headers, options.context);
+}
+async function runWithA365ExtractedTraceContext(headers, fn, options = {}) {
+  const module = await loadObservabilityModule(options);
+  if (!module.runWithExtractedTraceContext) {
+    throw new Error(
+      "Agent 365 observability module does not export runWithExtractedTraceContext."
+    );
+  }
+  return await module.runWithExtractedTraceContext(headers, fn);
+}
+async function runWithA365ParentSpanRef(parent, fn, options = {}) {
+  const module = await loadObservabilityModule(options);
+  if (!module.runWithParentSpanRef) {
+    throw new Error(
+      "Agent 365 observability module does not export runWithParentSpanRef."
+    );
+  }
+  return await module.runWithParentSpanRef(parent, fn);
+}
+async function createA365ContextWithParentSpanRef(baseContext, parent, options = {}) {
+  const module = await loadObservabilityModule(options);
+  if (!module.createContextWithParentSpanRef) {
+    throw new Error(
+      "Agent 365 observability module does not export createContextWithParentSpanRef."
+    );
+  }
+  return module.createContextWithParentSpanRef(baseContext, parent);
+}
+
+// src/tracing/output-scope.ts
+async function runWithA365OutputMessages(output, fn, options = {}) {
+  const module = await loadObservabilityModule(options);
+  if (!module.OutputScope) {
+    throw new Error(
+      "Agent 365 observability module does not export OutputScope."
+    );
+  }
+  const outputScope = module.OutputScope.start(
+    createOutputRequest(output),
+    { messages: output.messages },
+    createAgentDetails(output),
+    createUserDetails(output),
+    output.parentSpan ? { parentContext: output.parentSpan } : void 0
+  );
+  try {
+    return await fn();
+  } catch (error) {
+    outputScope.recordError?.(normalizeError(error));
+    throw error;
+  } finally {
+    outputScope.dispose();
+  }
+}
+function createOutputRequest(context) {
+  return {
+    conversationId: context.conversationId,
+    sessionId: context.sessionId,
+    channel: context.channelName || context.channelLink ? {
+      name: context.channelName,
+      description: context.channelLink
+    } : void 0
+  };
+}
+function createAgentDetails(context) {
+  return {
+    tenantId: context.tenantId,
+    agentId: context.agentId,
+    agentName: context.agentName,
+    agentDescription: context.agentDescription,
+    agentVersion: context.agentVersion,
+    agentPlatformId: context.agentPlatformId,
+    agentAUID: context.agentAuid,
+    agentEmail: context.agentEmail,
+    agentBlueprintId: context.agentBlueprintId
+  };
+}
+function createUserDetails(context) {
+  if (!context.userId && !context.userName && !context.userEmail) {
+    return void 0;
+  }
+  return {
+    tenantId: context.tenantId,
+    userId: context.userId,
+    userName: context.userName,
+    userEmail: context.userEmail
+  };
+}
+function normalizeError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(typeof error === "string" ? error : JSON.stringify(error));
+}
 export {
+  A365ObservabilityHostingModuleLoadError,
   A365ObservabilityModuleLoadError,
   A365_BAGGAGE_KEYS,
+  A365_EXPORTER_EVENT_NAMES,
+  applyA365PerRequestEnvironment,
   buildA365BaggagePairs,
   createA365ContextFromTurnContext,
+  createA365ContextWithParentSpanRef,
+  createA365OboTokenResolver,
+  createA365S2STokenResolver,
+  createA365S2STokenResolverFromEnv,
   createA365TracingConfig,
+  extractA365TraceContextFromHeaders,
   initA365Observability,
+  initA365S2SObservability,
+  injectA365TraceContextToHeaders,
+  invalidateA365OboObservabilityToken,
+  invalidateAllA365OboObservabilityTokens,
+  refreshA365OboObservabilityToken,
+  resolveA365ObservabilityEnvironment,
   runWithA365Context,
+  runWithA365ExtractedTraceContext,
+  runWithA365OutputMessages,
+  runWithA365ParentSpanRef,
   runWithA365TurnContext,
   updateA365ExportToken
 };