@cuylabs/agent-a365-observability 4.5.0 → 4.6.0

package/docs/README.md

@@ -12,7 +12,13 @@ Read these files in this order:
 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)
+4. [sdk-and-auth-flow.md](./sdk-and-auth-flow.md)
+   Explains the runtime flow, S2S token exchange, OBO/M365 token cache, optional
+   hosting peer dependency, per-request export, and trace propagation.
+5. [microsoft-node-package-comparison.md](./microsoft-node-package-comparison.md)
+   Compares the Microsoft Node packages, OpenAI/LangChain extensions, and this
+   agent-core adapter feature by feature.
+6. [lifecycle-and-limits.md](./lifecycle-and-limits.md)
    Explains startup order, per-request baggage, session/conversation behavior,
    and v0 limits.
 

package/docs/architecture.md

@@ -5,12 +5,13 @@ 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         |
+| 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           |
+| `@microsoft/agents-a365-observability-hosting` | M365 hosting utilities such as `AgenticTokenCache` for OBO authorization                                        | S2S token exchange or agent-core telemetry                      |
+| `@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
@@ -43,6 +44,17 @@ Per turn:
    start;
 5. Microsoft's exporter sends the final span shape to Agent 365.
 
+## Auth Paths
+
+S2S and OBO use different Microsoft SDK surfaces. S2S uses this adapter's FMI
+token resolver and Microsoft's core observability exporter. It does not load
+`@microsoft/agents-a365-observability-hosting`.
+
+OBO uses Microsoft's hosting `AgenticTokenCache` because the token comes from a
+Microsoft-hosted turn authorization exchange. The hosting package is therefore
+an optional peer dependency and is lazy-loaded only by OBO helpers. See
+[sdk-and-auth-flow.md](./sdk-and-auth-flow.md) for the complete flow.
+
 ## Why Not Put This In Agent-Core?
 
 Agent 365 observability has Microsoft-specific concepts:

package/docs/lifecycle-and-limits.md

@@ -94,6 +94,58 @@ await runWithA365Context(
 );
 ```
 
+Per-request export can be enabled and tuned at startup:
+
+```ts
+await initA365Observability({
+  serviceName: "email-agent-service",
+  tokenResolver,
+  configuration: {
+    exporterEnabled: true,
+    perRequest: {
+      enabled: true,
+      maxTraces: 1000,
+      maxSpansPerTrace: 5000,
+      maxConcurrentExports: 20,
+      flushGraceMs: 250,
+      maxTraceAgeMs: 30 * 60 * 1000,
+    },
+  },
+});
+```
+
+Microsoft's public builder currently reads these processor tuning values through
+its default environment-backed provider. The adapter applies explicit startup
+configuration to those environment variables before calling Microsoft's SDK
+start method.
+
+## Trace Propagation
+
+Use `injectA365TraceContextToHeaders(...)` before outbound A2A HTTP calls and
+`runWithA365ExtractedTraceContext(...)` on inbound handlers. For queue,
+callback, or WebSocket flows where only ids can be persisted, use
+`runWithA365ParentSpanRef(...)`.
+
+These helpers wrap Microsoft propagation utilities and do not create spans by
+themselves.
+
+## Output Message Spans
+
+`runWithA365OutputMessages(...)` exposes Microsoft's `OutputScope` as an
+opt-in delivery wrapper. It should be used only where a deployment needs a
+separate `output_messages` span because message content is recorded as telemetry
+attributes.
+
+## S2S And OBO Auth Helpers
+
+`initA365S2SObservability(...)` is the preferred setup for non-OBO service
+agents created with the Agent 365 CLI. It understands generated
+`agent365Observability__*` settings and sets the Microsoft S2S exporter
+endpoint option.
+
+M365 per-user hosts can use `refreshA365OboObservabilityToken(...)` and
+`createA365OboTokenResolver(...)` around Microsoft's `AgenticTokenCache`.
+
 ## M365 Session Mapping
 
 `@cuylabs/agent-channel-m365` defaults to using M365 `conversation.id` as the
@@ -105,13 +157,12 @@ If you use a custom session mapping, agent-core will set
 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
