@cuylabs/agent-a365-observability 4.5.0 → 4.6.0

package/README.md

@@ -14,7 +14,9 @@ It does four things:
 - 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).
+For the deeper design, read [docs/README.md](./docs/README.md). For the full
+SDK and auth flow, read
+[docs/sdk-and-auth-flow.md](./docs/sdk-and-auth-flow.md).
 
 ## Install
 
@@ -22,14 +24,28 @@ For the deeper design, read [docs/README.md](./docs/README.md).
 pnpm add @cuylabs/agent-a365-observability @microsoft/agents-a365-observability @microsoft/agents-a365-runtime
 ```
 
+Install `@microsoft/agents-a365-observability-hosting` as well when using the
+M365/OBO token-cache helpers.
+
+Dependency roles:
+
+| Package                                        | Required when                             | Notes                                                                                                                               |
+| ---------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `@microsoft/agents-a365-observability`         | Always, when exporting to Agent 365       | Owns Microsoft's `ObservabilityManager`, exporter, baggage processor, trace propagation utilities, and optional `OutputScope`.      |
+| `@microsoft/agents-a365-runtime`               | Always with Microsoft's observability SDK | Provides Microsoft runtime configuration types used by the SDK.                                                                     |
+| `@microsoft/agents-a365-observability-hosting` | Only for M365/OBO token-cache helpers     | Provides `AgenticTokenCache`. It is an optional peer and is lazy-loaded only by OBO helpers. S2S App Service agents do not need it. |
+
 ## Usage
 
 ```typescript
 import { createAgent } from "@cuylabs/agent-core";
 import {
+  createA365S2STokenResolverFromEnv,
   createA365TracingConfig,
+  initA365S2SObservability,
   initA365Observability,
   runWithA365Context,
+  runWithA365OutputMessages,
   runWithA365TurnContext,
 } from "@cuylabs/agent-a365-observability";
 
@@ -116,7 +132,15 @@ startup so the Microsoft exporter and token resolver are registered.
 
 ## Shape
 
-The integration has three separate pieces:
+This package is the `@cuylabs/agent-core` equivalent of a framework-specific
+Agent 365 observability extension. Microsoft's OpenAI Agents and LangChain
+extension packages patch those harnesses directly so their model/framework
+spans flow through the Agent 365 ObservabilityManager. This package does the
+same kind of adapter work at the agent-core layer: it starts the Microsoft
+ObservabilityManager, feeds agent-core tracing metadata, and wraps each
+agent-core turn with Agent 365 baggage.
+
+The integration has four separate pieces:
 
 1. `initA365Observability(...)` starts Microsoft's exporter and baggage span
    processor once at host startup.
@@ -124,6 +148,13 @@ The integration has three separate pieces:
    contract.
 3. `runWithA365Context(...)` or `runWithA365TurnContext(...)` binds
    per-request Agent 365 baggage before `agent.chat()` runs.
+4. `createA365S2STokenResolver(...)` provides a reusable service-to-service
+   token resolver for Agent 365 Observability API export.
+
+The source follows those same boundaries: `auth/` owns Agent 365 S2S token
+resolution, `context/` owns baggage and TurnContext mapping, `runtime/` owns
+Microsoft SDK startup and lazy loading, and `tracing/` owns the agent-core
+tracing config adapter.
 
 Use agent-core for portable OpenTelemetry spans:
 
@@ -203,17 +234,169 @@ you need those dimensions.
 
 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.
