@cuylabs/agent-a365-observability 4.6.0 → 4.7.0

package/README.md

@@ -40,6 +40,7 @@ Dependency roles:
 ```typescript
 import { createAgent } from "@cuylabs/agent-core";
 import {
+  createA365ObservedTurnSource,
   createA365S2STokenResolverFromEnv,
   createA365TracingConfig,
   initA365S2SObservability,
@@ -90,6 +91,25 @@ await agent.close();
 await observability.shutdown();
 ```
 
+When you are adapting a custom channel around `AgentTurnSource`, use
+`createA365ObservedTurnSource(...)` instead of hand-rolling async-generator
+wrapping. The helper keeps the full event stream inside the Agent 365 baggage
+scope while letting the channel own its own metadata mapping:
+
+```typescript
+const observedSource = createA365ObservedTurnSource({
+  source: agent,
+  context: ({ sessionId }) => ({
+    tenantId: "tenant-123",
+    agentId: "agent-456",
+    conversationId: sessionId,
+    sessionId,
+    channelName: "slack",
+    userId: "slack-user-id",
+  }),
+});
+```
+
 ## M365 / Teams bot turns
 
 When your bot uses `@microsoft/agents-hosting` `TurnContext`, use the
@@ -148,7 +168,10 @@ The integration has four 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
+4. `createA365ObservedTurnSource(...)` wraps a channel-neutral
+   `AgentTurnSource` when a host needs streaming-safe A365 baggage around every
+   emitted event.
+5. `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

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { TelemetryOptions } from 'ai';
+import { AgentTurnSourceChatOptions, AgentTurnSource } from '@cuylabs/agent-core';
 
 type A365TokenResolver = (agentId: string, tenantId: string) => string | null | Promise<string | null>;
 type A365Logger = {
@@ -301,6 +302,19 @@ declare function createA365ContextFromTurnContext(turnContext: A365TurnContextLi
 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>>;
 
+type A365ObservedTurnSourceContextInput = {
+    sessionId: string;
+    message: string;
+    options?: AgentTurnSourceChatOptions;
+};
+type A365ObservedTurnSourceContextFactory = (input: A365ObservedTurnSourceContextInput) => A365RequestContext | Promise<A365RequestContext>;
+type A365ObservedTurnSourceOptions = {
+    source: AgentTurnSource;
+    context: A365RequestContext | A365ObservedTurnSourceContextFactory;
+    runtimeOptions?: A365ObservabilityRuntimeOptions;
+};
+declare function createA365ObservedTurnSource({ context, runtimeOptions, source, }: A365ObservedTurnSourceOptions): AgentTurnSource;
+
 declare function initA365Observability(options: InitA365ObservabilityOptions): Promise<A365ObservabilityHandle>;
 declare function runWithA365Context<T>(requestContext: A365RequestContext, fn: () => T, options?: A365ObservabilityRuntimeOptions): Promise<Awaited<T>>;
 declare function updateA365ExportToken(token: string, options?: A365ObservabilityRuntimeOptions): Promise<boolean>;
@@ -346,4 +360,4 @@ type A365OutputScopeContext = A365RequestContext & {
 };
 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 };
+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 A365ObservedTurnSourceContextFactory, type A365ObservedTurnSourceContextInput, type A365ObservedTurnSourceOptions, 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, createA365ObservedTurnSource, createA365S2STokenResolver, createA365S2STokenResolverFromEnv, createA365TracingConfig, extractA365TraceContextFromHeaders, initA365Observability, initA365S2SObservability, injectA365TraceContextToHeaders, invalidateA365OboObservabilityToken, invalidateAllA365OboObservabilityTokens, refreshA365OboObservabilityToken, resolveA365ObservabilityEnvironment, runWithA365Context, runWithA365ExtractedTraceContext, runWithA365OutputMessages, runWithA365ParentSpanRef, runWithA365TurnContext, updateA365ExportToken };

package/dist/index.js

@@ -876,6 +876,98 @@ async function runWithA365TurnContext(turnContext, optionsOrFn, maybeFnOrRuntime
   );
 }
 
+// src/internal/async-queue.ts
+var AsyncQueue = class {
+  values = [];
+  waiters = [];
+  closed = false;
+  push(value) {
+    if (this.closed) {
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value, done: false });
+      return;
+    }
+    this.values.push(value);
+  }
+  close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    for (const waiter of this.waiters.splice(0)) {
+      waiter({ value: void 0, done: true });
+    }
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => this.next()
+    };
+  }
+  next() {
+    if (this.values.length > 0) {
+      const value = this.values.shift();
+      return Promise.resolve({ value, done: false });
+    }
+    if (this.closed) {
+      return Promise.resolve({ value: void 0, done: true });
+    }
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+};
+
+// src/context/turn-source.ts
+function createA365ObservedTurnSource({
+  context,
+  runtimeOptions,
+  source
+}) {
+  const resolveContext = typeof context === "function" ? context : () => context;
+  return {
+    async *chat(sessionId, message, options) {
+      const requestContext = await resolveContext({
+        sessionId,
+        message,
+        options
+      });
+      const queue = new AsyncQueue();
+      let failure;
+      void runWithA365Context(
+        requestContext,
+        async () => {
+          try {
+            for await (const event of source.chat(
+              sessionId,
+              message,
+              options
+            )) {
+              queue.push(event);
+            }
+          } catch (error) {
+            failure = error;
+          } finally {
+            queue.close();
+          }
+        },
+        runtimeOptions
+      ).catch((error) => {
+        failure = error;
+        queue.close();
+      });
+      for await (const event of queue) {
+        yield event;
+      }
+      if (failure) {
+        throw failure;
+      }
+    }
+  };
+}
+
 // src/runtime/s2s.ts
 async function initA365S2SObservability(options) {
   const env = resolveA365ObservabilityEnvironment(options.s2s?.env);
@@ -1041,6 +1133,7 @@ export {
   createA365ContextFromTurnContext,
   createA365ContextWithParentSpanRef,
   createA365OboTokenResolver,
+  createA365ObservedTurnSource,
   createA365S2STokenResolver,
   createA365S2STokenResolverFromEnv,
   createA365TracingConfig,

package/docs/README.md

@@ -29,5 +29,6 @@ The short version:
 - `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.