+## Limits
 
-v0 does not expose:
+This package does not expose:
 
-- a separate Microsoft `OutputScope` span;
-- agent-to-agent HTTP trace propagation wrappers;
 - custom span processors for overriding agent-core attributes;
+- raw OpenAI Agents or LangChain instrumentors;
 - real-time threat protection or chat-history submission middleware.
 
 Those features are additive and should be introduced only when a real Agent 365

package/docs/microsoft-a365-observability.md

@@ -18,6 +18,13 @@ Microsoft's SDK owns:
 
 This package intentionally does not reimplement those pieces.
 
+Microsoft's hosting package,
+`@microsoft/agents-a365-observability-hosting`, owns M365 turn helpers and
+`AgenticTokenCache`. That package is not required for S2S observability. This
+adapter lazy-loads it only for OBO helpers such as
+`refreshA365OboObservabilityToken(...)` and
+`createA365OboTokenResolver(...)`.
+
 ## Why This Package Still Exists
 
 Microsoft's SDK is platform-level observability infrastructure. It does not
@@ -34,6 +41,9 @@ The answer is:
 2. pass stable tracing config into `createAgent()`;
 3. wrap each request with Agent 365 baggage before `agent.chat()` runs.
 
+The detailed startup, S2S, OBO, per-request export, and trace propagation flows
+are documented in [sdk-and-auth-flow.md](./sdk-and-auth-flow.md).
+
 ## Scope Classes
 
 Microsoft exposes explicit scope classes for several span shapes. agent-core
@@ -44,10 +54,9 @@ 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.
+The adapter exposes `runWithA365OutputMessages(...)` as an opt-in wrapper for
+that separate `OutputScope`. Keep it out of the default path because outgoing
+message content is recorded as telemetry.
 
 ## Trace Propagation
 
