@cuylabs/agent-a365-observability 4.6.0 → 4.7.1

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
@@ -156,11 +179,11 @@ 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:
+Use agent-core and AI SDK v7 for portable OpenTelemetry spans:
 
 - `invoke_agent` agent spans
-- `execute_tool` tool spans
-- AI SDK model spans nested under the agent turn
+- AI SDK `chat` model spans nested under the agent turn
+- AI SDK `execute_tool` tool spans when tools run
 
 Use this package for Agent 365-specific context on those spans:
 
@@ -189,7 +212,7 @@ See [docs/agent-core-otel.md](./docs/agent-core-otel.md) for details.
 
 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.
 
-Agent 365 is different. The Microsoft SDK owns the exporter and adds an Agent 365 span processor that copies baggage into span attributes. `agent-core` still emits the agent, tool, and AI SDK spans, while this package starts the Microsoft exporter and wraps each request with the tenant, agent, conversation, channel, and caller baggage that Agent 365 expects.
+Agent 365 is different. The Microsoft SDK owns the exporter and adds an Agent 365 span processor that copies baggage into span attributes. `agent-core` still emits the agent and AI SDK spans, while this package starts the Microsoft exporter and wraps each request with the tenant, agent, conversation, channel, and caller baggage that Agent 365 expects.
 
 ## AI SDK Telemetry
 
@@ -197,6 +220,8 @@ Agent 365 is different. The Microsoft SDK owns the exporter and adds an Agent 36
 
 This package does not replace that model telemetry. It adds the Microsoft Agent 365 layer: exporter startup, token resolution, and baggage that flows `microsoft.tenant.id`, `gen_ai.agent.id`, conversation, channel, and caller identity onto the spans.
 
