@cuylabs/agent-a365-observability 3.0.0 → 3.1.0

package/README.md

@@ -2,12 +2,19 @@
 
 Microsoft Agent 365 observability adapter for `@cuylabs/agent-core`.
 
-This package keeps the Microsoft-specific parts outside `agent-core`:
+This package connects agent-core's portable OpenTelemetry spans to Microsoft's
+Agent 365 observability SDK without putting Microsoft SDK types in agent-core.
 
-- starts Microsoft Agent 365 Observability
-- wires the Agent 365 exporter token resolver
-- wraps each request in Agent 365 baggage so spans include tenant and agent identity
-- returns a small tracing config fragment for stable agent metadata
+It does four things:
+
+- starts Microsoft Agent 365 Observability;
+- wires the Agent 365 exporter token resolver;
+- returns a small `createAgent({ tracing })` config fragment for stable agent
+  metadata;
+- wraps each request in Agent 365 baggage so spans include tenant, agent,
+  conversation, channel, and caller identity.
+
+For the deeper design, read [docs/README.md](./docs/README.md).
 
 ## Install
 
@@ -31,7 +38,7 @@ const observability = await initA365Observability({
   serviceVersion: "1.0.0",
   configuration: {
     exporterEnabled: true,
-    logLevel: "info|warn|error",
+    logLevel: "info",
   },
   tokenResolver: async (agentId, tenantId) => {
     return getObservabilityToken(agentId, tenantId);
@@ -52,7 +59,6 @@ await runWithA365Context(
   {
     tenantId: "tenant-123",
     agentId: "agent-456",
-    agentName: "email-assistant",
     conversationId: "conversation-789",
     sessionId: "session-789",
     channelName: "msteams",
@@ -79,7 +85,6 @@ await runWithA365TurnContext(
   context, // TurnContext from CloudAdapter
   {
     agentId: "agent-456",
-    agentName: "email-assistant",
     agentDescription: "Organizes email and calendar work",
     agentVersion: "1.0.0",
     sessionId,
@@ -100,7 +105,6 @@ const m365 = createM365ChannelAdapter({
   agent,
   a365Observability: {
     agentId: "agent-456",
-    agentName: "email-assistant",
     agentDescription: "Organizes email and calendar work",
     agentVersion: "1.0.0",
   },
@@ -112,13 +116,22 @@ startup so the Microsoft exporter and token resolver are registered.
 
 ## Shape
 
-Use `agent-core` for portable OpenTelemetry spans:
+The integration has three separate pieces:
+
+1. `initA365Observability(...)` starts Microsoft's exporter and baggage span
+   processor once at host startup.
+2. `createA365TracingConfig(...)` feeds agent-core's `createAgent({ tracing })`
+   contract.
+3. `runWithA365Context(...)` or `runWithA365TurnContext(...)` binds
+   per-request Agent 365 baggage before `agent.chat()` runs.
+
+Use agent-core for portable OpenTelemetry spans:
 
 - `invoke_agent` agent spans
 - `execute_tool` tool spans
 - AI SDK model spans nested under the agent turn
 
-Use this package for Agent 365-specific context:
+Use this package for Agent 365-specific context on those spans:
 
 - `microsoft.tenant.id`
 - `gen_ai.agent.id`
@@ -129,6 +142,18 @@ Use this package for Agent 365-specific context:
 
 For multi-tenant agents, prefer `runWithA365Context()` over static tracing attributes. Static attributes are useful for stable agent metadata; baggage is the right place for per-request tenant and conversation identity.
 
+Use `extraBaggage` only for additional dimensions that are not part of the
+standard Agent 365 identity set. Structured fields such as `tenantId`,
+`agentId`, `conversationId`, and `userId` win over conflicting `extraBaggage`
+keys.
+
+Microsoft's baggage processor does not overwrite span attributes that
+agent-core already set. In normal `@cuylabs/agent-channel-m365` usage this is
+fine because the channel's default session strategy uses the M365
+`conversation.id` as the agent-core session ID. If you use custom M365 session
+mapping, `gen_ai.conversation.id` reflects the custom agent-core session ID.
+See [docs/agent-core-otel.md](./docs/agent-core-otel.md) for details.
+
 ## Phoenix vs Agent 365
 
 Phoenix is a normal OTLP destination. You pass a span processor/exporter into `agent-core` tracing, and `agent-core` owns the tracer provider lifecycle for that example.
@@ -156,8 +181,42 @@ const agent = createAgent({
 
 Set `useGenAIOpenTelemetry: false` only when you intentionally want to use global AI SDK telemetry integrations or another model-span integration.
 
+## TurnContext Mapping
+
+`runWithA365TurnContext(...)` follows Microsoft's
+`agents-a365-observability-hosting` helper behavior for M365 Activity fields.
+Some mappings look surprising if read as generic Bot Framework fields:
+
+- `activity.serviceUrl` maps to `microsoft.conversation.item.link`.
+- `activity.recipient.role` maps to `gen_ai.agent.description`.
+- `activity.from.agenticUserId` maps to `user.email`.
+- `activity.channelIdSubChannel` maps to `microsoft.channel.link`.
+
+Pass explicit `runWithA365TurnContext` options when your host has more precise
+values, such as a real Teams message deep link for `conversationItemLink`.
+Caller-agent attributes and host-owned fields such as `agentEmail`,
+`agentPlatformId`, and `callerClientIp` are not inferred from TurnContext; pass
+them explicitly through `runWithA365Context()` or the TurnContext options when
+you need those dimensions.
+
 ## Exporter Modes
 
 For batch export, provide `tokenResolver` in `initA365Observability()`.
 
 For per-request export, pass `exportToken` to `runWithA365Context()` and enable per-request export in the Microsoft SDK configuration or environment.
+
+## v0 Limits
+
+v0 does not expose:
+
+- a separate Microsoft `OutputScope` span;
+- agent-to-agent HTTP trace propagation wrappers;
+- real-time threat protection or chat-history submission middleware.
+
+Those remain additive adapter features if an Agent 365 deployment needs them.
+
+## Examples
+
+Examples live in the repository under
+`packages/agent-a365-observability/examples`. They are monorepo-local reference
+files and are not shipped in the npm tarball.

package/dist/index.d.ts

@@ -14,19 +14,6 @@ type A365ObservabilityConfiguration = {
     logLevel?: string;
     authenticationScopes?: string[];
 };
-type InitA365ObservabilityOptions = {
-    serviceName: string;
-    serviceVersion?: string;
-    serviceNamespace?: string;
-    tokenResolver?: A365TokenResolver;
-    clusterCategory?: string;
-    exporterOptions?: Record<string, unknown>;
-    customLogger?: A365Logger;
-    configuration?: A365ObservabilityConfiguration;
-};
-type A365ObservabilityHandle = {
-    shutdown(): Promise<void>;
-};
 type A365RequestContext = {
     tenantId?: string;
     agentId?: string;
@@ -68,8 +55,11 @@ type A365RequestContext = {
 type A365ActivityAccountLike = {
     id?: string;
     name?: string;
+    role?: string;
     aadObjectId?: string;
     agenticAppId?: string;
+    agenticAppBlueprintId?: string;
+    agenticUserId?: string;
     tenantId?: string;
     userPrincipalName?: string;
     email?: string;
@@ -79,6 +69,7 @@ type A365ActivityLike = {
     id?: string;
     serviceUrl?: string;
     channelId?: string;
+    channelIdSubChannel?: string;
     from?: A365ActivityAccountLike;
     recipient?: A365ActivityAccountLike;
     conversation?: {
@@ -89,6 +80,9 @@ type A365ActivityLike = {
         [key: string]: unknown;
     };
     channelData?: unknown;
+    isAgenticRequest?: () => boolean;
+    getAgenticInstanceId?: () => string | undefined;
+    getAgenticTenantId?: () => string | undefined;
     [key: string]: unknown;
 };
 type A365TurnContextLike = {
@@ -103,8 +97,8 @@ type A365TurnContextOptions = Omit<A365RequestContext, "extraBaggage"> & {
      */
     serviceUrl?: string;
     /**
-     * Use `activity.recipient.id` as `agentId` when `agentId` and
-     * `activity.recipient.agenticAppId` are both unavailable.
+     * Use `activity.recipient.id` as `agentId` when `agentId` and Agent 365
+     * activity identity helpers are unavailable.
      *
      * Keep this disabled when the recipient ID is only a Bot Framework ID and not
      * the Agent 365 app ID.
@@ -135,6 +129,35 @@ type A365TracingConfig = {
     useGlobalTelemetryIntegrations?: boolean;
     spanAttributes?: Record<string, SpanAttributeValue>;
 };
+
+type A365ObservabilityModuleLoader = () => Promise<unknown>;
+type A365ObservabilityRuntimeOptions = {
+    /**
+     * Test seam for loading `@microsoft/agents-a365-observability`.
+     *
+     * Production code normally leaves this unset so the package is loaded lazily
+     * only when observability is used.
+     */
+    getObservabilityModule?: A365ObservabilityModuleLoader;
+};
+type InitA365ObservabilityOptions = A365ObservabilityRuntimeOptions & {
+    serviceName: string;
+    serviceVersion?: string;
+    serviceNamespace?: string;
+    tokenResolver?: A365TokenResolver;
+    clusterCategory?: string;
+    exporterOptions?: Record<string, unknown>;
+    customLogger?: A365Logger;
+    configuration?: A365ObservabilityConfiguration;
+};
+type A365ObservabilityHandle = {
+    shutdown(): Promise<void>;
+};
+
+declare class A365ObservabilityModuleLoadError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+
 declare const A365_BAGGAGE_KEYS: {
     readonly tenantId: "microsoft.tenant.id";
     readonly agentId: "gen_ai.agent.id";
@@ -166,13 +189,18 @@ declare const A365_BAGGAGE_KEYS: {
     readonly serverAddress: "server.address";
     readonly serverPort: "server.port";
 };
-declare function createA365TracingConfig(options?: A365TracingConfigOptions): A365TracingConfig;
+
 declare function buildA365BaggagePairs(context: A365RequestContext): Record<string, string>;
+
+declare function createA365TracingConfig(options?: A365TracingConfigOptions): A365TracingConfig;
+
 declare function createA365ContextFromTurnContext(turnContext: A365TurnContextLike, options?: A365TurnContextOptions): A365RequestContext;
-declare function runWithA365TurnContext<T>(turnContext: A365TurnContextLike, fn: () => T): Promise<Awaited<T>>;
-declare function runWithA365TurnContext<T>(turnContext: A365TurnContextLike, options: A365TurnContextOptions, fn: () => T): Promise<Awaited<T>>;
+
+declare function runWithA365TurnContext<T>(turnContext: A365TurnContextLike, fn: () => T, runtimeOptions?: A365ObservabilityRuntimeOptions): Promise<Awaited<T>>;
+declare function runWithA365TurnContext<T>(turnContext: A365TurnContextLike, options: A365TurnContextOptions, fn: () => T, runtimeOptions?: A365ObservabilityRuntimeOptions): Promise<Awaited<T>>;
+
 declare function initA365Observability(options: InitA365ObservabilityOptions): Promise<A365ObservabilityHandle>;
-declare function runWithA365Context<T>(requestContext: A365RequestContext, fn: () => T): Promise<Awaited<T>>;
-declare function updateA365ExportToken(token: string): Promise<boolean>;
+declare function runWithA365Context<T>(requestContext: A365RequestContext, fn: () => T, options?: A365ObservabilityRuntimeOptions): Promise<Awaited<T>>;
+declare function updateA365ExportToken(token: string, options?: A365ObservabilityRuntimeOptions): Promise<boolean>;
 
-export { type A365ActivityAccountLike, type A365ActivityLike, type A365Logger, type A365ObservabilityConfiguration, type A365ObservabilityHandle, type A365RequestContext, type A365TokenResolver, type A365TracingConfig, type A365TracingConfigOptions, type A365TurnContextLike, type A365TurnContextOptions, A365_BAGGAGE_KEYS, type InitA365ObservabilityOptions, type SpanAttributeValue, buildA365BaggagePairs, createA365ContextFromTurnContext, createA365TracingConfig, initA365Observability, runWithA365Context, runWithA365TurnContext, updateA365ExportToken };
+export { type A365ActivityAccountLike, type A365ActivityLike, type A365Logger, type A365ObservabilityConfiguration, type A365ObservabilityHandle, A365ObservabilityModuleLoadError, type A365ObservabilityModuleLoader, type A365ObservabilityRuntimeOptions, type A365RequestContext, type A365TokenResolver, type A365TracingConfig, type A365TracingConfigOptions, type A365TurnContextLike, type A365TurnContextOptions, A365_BAGGAGE_KEYS, type InitA365ObservabilityOptions, type SpanAttributeValue, buildA365BaggagePairs, createA365ContextFromTurnContext, createA365TracingConfig, initA365Observability, runWithA365Context, runWithA365TurnContext, updateA365ExportToken };

package/dist/index.js

@@ -1,4 +1,12 @@
-// src/index.ts
+// src/errors.ts
+var A365ObservabilityModuleLoadError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "A365ObservabilityModuleLoadError";
+  }
+};
+
+// src/baggage-keys.ts
 var A365_BAGGAGE_KEYS = {
   tenantId: "microsoft.tenant.id",
   agentId: "gen_ai.agent.id",
@@ -30,28 +38,89 @@ var A365_BAGGAGE_KEYS = {
   serverAddress: "server.address",
   serverPort: "server.port"
 };
-var OBSERVABILITY_PACKAGE = "@microsoft/agents-a365-observability";
-function createA365TracingConfig(options = {}) {
-  const spanAttributes = {
-    ...options.spanAttributes ?? {}
-  };
-  if (isNonEmpty(options.tenantId)) {
-    spanAttributes[A365_BAGGAGE_KEYS.tenantId] = options.tenantId.trim();
+
+// src/internal/parsing.ts
+function setPair(target, key, value) {
+  if (value === null || value === void 0) {
+    return;
   }
-  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 } : {}
-  };
+  const stringValue = String(value).trim();
+  if (!stringValue) {
+    return;
+  }
+  target[key] = stringValue;
+}
+function isNonEmpty(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    if (value === null || value === void 0) {
+      continue;
+    }
+    const stringValue = String(value).trim();
+    if (stringValue) {
+      return stringValue;
+    }
+  }
+  return void 0;
 }
+function readPath(value, path) {
+  let current = value;
+  for (const segment of path) {
+    if (!isRecord(current)) {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return firstNonEmpty(
+    typeof current === "string" || typeof current === "number" || typeof current === "boolean" ? current : void 0
+  );
+}
+function parseServiceEndpoint(serviceUrl) {
+  if (!isNonEmpty(serviceUrl)) {
+    return void 0;
+  }
+  try {
+    const url = new URL(serviceUrl);
+    return {
+      serverAddress: url.hostname,
+      ...url.port ? { serverPort: Number(url.port) } : {}
+    };
+  } catch {
+    return void 0;
+  }
+}
+function callOptionalStringMethod(method) {
+  if (!method) {
+    return void 0;
+  }
+  try {
+    return firstNonEmpty(method());
+  } catch {
+    return void 0;
+  }
+}
+function callOptionalBooleanMethod(method) {
+  if (!method) {
+    return false;
+  }
+  try {
+    return method() === true;
+  } catch {
+    return false;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/baggage.ts
 function buildA365BaggagePairs(context) {
   const pairs = {};
+  for (const [key, value] of Object.entries(context.extraBaggage ?? {})) {
+    setPair(pairs, key, value);
+  }
   setPair(pairs, A365_BAGGAGE_KEYS.tenantId, context.tenantId);
   setPair(pairs, A365_BAGGAGE_KEYS.agentId, context.agentId);
   setPair(pairs, A365_BAGGAGE_KEYS.agentName, context.agentName);
@@ -101,23 +170,46 @@ function buildA365BaggagePairs(context) {
   setPair(pairs, A365_BAGGAGE_KEYS.serviceName, context.serviceName);
   setPair(pairs, A365_BAGGAGE_KEYS.serverAddress, context.serverAddress);
   setPair(pairs, A365_BAGGAGE_KEYS.serverPort, context.serverPort);
-  for (const [key, value] of Object.entries(context.extraBaggage ?? {})) {
-    setPair(pairs, key, value);
-  }
   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
 function createA365ContextFromTurnContext(turnContext, options = {}) {
   const { serviceUrl, useRecipientIdAsAgentId, ...requestOptions } = options;
   const activity = turnContext.activity ?? {};
   const channelData = activity.channelData;
   const endpoint = parseServiceEndpoint(serviceUrl ?? activity.serviceUrl);
+  const isAgenticRequest = callOptionalBooleanMethod(activity.isAgenticRequest);
   const agentId = firstNonEmpty(
     requestOptions.agentId,
+    isAgenticRequest ? callOptionalStringMethod(activity.getAgenticInstanceId) : void 0,
     activity.recipient?.agenticAppId,
     useRecipientIdAsAgentId ? activity.recipient?.id : void 0
   );
   const tenantId = firstNonEmpty(
     requestOptions.tenantId,
+    callOptionalStringMethod(activity.getAgenticTenantId),
     activity.recipient?.tenantId,
     activity.conversation?.tenantId,
     readPath(channelData, ["tenant", "id"]),
@@ -133,12 +225,43 @@ function createA365ContextFromTurnContext(turnContext, options = {}) {
         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(
+      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,
@@ -156,6 +279,12 @@ function createA365ContextFromTurnContext(turnContext, options = {}) {
         activity.channelId
       )
     } : {},
+    ...firstNonEmpty(requestOptions.channelLink, activity.channelIdSubChannel) ? {
+      channelLink: firstNonEmpty(
+        requestOptions.channelLink,
+        activity.channelIdSubChannel
+      )
+    } : {},
     ...firstNonEmpty(
       requestOptions.userId,
       activity.from?.aadObjectId,
@@ -174,10 +303,13 @@ function createA365ContextFromTurnContext(turnContext, options = {}) {
     ...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"])
@@ -186,28 +318,30 @@ function createA365ContextFromTurnContext(turnContext, options = {}) {
         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(
+      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 } : {}
   };
 }
-async function runWithA365TurnContext(turnContext, optionsOrFn, maybeFn) {
-  const options = typeof optionsOrFn === "function" ? {} : optionsOrFn ?? {};
-  const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
-  if (!fn) {
-    throw new Error("runWithA365TurnContext requires a callback.");
-  }
-  return await runWithA365Context(
-    createA365ContextFromTurnContext(turnContext, options),
-    fn
-  );
-}
+
+// src/lifecycle.ts
+var OBSERVABILITY_PACKAGE = "@microsoft/agents-a365-observability";
 async function initA365Observability(options) {
-  const module = await loadObservabilityModule();
+  const module = await loadObservabilityModule(options);
   const configProvider = createConfigurationProvider(
     module,
     options.configuration
@@ -227,7 +361,7 @@ async function initA365Observability(options) {
       builder2.withExporterOptions?.(options.exporterOptions);
     }
     if (options.customLogger) {
-      builder2.withCustomLogger?.(options.customLogger);
+      builder2.withCustomLogger?.(normalizeCustomLogger(options.customLogger));
     }
     if (configProvider) {
       builder2.withConfigurationProvider?.(configProvider);
@@ -238,8 +372,8 @@ async function initA365Observability(options) {
     shutdown: () => module.ObservabilityManager.shutdown()
   };
 }
-async function runWithA365Context(requestContext, fn) {
-  const module = await loadObservabilityModule();
+async function runWithA365Context(requestContext, fn, options = {}) {
+  const module = await loadObservabilityModule(options);
   const runWithBaggage = () => {
     const scope = new module.BaggageBuilder().setPairs(buildA365BaggagePairs(requestContext)).build();
     return scope.run(fn);
@@ -247,15 +381,18 @@ async function runWithA365Context(requestContext, fn) {
   const result = requestContext.exportToken && module.runWithExportToken ? module.runWithExportToken(requestContext.exportToken, runWithBaggage) : runWithBaggage();
   return await result;
 }
-async function updateA365ExportToken(token) {
-  const module = await loadObservabilityModule();
+async function updateA365ExportToken(token, options = {}) {
+  const module = await loadObservabilityModule(options);
   return module.updateExportToken?.(token) ?? false;
 }
-async function loadObservabilityModule() {
+async function loadObservabilityModule(options = {}) {
   try {
+    if (options.getObservabilityModule) {
+      return await options.getObservabilityModule();
+    }
     return await import(OBSERVABILITY_PACKAGE);
   } catch (error) {
-    throw new 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 }
     );
@@ -285,61 +422,30 @@ function createConfigurationProvider(module, configuration) {
     getConfiguration: () => new module.ObservabilityConfiguration(overrides)
   };
 }
-function setPair(target, key, value) {
-  if (value === null || value === void 0) {
-    return;
-  }
-  const stringValue = String(value).trim();
-  if (!stringValue) {
-    return;
-  }
-  target[key] = stringValue;
-}
-function isNonEmpty(value) {
-  return typeof value === "string" && value.trim().length > 0;
-}
-function firstNonEmpty(...values) {
-  for (const value of values) {
-    if (value === null || value === void 0) {
-      continue;
-    }
-    const stringValue = String(value).trim();
-    if (stringValue) {
-      return stringValue;
-    }
-  }
-  return void 0;
+function normalizeCustomLogger(customLogger) {
+  return {
+    ...customLogger,
+    event: customLogger.event ?? (() => {
+    })
+  };
 }
-function readPath(value, path) {
-  let current = value;
-  for (const segment of path) {
-    if (!isRecord(current)) {
-      return void 0;
-    }
-    current = current[segment];
+
+// src/turn-runner.ts
+async function runWithA365TurnContext(turnContext, optionsOrFn, maybeFnOrRuntime, maybeRuntime) {
+  const options = typeof optionsOrFn === "function" ? {} : optionsOrFn ?? {};
+  const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFnOrRuntime;
+  const runtimeOptions = typeof optionsOrFn === "function" ? typeof maybeFnOrRuntime === "function" ? void 0 : maybeFnOrRuntime : maybeRuntime;
+  if (typeof fn !== "function") {
+    throw new Error("runWithA365TurnContext requires a callback.");
   }
-  return firstNonEmpty(
-    typeof current === "string" || typeof current === "number" || typeof current === "boolean" ? current : void 0
+  return await runWithA365Context(
+    createA365ContextFromTurnContext(turnContext, options),
+    fn,
+    runtimeOptions
   );
 }
-function parseServiceEndpoint(serviceUrl) {
-  if (!isNonEmpty(serviceUrl)) {
-    return void 0;
-  }
-  try {
-    const url = new URL(serviceUrl);
-    return {
-      serverAddress: url.hostname,
-      ...url.port ? { serverPort: Number(url.port) } : {}
-    };
-  } catch {
-    return void 0;
-  }
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
-}
 export {
+  A365ObservabilityModuleLoadError,
   A365_BAGGAGE_KEYS,
   buildA365BaggagePairs,
   createA365ContextFromTurnContext,

package/docs/README.md

@@ -0,0 +1,27 @@
+# Agent 365 Observability Docs
+
+`@cuylabs/agent-a365-observability` connects agent-core's portable
+OpenTelemetry spans to Microsoft's Agent 365 observability SDK.
+
+Read these files in this order:
+
+1. [architecture.md](./architecture.md)
+   Explains the layer split and why this package exists outside agent-core.
+2. [agent-core-otel.md](./agent-core-otel.md)
+   Explains what agent-core emits and how this package feeds that telemetry.
+3. [microsoft-a365-observability.md](./microsoft-a365-observability.md)
+   Explains what Microsoft's SDK owns: exporter startup, baggage enrichment,
+   export tokens, and trace propagation utilities.
+4. [lifecycle-and-limits.md](./lifecycle-and-limits.md)
+   Explains startup order, per-request baggage, session/conversation behavior,
+   and v0 limits.
+
+The short version:
+
+- agent-core owns platform-neutral spans for agent turns, tools, and model
+  calls.
+- `agent-channel-m365` owns Activity ingress and turn wrapping for M365 hosts.
+- Microsoft's Agent 365 observability SDK owns exporter registration and
+  baggage-to-span enrichment.
+- this package starts Microsoft observability and wraps each agent turn with
+  the Agent 365 baggage that Microsoft expects.

package/docs/agent-core-otel.md

@@ -0,0 +1,68 @@
+# Agent-Core OpenTelemetry Integration
+
+This package builds on agent-core's existing tracing support. It does not
+replace agent-core telemetry and it does not create agent-core spans itself.
+
+## What Agent-Core Emits
+
+agent-core's OpenTelemetry middleware emits:
+
+- `invoke_agent` spans for agent turns;
+- `execute_tool` spans for tool calls;
+- AI SDK GenAI spans for model calls when AI SDK telemetry is enabled.
+
+The root agent span includes common GenAI attributes such as:
+
+- `gen_ai.operation.name`
+- `gen_ai.agent.name`
+- `gen_ai.agent.id`
+- `gen_ai.agent.description`
+- `gen_ai.agent.version`
+- `gen_ai.input.messages`
+- `gen_ai.output.messages`
+- `gen_ai.usage.input_tokens`
+- `gen_ai.usage.output_tokens`
+
+`createA365TracingConfig(...)` returns the agent-core tracing fragment for
+stable agent metadata. Per-request metadata belongs in baggage via
+`runWithA365Context(...)`.
+
+## What This Package Adds
+
+This package wraps the turn in Agent 365 baggage before agent-core starts its
+spans. Microsoft's baggage processor then copies that baggage into span
+attributes.
+
+Common copied attributes include:
+
+- `microsoft.tenant.id`
+- `microsoft.session.id`
+- `microsoft.a365.agent.blueprint.id`
+- `microsoft.channel.name`
+- `microsoft.channel.link`
+- `user.id`
+- `user.name`
+- `user.email`
+
+For `invoke_agent` spans, Microsoft's processor also copies Agent 365
+agent/caller dimensions when agent-core has not already set the same key.
+
+## Attribute Precedence
+
+Microsoft's baggage processor does not overwrite attributes that already exist
+on a span.
+
+That matters for a few keys:
+
+- agent-core always sets `gen_ai.agent.name` from `createAgent({ name })`;
+- agent-core sets `gen_ai.conversation.id` from the agent-core session ID;
+- `createA365TracingConfig({ agentId, agentDescription, agentVersion })`
+  causes agent-core to set those keys before baggage is copied.
+
+For normal `@cuylabs/agent-channel-m365` usage this is fine because the default
+session strategy uses the M365 `conversation.id` as the agent-core session ID.
+If you use a custom M365 session mapping, `gen_ai.conversation.id` will reflect
+the custom agent-core session ID, not the original M365 conversation ID.
+
+Use `microsoft.session.id` for the Agent 365 session dimension and keep custom
+session mapping in mind when analyzing exported spans.

package/docs/architecture.md

@@ -0,0 +1,57 @@
+# Architecture
+
+This package exists to keep agent-core platform-neutral while allowing an
+M365-hosted agent to export Agent 365-shaped telemetry.
+
+## Layer Split
+
+| Layer                                  | Owns                                                                                                            | Does not own                                                    |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `@cuylabs/agent-core`                  | Agent runtime, model loop, tool execution, OpenTelemetry span emission                                          | Microsoft exporter startup, Agent 365 baggage, token resolution |
+| `@cuylabs/agent-channel-m365`          | M365 Activity/CloudAdapter ingress, session mapping, optional per-turn observability wrapper                    | Exporter lifecycle or OpenTelemetry provider registration       |
+| `@microsoft/agents-a365-observability` | Agent 365 exporter, baggage builder, baggage span processor, per-request export token context                   | agent-core tracing config or channel message handling           |
+| `@cuylabs/agent-a365-observability`    | Glue that starts Microsoft observability, produces agent-core tracing config, and wraps turns with A365 baggage | Model provider, chat transport, Microsoft SDK internals         |
+
+The important boundary is that agent-core never imports Microsoft SDK types.
+Microsoft-specific telemetry behavior lives in this adapter and the Microsoft
+SDK.
+
+## Runtime Flow
+
+At startup:
+
+1. the host calls `initA365Observability(...)`;
+2. this package loads Microsoft's observability SDK;
+3. Microsoft registers its OpenTelemetry provider/export processor;
+4. Microsoft registers a span processor that copies baggage into span
+   attributes.
+
+Per agent:
+
+1. the host calls `createAgent({ tracing: createA365TracingConfig(...) })`;
+2. agent-core installs its normal OpenTelemetry middleware;
+3. agent-core emits `invoke_agent`, `execute_tool`, and AI SDK model spans.
+
+Per turn:
+
+1. the host or M365 channel calls `runWithA365Context(...)` or
+   `runWithA365TurnContext(...)`;
+2. this package builds Agent 365 baggage from tenant, agent, conversation,
+   channel, and caller identity;
+3. agent-core runs the turn inside that baggage scope;
+4. Microsoft's span processor copies relevant baggage onto each span at span
+   start;
+5. Microsoft's exporter sends the final span shape to Agent 365.
+
+## Why Not Put This In Agent-Core?
+
+Agent 365 observability has Microsoft-specific concepts:
+
+- Agent 365 tenant and agent identity baggage;
+- Microsoft exporter token resolution;
+- Microsoft per-request export token context;
+- M365 `TurnContext` identity helpers;
+- Agent 365 trace propagation utilities.
+
+Putting those in agent-core would make core platform-specific. This adapter
+keeps the runtime portable while still supporting Agent 365 deployment.

package/docs/lifecycle-and-limits.md

@@ -0,0 +1,118 @@
+# Lifecycle And Limits
+
+This package is intentionally small for v0. It initializes Microsoft
+observability once, then wraps each turn with Agent 365 baggage.
+
+## Startup Order
+
+Call `initA365Observability(...)` during host startup, before the first
+agent-core turn emits spans.
+
+```ts
+const observability = await initA365Observability({
+  serviceName: "email-agent-service",
+  tokenResolver: async (agentId, tenantId) =>
+    getObservabilityToken(agentId, tenantId),
+});
+```
+
+The returned handle shuts down the Microsoft observability manager:
+
+```ts
+await observability.shutdown();
+```
+
+Microsoft's current `ObservabilityManager` API exposes shutdown, not a separate
+public flush method. When Microsoft's builder creates its own OpenTelemetry
+`NodeSDK`, `shutdown()` delegates to that SDK. When Microsoft's builder detects
+an existing global tracer provider, it attaches its processors to that provider
+and does not own provider shutdown; the host that created the global provider is
+responsible for flushing or shutting it down.
+
+## Per-Request Baggage
+
+Use `runWithA365Context(...)` when you already have tenant, agent, channel, and
+caller identity:
+
+```ts
+await runWithA365Context(
+  {
+    tenantId,
+    agentId,
+    sessionId,
+    conversationId,
+    channelName: "msteams",
+  },
+  () => agent.send(sessionId, message),
+);
+```
+
+Use `runWithA365TurnContext(...)` when you have a Microsoft `TurnContext`.
+The helper reads common Activity fields and optional Agent 365 Activity methods
+such as `getAgenticTenantId()` and `getAgenticInstanceId()`.
+
+## Extra Baggage
+
+Use `extraBaggage` for additional span attributes that are not part of the
+standard Agent 365 baggage set:
+
+```ts
+await runWithA365Context(
+  {
+    tenantId,
+    agentId,
+    extraBaggage: {
+      "deployment.environment.name": "prod",
+      "custom.routing.bucket": "soc",
+    },
+  },
+  () => agent.send(sessionId, message),
+);
+```
+
+Structured Agent 365 fields win over `extraBaggage` conflicts. For example, if
+`tenantId` is set and `extraBaggage` also contains `microsoft.tenant.id`, the
+structured `tenantId` value is used. This prevents ad hoc baggage from
+accidentally or deliberately spoofing core tenant, agent, conversation, and user
+identity dimensions.
+
+## Per-Request Export Tokens
+
+Batch export usually uses `tokenResolver` from `initA365Observability(...)`.
+
+For Microsoft's per-request export mode, pass `exportToken` in the request
+context:
+
+```ts
+await runWithA365Context(
+  {
+    tenantId,
+    agentId,
+    exportToken,
+  },
+  () => agent.send(sessionId, message),
+);
+```
+
+## M365 Session Mapping
+
+`@cuylabs/agent-channel-m365` defaults to using M365 `conversation.id` as the
+agent-core session ID. That keeps agent-core's `gen_ai.conversation.id` aligned
+with Agent 365 conversation identity.
+
+If you use a custom session mapping, agent-core will set
+`gen_ai.conversation.id` to your custom session ID. Microsoft's baggage
+processor will not overwrite that attribute with Agent 365 baggage. This is a
+known v0 limit and should be considered when analyzing spans.
+
+## v0 Limits
+
+v0 does not expose:
+
+- a separate Microsoft `OutputScope` span;
+- agent-to-agent HTTP trace propagation wrappers;
+- custom span processors for overriding agent-core attributes;
+- real-time threat protection or chat-history submission middleware.
+
+Those features are additive and should be introduced only when a real Agent 365
+deployment needs them.

package/docs/microsoft-a365-observability.md

@@ -0,0 +1,86 @@
+# Microsoft Agent 365 Observability SDK
+
+This package delegates exporter and baggage behavior to Microsoft's
+`@microsoft/agents-a365-observability` SDK.
+
+## What Microsoft Owns
+
+Microsoft's SDK owns:
+
+- OpenTelemetry provider/export processor registration;
+- the Agent 365 span exporter;
+- batch export and per-request export token modes;
+- `BaggageBuilder` and `BaggageScope`;
+- the span processor that copies baggage into span attributes;
+- Agent 365 scope classes such as `InvokeAgentScope`, `ExecuteToolScope`,
+  `InferenceScope`, and `OutputScope`;
+- trace propagation helpers for agent-to-agent HTTP calls.
+
+This package intentionally does not reimplement those pieces.
+
+## Why This Package Still Exists
+
+Microsoft's SDK is platform-level observability infrastructure. It does not
+know how a cuylabs agent is configured or how agent-core emits spans.
+
+This package answers the integration question:
+
+> How does an agent-core agent participate in Microsoft Agent 365
+> observability without making agent-core depend on Microsoft SDK types?
+
+The answer is:
+
+1. initialize Microsoft's SDK once at host startup;
+2. pass stable tracing config into `createAgent()`;
+3. wrap each request with Agent 365 baggage before `agent.chat()` runs.
+
+## Scope Classes
+
+Microsoft exposes explicit scope classes for several span shapes. agent-core
+already emits equivalent agent and tool spans, and AI SDK telemetry covers model
+spans.
+
+The main shape difference is `OutputScope`, which creates a separate
+`output_messages` span. agent-core currently records output messages on the
+`invoke_agent` span through `gen_ai.output.messages`.
+
+The v0 adapter does not emit a separate `OutputScope`. If a future Agent 365
+dashboard requires the separate `output_messages` span, this should be added as
+an adapter feature or an agent-core telemetry extension point, not by importing
+Microsoft scope classes into agent-core.
+
+## Trace Propagation
+
+Microsoft also exports helpers such as:
+
+- `runWithParentSpanRef`
+- `extractContextFromHeaders`
+- `injectContextToHeaders`
+
+Those are useful for agent-to-agent HTTP trace continuation. v0 does not wrap
+them. Consumers that need A2A trace propagation can import them directly from
+Microsoft's SDK until a real cuylabs integration requires a first-class helper.
+
+## TurnContext Mapping Parity
+
+`runWithA365TurnContext(...)` intentionally mirrors Microsoft's
+`agents-a365-observability-hosting` TurnContext helpers for fields that can
+look surprising outside the Agent 365 activity model:
+
+- `activity.serviceUrl` maps to `microsoft.conversation.item.link`.
+- `activity.recipient.role` maps to `gen_ai.agent.description`.
+- `activity.from.agenticUserId` maps to `user.email`.
+- `activity.channelIdSubChannel` maps to `microsoft.channel.link`.
+
+Those mappings come from Microsoft's hosting helper behavior, not from generic
+Bot Framework naming. Prefer explicit options when your host has more precise
+values, for example a real Teams message deep link for
+`conversationItemLink`.
+
+Caller-agent attributes and some host-owned agent attributes are not
+extractable from a generic TurnContext shape. Fields such as `agentEmail`,
+`agentPlatformId`, `sessionDescription`, `callerClientIp`, `callerAgentId`,
+`callerAgentName`, `callerAgentAuid`, `callerAgentEmail`,
+`callerAgentPlatformId`, and `callerAgentVersion` are only populated when the
+host passes them explicitly through `runWithA365Context(...)` or the options
+argument to `runWithA365TurnContext(...)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-a365-observability",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Microsoft Agent 365 observability adapter for @cuylabs/agent-core",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,18 +14,19 @@
   },
   "files": [
     "dist",
-    "examples",
+    "docs",
     "README.md"
   ],
   "devDependencies": {
     "@ai-sdk/openai": "4.0.0-beta.38",
     "@types/node": "^22.0.0",
     "ai": "7.0.0-beta.111",
+    "dotenv": "^17.2.3",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
     "vitest": "^4.0.18",
     "zod": "^3.25.76 || ^4.1.8",
-    "@cuylabs/agent-core": "^3.0.0"
+    "@cuylabs/agent-core": "^3.1.0"
   },
   "peerDependencies": {
     "@cuylabs/agent-core": "^3.0.0",

package/examples/01-a365-observability.ts

@@ -1,115 +0,0 @@
-/**
- * 01 — Microsoft Agent 365 Observability
- *
- * Similar goal to agent-core's Phoenix/Zipkin examples, but A365 owns the
- * OpenTelemetry exporter setup and requires per-request tenant/agent identity
- * through baggage.
- *
- * Simplified span hierarchy:
- *
- *   invoke_agent calculator-bot          (agent-core turn span)
- *     ├── invoke_agent gpt-4o-mini       (AI SDK v7 / @ai-sdk/otel)
- *     │    └── chat gpt-4o-mini          (model request)
- *     ├── execute_tool calculator        (agent-core tool span)
- *     └── invoke_agent gpt-4o-mini       (AI SDK final model span)
- *
- * Required env:
- *   ENABLE_A365_OBSERVABILITY_EXPORTER=true
- *   A365_AGENT_ID=...
- *   A365_TENANT_ID=...
- *   A365_OBSERVABILITY_TOKEN=...         # demo token resolver only
- *
- * Run:
- *   npx tsx examples/01-a365-observability.ts
- */
-
-import {
-  createA365TracingConfig,
-  initA365Observability,
-  runWithA365Context,
-} from "@cuylabs/agent-a365-observability";
-import { createAgent, Tool } from "@cuylabs/agent-core";
-import { openai } from "@ai-sdk/openai";
-import { z } from "zod";
-
-const agentId = requiredEnv("A365_AGENT_ID");
-const tenantId = requiredEnv("A365_TENANT_ID");
-
-const observability = await initA365Observability({
-  serviceName: "agent-a365-observability-example",
-  serviceVersion: "1.0.0",
-  configuration: {
-    exporterEnabled: process.env.ENABLE_A365_OBSERVABILITY_EXPORTER === "true",
-    logLevel: process.env.A365_OBSERVABILITY_LOG_LEVEL ?? "info|warn|error",
-  },
-  tokenResolver: async () => requiredEnv("A365_OBSERVABILITY_TOKEN"),
-});
-
-const calculator = Tool.define("calculator", {
-  description: "Evaluate a math expression",
-  parameters: z.object({
-    expression: z.string().describe("Expression like '2 + 3 * 4'"),
-  }),
-  execute: async ({ expression }) => ({
-    title: "Calculator",
-    output: String(eval(expression)), // demo only
-  }),
-});
-
-const agent = createAgent({
-  name: "calculator-bot",
-  model: openai("gpt-4o-mini"),
-  tools: [calculator],
-  systemPrompt:
-    "You have a calculator tool. Use it to answer math questions. Be concise.",
-  tracing: createA365TracingConfig({
-    agentId,
-    agentDescription: "Calculator example for Microsoft Agent 365 Observability",
-    agentVersion: "1.0.0",
-  }),
-});
-
-try {
-  await runWithA365Context(
-    {
-      tenantId,
-      agentId,
-      agentName: "calculator-bot",
-      agentDescription:
-        "Calculator example for Microsoft Agent 365 Observability",
-      agentVersion: "1.0.0",
-      sessionId: "demo",
-      conversationId: "demo",
-      channelName: "local",
-    },
-    async () => {
-      for await (const event of agent.chat(
-        "demo",
-        "What is 123 * 456 + 789?",
-      )) {
-        if (event.type === "text-delta") {
-          process.stdout.write(event.text);
-        }
-        if (event.type === "tool-start") {
-          console.log(`\n${event.toolName}(${JSON.stringify(event.input)})`);
-        }
-        if (event.type === "tool-result") {
-          console.log(`   ${event.result}`);
-        }
-      }
-    },
-  );
-
-  console.log("\nSpans emitted with Agent 365 baggage.");
-} finally {
-  await agent.close();
-  await observability.shutdown();
-}
-
-function requiredEnv(name: string): string {
-  const value = process.env[name];
-  if (!value) {
-    throw new Error(`${name} is required`);
-  }
-  return value;
-}