@@ -57,9 +66,9 @@ Microsoft also exports helpers such as:
 - `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.
+Those are useful for agent-to-agent HTTP trace continuation. The adapter
+exposes first-class wrappers for these helpers so hosts can propagate trace
+context without importing Microsoft SDK types directly.
 
 ## TurnContext Mapping Parity
 

package/docs/microsoft-node-package-comparison.md

@@ -0,0 +1,75 @@
+# Microsoft Node Package Comparison
+
+This package is an `@cuylabs/agent-core` adapter. It is not a replacement for
+Microsoft's Agent 365 observability packages. It uses Microsoft's runtime and
+exporter where those packages own the behavior, and it avoids the parts that
+would duplicate spans already emitted by agent-core.
+
+## Core Concept
+
+Microsoft's Node observability packages have three practical layers:
+
+| Layer                | Microsoft package                                                                                                     | Purpose                                                                                        |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Runtime and exporter | `@microsoft/agents-a365-observability`                                                                                | Starts OpenTelemetry, adds Agent 365 baggage enrichment, and exports spans to Agent 365.       |
+| Hosting helpers      | `@microsoft/agents-a365-observability-hosting`                                                                        | Maps Microsoft Activity/TurnContext fields into Agent 365 baggage and middleware.              |
+| Framework extensions | `@microsoft/agents-a365-observability-extensions-openai`, `@microsoft/agents-a365-observability-extensions-langchain` | Patch specific agent frameworks and translate their lifecycle events into OpenTelemetry spans. |
+
+The cuylabs adapter sits beside those framework extensions. OpenAI Agents and
+LangChain need extension packages because their framework callbacks must be
+converted into Agent 365-shaped OpenTelemetry spans. agent-core already emits
+agent, tool, and model spans, so this adapter focuses on startup, token
+resolution, and Agent 365 baggage.
+
+## What We Use
+
+| Microsoft capability                                               | Our usage                                                                                                            | Reason                                                                                                                                          |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ObservabilityManager` / `ObservabilityBuilder`                    | Used by `initA365Observability(...)`.                                                                                | Microsoft owns exporter registration and OpenTelemetry processor setup.                                                                         |
+| Agent 365 span exporter                                            | Used through Microsoft's builder.                                                                                    | We should not duplicate the export protocol, batching, partitioning, retries, or endpoint behavior.                                             |
+| Baggage span processor                                             | Used through Microsoft's builder.                                                                                    | It copies Agent 365 baggage into span attributes without agent-core depending on Microsoft SDK types.                                           |
+| `BaggageBuilder.setPairs(...)`                                     | Used by `runWithA365Context(...)` and `runWithA365TurnContext(...)`.                                                 | It gives us Microsoft's baggage scope behavior while keeping the cuylabs API typed around agent-core needs.                                     |
+| Batch export token resolver                                        | Used through `initA365Observability({ tokenResolver })`.                                                             | The host can provide per-tenant Agent 365 Observability tokens.                                                                                 |
+| Per-request export token context                                   | Exposed as `exportToken` and `updateA365ExportToken(...)`.                                                           | Keeps compatibility with Microsoft per-request export mode when the host has request-scoped auth.                                               |
+| Exporter options, cluster category, logger, configuration provider | Passed through from `initA365Observability(...)`.                                                                    | These are runtime concerns owned by the host process.                                                                                           |
+| Agent 365 S2S token exchange                                       | Implemented in `createA365S2STokenResolver(...)`.                                                                    | The Agent 365 `fmi_path` token exchange is required by the setup flow and is not exposed by the standard Azure Identity client credential APIs. |
+| Agent 365 CLI environment aliases                                  | Exposed through `resolveA365ObservabilityEnvironment(...)` and `createA365S2STokenResolverFromEnv(...)`.             | Hosts can use generated `agent365Observability__*` settings directly.                                                                           |
+| S2S exporter endpoint wiring                                       | Exposed through `initA365S2SObservability(...)`.                                                                     | S2S export requires Microsoft's `useS2SEndpoint` exporter option.                                                                               |
+| Trace context propagation helpers                                  | Exposed as `injectA365TraceContextToHeaders(...)`, `runWithA365ExtractedTraceContext(...)`, and parent-span helpers. | A2A HTTP and async continuation need trace propagation without duplicate spans.                                                                 |
+| Per-request processor tuning                                       | Exposed through `configuration.perRequest`.                                                                          | Microsoft currently reads per-request tuning from env-backed configuration, so the adapter applies explicit startup settings before SDK start.  |
+| `OutputScope`                                                      | Exposed through opt-in `runWithA365OutputMessages(...)`.                                                             | Some dashboards may want separate `output_messages` spans, but content capture should stay deliberate.                                          |
+| `AgenticTokenCache`                                                | Exposed through OBO helpers.                                                                                         | M365/OBO hosts can refresh and resolve per-user observability tokens without using the S2S flow.                                                |
+
+## What We Do Not Use By Default
+
+| Microsoft capability    | Status               | Reason                                                                                                         |
+| ----------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `InvokeAgentScope`      | Not used by default. | agent-core already emits the agent turn span. Creating another scope would duplicate `invoke_agent` telemetry. |
+| `ExecuteToolScope`      | Not used by default. | agent-core already emits tool spans around tool execution.                                                     |
+| `InferenceScope`        | Not used by default. | AI SDK telemetry already emits model spans under the agent turn.                                               |
+| OpenAI Agents extension | Not used by default. | It patches `@openai/agents`; agent-core is the harness we adapt.                                               |
+| LangChain extension     | Not used by default. | It patches LangChain callbacks; agent-core already owns the turn and tool lifecycle.                           |
+| Hosting middleware      | Not used directly.   | `agent-channel-m365` and this package perform the equivalent turn wrapping for cuylabs hosts.                  |
+
+These are intentional gaps, not missing wiring. The default integration should
+enrich and export the spans agent-core already creates.
+
+## Feature Gaps To Add Only When Needed
+
+| Feature                      | Why it may matter                                                                           | Likely cuylabs shape                                                              |
+| ---------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Framework-specific bridges   | Needed only if a cuylabs host runs raw OpenAI Agents or LangChain flows outside agent-core. | Provide opt-in bridge packages or examples, not default behavior in this adapter. |
+| Privacy and content controls | Needed when the host must suppress prompt, completion, or tool payload attributes.          | Surface explicit config aligned with agent-core's telemetry controls.             |
+
+## Current Direction
+
+The right production boundary is:
+
+1. let agent-core emit portable OpenTelemetry spans;
+2. let this package attach Agent 365 identity, request, and tenant context;
+3. let Microsoft's SDK enrich spans and export them to Agent 365;
+4. add optional helpers only where Agent 365 needs a span shape that agent-core
+   does not already produce.
+
+That keeps the adapter small, avoids double instrumentation, and leaves the
+Microsoft SDK responsible for Microsoft-owned runtime behavior.