+For non-OBO service-to-service export, use `initA365S2SObservability()` when
+the host should use the Agent 365 CLI generated environment values. The helper
+understands both `A365_OBSERVABILITY_*` names and generated
+`agent365Observability__*` names such as `agent365Observability__tenantId`,
+`agent365Observability__agentId`, `agent365Observability__clientId`, and
+`agent365Observability__clientSecret`.
+
+```typescript
+await initA365S2SObservability({
+  serviceName: "email-agent-service",
+  serviceVersion: "1.0.0",
+});
+```
+
+The S2S initializer creates the token resolver, enables the Microsoft S2S
+exporter endpoint, and enables the exporter unless configuration overrides it.
+
+Use `createA365S2STokenResolverFromEnv()` when you want the resolver only:
+
+```typescript
+const tokenResolver = createA365S2STokenResolverFromEnv();
+
+await initA365Observability({
+  serviceName: "email-agent-service",
+  tokenResolver,
+  exporterOptions: { useS2SEndpoint: true },
+  configuration: { exporterEnabled: true },
+});
+```
+
+Use `createA365S2STokenResolver()` when you want to pass values explicitly:
+
+```typescript
+import {
+  createA365S2STokenResolver,
+  initA365Observability,
+} from "@cuylabs/agent-a365-observability";
+
+const tokenResolver = createA365S2STokenResolver({
+  tenantId: process.env.A365_OBSERVABILITY_TENANT_ID!,
+  agentId: process.env.A365_OBSERVABILITY_AGENT_ID!,
+  blueprintClientId: process.env.A365_OBSERVABILITY_CLIENT_ID!,
+  blueprintClientSecret: process.env.A365_OBSERVABILITY_CLIENT_SECRET,
+  useManagedIdentity:
+    process.env.A365_OBSERVABILITY_USE_MANAGED_IDENTITY === "true",
+});
+
+await initA365Observability({
+  serviceName: "email-agent-service",
+  tokenResolver,
+  exporterOptions: { useS2SEndpoint: true },
+  configuration: { exporterEnabled: true },
+});
+```
+
+Hosts that want Azure managed identity without taking an Azure dependency in
+this package can pass `managedIdentityAssertionProvider`; the provider should
+return an assertion token for `api://AzureADTokenExchange`.
+
+For per-request export, pass `exportToken` to `runWithA365Context()` and enable
+per-request export in startup configuration:
+
+```typescript
+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 current per-request processor reads its tuning options from
+environment-backed configuration. This package applies these explicit startup
+values to the Microsoft environment variables before the SDK starts.
+
+## Trace Propagation
+
+Use the trace propagation helpers when one agent calls another over HTTP or
+when async work needs to keep a parent span:
+
+```typescript
+const headers = await injectA365TraceContextToHeaders({});
+await fetch(agentUrl, { method: "POST", headers });
+
+await runWithA365ExtractedTraceContext(req.headers, () =>
+  runWithA365Context(context, () => agent.chat(sessionId, text)),
+);
+```
+
+For queue or callback flows where you persisted the parent span ids, use
+`runWithA365ParentSpanRef(...)`.
+
+## Optional Output Spans
+
+agent-core records output messages on the agent turn span. If an Agent 365
+deployment needs Microsoft's separate `output_messages` span shape, wrap the
+outgoing delivery path:
+
+```typescript
+await runWithA365OutputMessages(
+  {
+    tenantId,
+    agentId,
+    conversationId,
+    channelName: "msteams",
+    messages: ["Done."],
+  },
+  () => sendMessage("Done."),
+);
+```
+
+This is opt-in because outgoing message content is recorded as telemetry.
+
+## OBO Token Cache
+
+For M365/OBO hosts, use the OBO helpers around Microsoft's
+`AgenticTokenCache`. This is separate from the S2S setup flow.
+
+This path requires the optional
+`@microsoft/agents-a365-observability-hosting` peer because `AgenticTokenCache`
+lives in Microsoft's hosting package. The adapter does not load that package
+for S2S startup, S2S token resolution, baggage wrapping, trace propagation, or
+output spans. It is loaded only when an OBO helper is called.
+
+```typescript
+await refreshA365OboObservabilityToken({
+  agentId,
+  tenantId,
+  turnContext,
+  authorization,
+  scopes: ["api://9b975845-388f-4429-889e-eab1ef63949c/.default"],
+});
+
+await initA365Observability({
+  serviceName: "email-agent-service",
+  tokenResolver: createA365OboTokenResolver(),
+  configuration: { exporterEnabled: true },
+});
+```
 
-## v0 Limits
+## Optional Features
 
-v0 does not expose:
+The adapter now exposes the official additive pieces that do not duplicate
+agent-core telemetry:
 
-- a separate Microsoft `OutputScope` span;
-- agent-to-agent HTTP trace propagation wrappers;
-- real-time threat protection or chat-history submission middleware.
+- S2S Observability token resolution, including Agent 365 CLI env aliases;
+- Microsoft trace context propagation helpers;
+- per-request export token and processor configuration;
+- optional Microsoft `OutputScope` output-message spans;
+- OBO token cache helpers for M365 per-user authorization.
 
-Those remain additive adapter features if an Agent 365 deployment needs them.
+Real-time threat protection and chat-history submission are outside
+observability and should live in separate Agent 365 tooling or security
+packages.
 
 ## Examples
 

package/dist/index.d.ts

@@ -5,14 +5,29 @@ type A365Logger = {
     info(message: string, ...args: unknown[]): void;
     warn(message: string, ...args: unknown[]): void;
     error(message: string, ...args: unknown[]): void;
-    event?(eventName: string, success: boolean, durationMs: number, message?: string, details?: Record<string, string>): void;
+    event?(eventName: A365ExporterEventName | (string & {}), success: boolean, durationMs: number, message?: string, details?: Record<string, string>): void;
 };
+declare const A365_EXPORTER_EVENT_NAMES: {
+    readonly export: "agent365-export";
+    readonly exportGroup: "export-group";
+    readonly exportPartitionSpanMissingIdentity: "export-partition-span-missing-identity";
+};
+type A365ExporterEventName = (typeof A365_EXPORTER_EVENT_NAMES)[keyof typeof A365_EXPORTER_EVENT_NAMES];
 type SpanAttributeValue = string | number | boolean | string[] | number[] | boolean[];
 type A365ObservabilityConfiguration = {
     exporterEnabled?: boolean;
     domainOverride?: string | null;
     logLevel?: string;
     authenticationScopes?: string[];
+    perRequest?: A365PerRequestExportConfiguration;
+};
+type A365PerRequestExportConfiguration = {
+    enabled?: boolean;
+    maxTraces?: number;
+    maxSpansPerTrace?: number;
+    maxConcurrentExports?: number;
+    flushGraceMs?: number;
+    maxTraceAgeMs?: number;
 };
 type A365RequestContext = {
     tenantId?: string;
@@ -130,15 +145,85 @@ type A365TracingConfig = {
     spanAttributes?: Record<string, SpanAttributeValue>;
 };
 
+declare class A365ObservabilityModuleLoadError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+declare class A365ObservabilityHostingModuleLoadError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+
+type A365ManagedIdentityAssertionProvider = () => string | Promise<string>;
+type A365S2STokenResolverLogger = {
+    warn(message: string, details?: Record<string, unknown>): void;
+};
+type A365S2STokenResolverOptions = {
+    tenantId: string;
+    agentId: string;
+    blueprintClientId: string;
+    blueprintClientSecret?: string;
+    useManagedIdentity?: boolean;
+    managedIdentityAssertionProvider?: A365ManagedIdentityAssertionProvider;
+    allowManagedIdentityClientSecretFallback?: boolean;
+    observabilityScope?: string;
+    fmiScope?: string;
+    refreshSkewMs?: number;
+    logger?: A365S2STokenResolverLogger;
+    fetch?: typeof fetch;
+};
+
+/**
+ * Creates an Agent 365 S2S Observability API token resolver.
+ *
+ * The resolver implements the Agent 365 3-hop FMI flow used by non-OBO agents:
+ *
+ * 1. Blueprint credential or managed-identity assertion -> FMI token targeted at
+ *    the agent identity through `fmi_path`.
+ * 2. Agent identity uses that FMI token as a client assertion.
+ * 3. Entra returns an Observability API token for the Agent 365 exporter.
+ */
+declare function createA365S2STokenResolver(options: A365S2STokenResolverOptions): A365TokenResolver;
+
+type A365Environment = Record<string, string | undefined>;
+type A365ResolvedObservabilityEnvironment = {
+    tenantId?: string;
+    agentId?: string;
+    agentName?: string;
+    agentDescription?: string;
+    blueprintClientId?: string;
+    blueprintClientSecret?: string;
+    useManagedIdentity?: boolean;
+    observabilityScope?: string;
+    fmiScope?: string;
+    configuration: A365ObservabilityConfiguration;
+};
+type A365S2STokenResolverFromEnvOptions = Partial<Omit<A365S2STokenResolverOptions, "tenantId" | "agentId" | "blueprintClientId">> & Partial<Pick<A365S2STokenResolverOptions, "tenantId" | "agentId" | "blueprintClientId">> & {
+    env?: A365Environment;
+};
+declare function resolveA365ObservabilityEnvironment(env?: A365Environment): A365ResolvedObservabilityEnvironment;
+declare function createA365S2STokenResolverFromEnv(options?: A365S2STokenResolverFromEnvOptions): A365TokenResolver;
+
+type A365AgenticTokenCacheLike = {
+    getObservabilityToken(agentId: string, tenantId: string): string | null;
+    RefreshObservabilityToken(agentId: string, tenantId: string, turnContext: unknown, authorization: unknown, scopes: string[], authHandlerName?: string): Promise<void>;
+    invalidateToken?(agentId: string, tenantId: string): void;
+    invalidateAll?(): void;
+};
+
 type A365ObservabilityModuleLoader = () => Promise<unknown>;
 type A365ObservabilityRuntimeOptions = {
     /**
-     * Test seam for loading `@microsoft/agents-a365-observability`.
+     * Loader override for `@microsoft/agents-a365-observability`.
      *
      * Production code normally leaves this unset so the package is loaded lazily
      * only when observability is used.
      */
     getObservabilityModule?: A365ObservabilityModuleLoader;
+    /**
+     * Loader override for `@microsoft/agents-a365-observability-hosting`.
+     *
+     * Only OBO token-cache helpers use this package.
+     */
+    getObservabilityHostingModule?: A365ObservabilityModuleLoader;
 };
 type InitA365ObservabilityOptions = A365ObservabilityRuntimeOptions & {
     serviceName: string;
@@ -154,9 +239,28 @@ type A365ObservabilityHandle = {
     shutdown(): Promise<void>;
 };
 
-declare class A365ObservabilityModuleLoadError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-}
+type A365AuthorizationLike = {
+    exchangeToken(turnContext: unknown, authHandlerName: string, options: {
+        scopes: string[];
+    }): Promise<{
+        token?: string;
+    } | undefined>;
+};
+type A365OboTokenCacheOptions = A365ObservabilityRuntimeOptions & {
+    cache?: A365AgenticTokenCacheLike;
+};
+type A365RefreshOboObservabilityTokenOptions = A365OboTokenCacheOptions & {
+    agentId: string;
+    tenantId: string;
+    turnContext: unknown;
+    authorization: A365AuthorizationLike;
+    scopes?: string[];
+    authHandlerName?: string;
+};
+declare function createA365OboTokenResolver(options?: A365OboTokenCacheOptions): A365TokenResolver;
+declare function refreshA365OboObservabilityToken(options: A365RefreshOboObservabilityTokenOptions): Promise<void>;
+declare function invalidateA365OboObservabilityToken(agentId: string, tenantId: string, options?: A365OboTokenCacheOptions): Promise<void>;
+declare function invalidateAllA365OboObservabilityTokens(options?: A365OboTokenCacheOptions): Promise<void>;
 
 declare const A365_BAGGAGE_KEYS: {
     readonly tenantId: "microsoft.tenant.id";
@@ -192,8 +296,6 @@ declare const A365_BAGGAGE_KEYS: {
 
 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, runtimeOptions?: A365ObservabilityRuntimeOptions): Promise<Awaited<T>>;
@@ -203,4 +305,45 @@ declare function initA365Observability(options: InitA365ObservabilityOptions): P
 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, 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 };
+/**
+ * Microsoft currently reads per-request processor settings through its default
+ * env-backed provider. Apply explicit startup options before the SDK starts.
+ */
+declare function applyA365PerRequestEnvironment(configuration: A365PerRequestExportConfiguration | undefined, env?: NodeJS.ProcessEnv): void;
+
+type InitA365S2SObservabilityOptions = Omit<InitA365ObservabilityOptions, "tokenResolver"> & {
+    s2s?: A365S2STokenResolverFromEnvOptions;
+};
+declare function initA365S2SObservability(options: InitA365S2SObservabilityOptions): Promise<A365ObservabilityHandle>;
+
+declare function createA365TracingConfig(options?: A365TracingConfigOptions): A365TracingConfig;
+
+type A365HeadersCarrier = Record<string, string | string[] | undefined>;
+type A365MutableHeadersCarrier = Record<string, string>;
+type A365ParentSpanRef = {
+    traceId: string;
+    spanId: string;
+    traceFlags?: number;
+    traceState?: unknown;
+    isRemote?: boolean;
+};
+type A365TraceContextOptions = A365ObservabilityRuntimeOptions & {
+    context?: unknown;
+};
+declare function injectA365TraceContextToHeaders(headers?: A365MutableHeadersCarrier, options?: A365TraceContextOptions): Promise<A365MutableHeadersCarrier>;
+declare function extractA365TraceContextFromHeaders(headers: A365HeadersCarrier, options?: A365TraceContextOptions): Promise<unknown>;
+declare function runWithA365ExtractedTraceContext<T>(headers: A365HeadersCarrier, fn: () => T, options?: A365ObservabilityRuntimeOptions): Promise<Awaited<T>>;
+declare function runWithA365ParentSpanRef<T>(parent: A365ParentSpanRef, fn: () => T, options?: A365ObservabilityRuntimeOptions): Promise<Awaited<T>>;
+declare function createA365ContextWithParentSpanRef(baseContext: unknown, parent: A365ParentSpanRef, options?: A365ObservabilityRuntimeOptions): Promise<unknown>;
+
+type A365OutputMessagesParam = string | string[] | Record<string, unknown> | {
+    version: string;
+    messages: unknown[];
+};
+type A365OutputScopeContext = A365RequestContext & {
+    messages: A365OutputMessagesParam;
+    parentSpan?: A365ParentSpanRef;
+};
+declare function runWithA365OutputMessages<T>(output: A365OutputScopeContext, fn: () => T, options?: A365ObservabilityRuntimeOptions): Promise<Awaited<T>>;
+
+export { type A365ActivityAccountLike, type A365ActivityLike, type A365AuthorizationLike, type A365Environment, type A365ExporterEventName, type A365HeadersCarrier, type A365Logger, type A365ManagedIdentityAssertionProvider, type A365MutableHeadersCarrier, type A365OboTokenCacheOptions, type A365ObservabilityConfiguration, type A365ObservabilityHandle, A365ObservabilityHostingModuleLoadError, A365ObservabilityModuleLoadError, type A365ObservabilityModuleLoader, type A365ObservabilityRuntimeOptions, type A365OutputMessagesParam, type A365OutputScopeContext, type A365ParentSpanRef, type A365PerRequestExportConfiguration, type A365RefreshOboObservabilityTokenOptions, type A365RequestContext, type A365ResolvedObservabilityEnvironment, type A365S2STokenResolverFromEnvOptions, type A365S2STokenResolverLogger, type A365S2STokenResolverOptions, type A365TokenResolver, type A365TraceContextOptions, type A365TracingConfig, type A365TracingConfigOptions, type A365TurnContextLike, type A365TurnContextOptions, A365_BAGGAGE_KEYS, A365_EXPORTER_EVENT_NAMES, type InitA365ObservabilityOptions, type InitA365S2SObservabilityOptions, type SpanAttributeValue, applyA365PerRequestEnvironment, buildA365BaggagePairs, createA365ContextFromTurnContext, createA365ContextWithParentSpanRef, createA365OboTokenResolver, createA365S2STokenResolver, createA365S2STokenResolverFromEnv, createA365TracingConfig, extractA365TraceContextFromHeaders, initA365Observability, initA365S2SObservability, injectA365TraceContextToHeaders, invalidateA365OboObservabilityToken, invalidateAllA365OboObservabilityTokens, refreshA365OboObservabilityToken, resolveA365ObservabilityEnvironment, runWithA365Context, runWithA365ExtractedTraceContext, runWithA365OutputMessages, runWithA365ParentSpanRef, runWithA365TurnContext, updateA365ExportToken };