+- this package starts Microsoft observability and wraps callbacks,
+  TurnContexts, or generic `AgentTurnSource` streams with the Agent 365 baggage
+  that Microsoft expects.

package/docs/architecture.md

@@ -35,8 +35,9 @@ Per agent:
 
 Per turn:
 
-1. the host or M365 channel calls `runWithA365Context(...)` or
-   `runWithA365TurnContext(...)`;
+1. the host or M365 channel calls `runWithA365Context(...)`,
+   `runWithA365TurnContext(...)`, or wraps an `AgentTurnSource` with
+   `createA365ObservedTurnSource(...)`;
 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;
@@ -67,3 +68,15 @@ Agent 365 observability has Microsoft-specific concepts:
 
 Putting those in agent-core would make core platform-specific. This adapter
 keeps the runtime portable while still supporting Agent 365 deployment.
+
+## Channel Bridges
+
+Channel-specific packages should not depend on this package just to describe
+their native metadata. For example, a Slack adapter can parse Slack user,
+channel, and thread fields without knowing Agent 365 semantic keys.
+
+The bridge that combines a channel with Agent 365 should map those fields into
+`A365RequestContext`, then pass that mapping to `createA365ObservedTurnSource`.
+That keeps the async stream and baggage lifecycle reusable while preserving the
+right ownership boundary: channels own channel facts, and the Agent 365 adapter
+owns Microsoft baggage/export behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-a365-observability",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "Microsoft Agent 365 observability adapter for @cuylabs/agent-core",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
     "typescript": "^5.7.0",
     "vitest": "^4.0.18",
     "zod": "^3.25.76 || ^4.1.8",
-    "@cuylabs/agent-core": "^4.6.0"
+    "@cuylabs/agent-core": "^4.7.0"
   },
   "peerDependencies": {
     "@cuylabs/agent-core": "^4.0.0",