package/docs/sdk-and-auth-flow.md

@@ -0,0 +1,125 @@
+# SDK And Auth Flow
+
+This package is an adapter around Microsoft's Agent 365 observability SDKs. It
+does not replace those SDKs, and it does not put Microsoft types in
+`@cuylabs/agent-core`.
+
+## SDK Dependencies
+
+| Package                                        | Required for                                 | How this adapter uses it                                                                                                                                                                                                                          |
+| ---------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@microsoft/agents-a365-observability`         | All Agent 365 export paths                   | Lazy-loaded by startup and runtime helpers. It owns `ObservabilityManager`, the exporter, baggage scope, baggage span processor, per-request export token context, trace propagation utilities, and optional scope classes such as `OutputScope`. |
+| `@microsoft/agents-a365-runtime`               | Microsoft configuration and cluster metadata | Required by the Microsoft observability SDK. The adapter passes configuration into Microsoft's builder and keeps agent-core independent of runtime-specific types.                                                                                |
+| `@microsoft/agents-a365-observability-hosting` | M365/OBO token-cache helpers only            | Lazy-loaded only by OBO helpers. It provides Microsoft's `AgenticTokenCache`, which exchanges M365 turn authorization into observability tokens. S2S hosts do not need this package unless they call OBO helpers.                                 |
+
+The hosting package is an optional peer dependency because the default S2S path
+does not use it. If an application calls OBO helpers without installing it, the
+adapter raises `A365ObservabilityHostingModuleLoadError` with an installation
+message.
+
+## Observability Runtime Flow
+
+At process startup, the host calls either `initA365Observability(...)` or
+`initA365S2SObservability(...)`. The adapter lazy-loads
+`@microsoft/agents-a365-observability`, calls Microsoft's
+`ObservabilityManager.configure(...)`, and passes service metadata, exporter
+options, token resolver, logger, cluster category, and configuration provider.
+
+When Microsoft's builder starts, it registers the OpenTelemetry provider or
+attaches processors to the existing global provider. It adds a baggage span
+processor and an export processor. The baggage processor copies current Agent
+365 baggage values onto spans. The export processor sends final spans to Agent
+365 either in batch mode or per-request mode.
+
+Per agent, the host passes `createA365TracingConfig(...)` into
+`createAgent({ tracing })`. agent-core still owns the real agent telemetry. It
+emits agent turn spans, tool spans, and AI SDK model spans.
+
+Per turn, the host or channel adapter calls `runWithA365Context(...)` or
+`runWithA365TurnContext(...)` before running `agent.chat(...)`. The adapter
+builds Agent 365 baggage from tenant, agent, conversation, channel, user, and
+caller-agent fields, then enters Microsoft's `BaggageScope`. Spans created by
+agent-core inside that scope are enriched by Microsoft's baggage processor.
+
+At export time, Microsoft's exporter groups spans by tenant and agent identity.
+For each group it obtains a bearer token, sets the tenant header, serializes the
+spans into Agent 365's OTLP-shaped payload, chunks oversized payloads, and posts
+to the Agent 365 observability endpoint.
+
+## S2S Flow
+
+Use S2S for non-M365, service-owned agents such as an App Service agent created
+with:
+
+```bash
+a365 setup all --agent-name aisoc-agent-s2s-dev --tenant-id <tenant-id> --authmode s2s
+```
+
+The CLI creates Agent 365 identity settings such as
+`agent365Observability__tenantId`, `agent365Observability__agentId`,
+`agent365Observability__clientId`, and
+`agent365Observability__clientSecret`. The adapter reads those aliases through
+`resolveA365ObservabilityEnvironment(...)` and
+`createA365S2STokenResolverFromEnv(...)`.
+
+The S2S token resolver performs the Agent 365 FMI token flow:
+
+1. The blueprint credential, or a managed-identity assertion, requests an FMI
+   token from Entra with `fmi_path` set to the Agent 365 agent identity id.
+2. The agent identity uses that FMI token as a client assertion.
+3. Entra returns an Observability API token for
+   `api://9b975845-388f-4429-889e-eab1ef63949c/.default`.
+4. Microsoft's exporter uses that token to write telemetry through the S2S
+   Agent 365 Observability endpoint.
+
+`initA365S2SObservability(...)` is the safest S2S startup helper. It creates the
+resolver from environment values, enables Microsoft's S2S exporter endpoint by
+setting `useS2SEndpoint: true`, and enables the exporter unless the host
+explicitly overrides that setting.
+
+The S2S path does not use `@microsoft/agents-a365-observability-hosting`.
+
+## OBO / M365 Flow
+
+Use OBO for M365-hosted agents where the current turn has Microsoft hosting
+authorization and the observability token should be derived from that turn.
+This is separate from the S2S blueprint flow.
+
+OBO helpers use Microsoft's `AgenticTokenCache` from
+`@microsoft/agents-a365-observability-hosting`. The host refreshes the cache
+with `refreshA365OboObservabilityToken(...)`, passing the agent id, tenant id,
+TurnContext, Authorization object, scopes, and auth handler name. The Microsoft
+cache calls `authorization.exchangeToken(...)`, stores the resulting token by
+agent id and tenant id, and applies token expiry rules.
+
+`createA365OboTokenResolver(...)` returns a token resolver for Microsoft's
+exporter. When the exporter asks for a token, the resolver reads the cached OBO
+token for the current agent and tenant.
+
+Because this flow needs Microsoft hosting types and authorization behavior, the
+hosting package is optional and lazy-loaded only for OBO helpers.
+
+## Per-Request Export
+
+Batch export resolves tokens through the startup `tokenResolver`. Per-request
+export reads the export token from OpenTelemetry context instead. The adapter
+exposes this through `exportToken` on `runWithA365Context(...)` and
+`updateA365ExportToken(...)`.
+
+Microsoft's current per-request processor reads tuning values from its
+environment-backed provider. The adapter accepts `configuration.perRequest` and
+applies those values to Microsoft's expected environment variables before
+starting the SDK.
+
+## Trace Propagation And Output Spans
+
+Trace propagation helpers wrap Microsoft's W3C trace utilities. Use
+`injectA365TraceContextToHeaders(...)` before outbound agent-to-agent HTTP
+calls and `runWithA365ExtractedTraceContext(...)` on inbound handlers. Use
+`runWithA365ParentSpanRef(...)` for queues, callbacks, or WebSocket flows where
+only a saved parent trace id and span id are available.
+
+`runWithA365OutputMessages(...)` wraps Microsoft's `OutputScope` for deployments
+that need a separate `output_messages` span. It is opt-in because outgoing
+message content is recorded as telemetry. The default path keeps output
+recording on the agent-core turn span.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-a365-observability",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "Microsoft Agent 365 observability adapter for @cuylabs/agent-core",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,18 +26,22 @@
     "typescript": "^5.7.0",
     "vitest": "^4.0.18",
     "zod": "^3.25.76 || ^4.1.8",
-    "@cuylabs/agent-core": "^4.5.0"
+    "@cuylabs/agent-core": "^4.6.0"
   },
   "peerDependencies": {
     "@cuylabs/agent-core": "^4.0.0",
     "ai": "7.0.0-beta.111",
     "@microsoft/agents-a365-observability": ">=0.2.0-preview.5 <1.0.0",
+    "@microsoft/agents-a365-observability-hosting": ">=0.2.0-preview.5 <1.0.0",
     "@microsoft/agents-a365-runtime": ">=0.2.0-preview.5 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@microsoft/agents-a365-observability": {
       "optional": true
     },
+    "@microsoft/agents-a365-observability-hosting": {
+      "optional": true
+    },
     "@microsoft/agents-a365-runtime": {
       "optional": true
     }