+`createA365TracingConfig()` defaults `emitToolSpans` to `false`. AI SDK v7 already emits `execute_tool` spans with the Agent 365 GenAI tool keys, including `gen_ai.tool.name`, `gen_ai.tool.call.id`, `gen_ai.tool.call.arguments`, and `gen_ai.tool.call.result` when content recording is enabled. Disabling agent-core's extra tool-span layer avoids duplicate `execute_tool` spans for one tool call while preserving model and tool observability from the AI SDK integration.
+
 If you need to plug in another AI SDK telemetry integration, pass it through `createA365TracingConfig()`:
 
 ```typescript
@@ -212,6 +237,8 @@ const agent = createAgent({
 
 Set `useGenAIOpenTelemetry: false` only when you intentionally want to use global AI SDK telemetry integrations or another model-span integration.
 
+Set `emitToolSpans: true` only when your agent execution path does not use AI SDK v7 tool telemetry and you need agent-core to emit tool spans itself.
+
 ## TurnContext Mapping
 
 `runWithA365TurnContext(...)` follows Microsoft's

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 = {
@@ -125,6 +126,26 @@ type A365TracingConfigOptions = {
     agentId?: string;
     agentDescription?: string;
     agentVersion?: string;
+    /**
+     * Whether to record prompts/tool arguments in GenAI spans.
+     *
+     * Defaults to agent-core's tracing default.
+     */
+    recordInputs?: boolean;
+    /**
+     * Whether to record responses/tool results in GenAI spans.
+     *
+     * Defaults to agent-core's tracing default.
+     */
+    recordOutputs?: boolean;
+    /**
+     * Whether agent-core should emit its own `execute_tool` spans.
+     *
+     * Agent 365 defaults this to `false` because AI SDK v7's
+     * `GenAIOpenTelemetry` already emits A365-compatible tool spans. Keeping both
+     * enabled can produce duplicate `execute_tool` spans for one tool call.
+     */
+    emitToolSpans?: boolean;
     /**
      * Include tenant as a static span attribute. Prefer `runWithA365Context`
      * when tenant varies per request.
@@ -139,6 +160,9 @@ type A365TracingConfig = {
     agentId?: string;
     agentDescription?: string;
     agentVersion?: string;
+    recordInputs?: boolean;
+    recordOutputs?: boolean;
+    emitToolSpans?: boolean;
     useGenAIOpenTelemetry?: boolean;
     telemetryIntegrations?: TelemetryOptions["integrations"];
     useGlobalTelemetryIntegrations?: boolean;
@@ -301,6 +325,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 +383,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);
@@ -911,6 +1003,9 @@ function createA365TracingConfig(options = {}) {
     ...isNonEmpty(options.agentId) ? { agentId: options.agentId.trim() } : {},
     ...isNonEmpty(options.agentDescription) ? { agentDescription: options.agentDescription.trim() } : {},
     ...isNonEmpty(options.agentVersion) ? { agentVersion: options.agentVersion.trim() } : {},
+    ...options.recordInputs !== void 0 ? { recordInputs: options.recordInputs } : {},
+    ...options.recordOutputs !== void 0 ? { recordOutputs: options.recordOutputs } : {},
+    emitToolSpans: options.emitToolSpans ?? false,
     ...options.useGenAIOpenTelemetry !== void 0 ? { useGenAIOpenTelemetry: options.useGenAIOpenTelemetry } : {},
     ...options.telemetryIntegrations ? { telemetryIntegrations: options.telemetryIntegrations } : {},
     ...options.useGlobalTelemetryIntegrations !== void 0 ? {
@@ -1041,6 +1136,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/agent-core-otel.md

@@ -8,7 +8,7 @@ replace agent-core telemetry and it does not create agent-core spans itself.
 agent-core's OpenTelemetry middleware emits:
 
 - `invoke_agent` spans for agent turns;
-- `execute_tool` spans for tool calls;
+- optional `execute_tool` spans for tool calls when `emitToolSpans` is enabled;
 - AI SDK GenAI spans for model calls when AI SDK telemetry is enabled.
 
 The root agent span includes common GenAI attributes such as:
@@ -27,6 +27,14 @@ The root agent span includes common GenAI attributes such as:
 stable agent metadata. Per-request metadata belongs in baggage via
 `runWithA365Context(...)`.
 
+The A365 tracing adapter intentionally defaults `emitToolSpans` to `false`.
+AI SDK v7's `GenAIOpenTelemetry` integration already emits `execute_tool`
+spans for tool executions, and Microsoft's Agent 365 exporter recognizes those
+spans. Keeping both the AI SDK tool span and the agent-core tool span enabled
+can create duplicate `execute_tool` records for one tool call. Override
+`emitToolSpans: true` only for execution paths that do not use AI SDK v7 tool
+telemetry.
+
 ## What This Package Adds
 
 This package wraps the turn in Agent 365 baggage before agent-core starts its

package/docs/architecture.md

@@ -31,12 +31,14 @@ 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.
+3. agent-core emits `invoke_agent` spans and AI SDK v7 emits model and
+   `execute_tool` spans.
 
 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 +69,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/docs/microsoft-a365-observability.md

@@ -47,8 +47,7 @@ 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
-already emits equivalent agent and tool spans, and AI SDK telemetry covers model
-spans.
+already emits the agent span, and AI SDK telemetry covers model and tool spans.
 
 The main shape difference is `OutputScope`, which creates a separate
 `output_messages` span. agent-core currently records output messages on the

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

@@ -18,8 +18,8 @@ Microsoft's Node observability packages have three practical layers:
 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.
+agent spans and AI SDK v7 already emits model/tool spans, so this adapter
+focuses on startup, token resolution, and Agent 365 baggage.
 
 ## What We Use
 
@@ -45,7 +45,7 @@ resolution, and Agent 365 baggage.
 | 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.                                                     |
+| `ExecuteToolScope`      | Not used by default. | AI SDK v7 already emits Agent 365-shaped tool spans for agent-core tool calls.                                 |
 | `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.                           |

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

@@ -33,7 +33,9 @@ processor and an export processor. The baggage processor copies current Agent
 
 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.
+emits agent turn spans and AI SDK v7 emits model/tool spans. The A365 adapter
+defaults agent-core's extra `execute_tool` span layer off so one tool execution
+does not produce duplicate Agent 365 tool records.
 
 Per turn, the host or channel adapter calls `runWithA365Context(...)` or
 `runWithA365TurnContext(...)` before running `agent.chat(...)`. The adapter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-a365-observability",
-  "version": "4.6.0",
+  "version": "4.7.1",
   "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.1"
   },
   "peerDependencies": {
     "@cuylabs/agent-core": "^4.0.0",