@cuylabs/agent-microsoft-opentelemetry 4.8.0 → 4.8.1

package/README.md

@@ -15,10 +15,11 @@ Microsoft now publishes a consolidated OpenTelemetry distro at
 setup, Agent 365 exporter, Agent 365 baggage processor, Azure Monitor exporter,
 OTLP support, and supported Microsoft framework auto-instrumentation.
 
-`@cuylabs/agent-core` already emits AI SDK v7 GenAI telemetry for model and tool
-execution. This package bridges those agent-core spans into the Microsoft distro
-pipeline and supplies Agent 365 identity context, S2S token resolution, and
-request-scoped baggage.
+`@cuylabs/agent-core` owns the agent runtime, but Agent 365 has product-specific
+scope types for invocation, inference, tools, and output. This package bridges
+those two models: it starts official Microsoft A365 scopes from agent-core
+lifecycle events, runs turns with Agent 365 baggage, provides S2S token
+resolution, and lets the Microsoft distro export the resulting spans.
 
 ## Install
 
@@ -60,24 +61,31 @@ const observability = await initMicrosoftOpenTelemetry({
 });
 ```
 
-Pass `observability.tracing` to `createAgent({ tracing })`. Wrap channel turn
-sources with `createMicrosoftA365ObservedTurnSource()` so each turn runs with
-Agent 365 baggage, including tenant, agent, user, channel, conversation, and
-session attributes.
+Pass `observability.tracing` to `createAgent({ tracing })`. By default that
+tracing config installs the package's official A365 scope middleware:
+
+- `InvokeAgentScope` starts when the agent turn starts.
+- `InferenceScope` starts around each model step.
+- `ExecuteToolScope` starts for each agent-core tool call event.
+- `OutputScope` is emitted at turn completion.
+
+Wrap channel turn sources with `createMicrosoftA365ObservedTurnSource()` so each
+turn runs with Agent 365 baggage, including tenant, agent, user, channel,
+conversation, and session attributes.
 
 ## Environment Compatibility
 
 The S2S helpers understand the Agent 365 CLI-generated settings:
 
-| Variable | Purpose |
-| --- | --- |
-| `A365_OBSERVABILITY_TENANT_ID` or `agent365Observability__tenantId` | Tenant that owns the Agent 365 identity. |
-| `A365_OBSERVABILITY_AGENT_ID` or `agent365Observability__agentId` | Agent 365 agent identity service principal ID. |
-| `A365_OBSERVABILITY_CLIENT_ID` or `agent365Observability__clientId` | Blueprint application/client ID. |
+| Variable                                                                    | Purpose                                                         |
+| --------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `A365_OBSERVABILITY_TENANT_ID` or `agent365Observability__tenantId`         | Tenant that owns the Agent 365 identity.                        |
+| `A365_OBSERVABILITY_AGENT_ID` or `agent365Observability__agentId`           | Agent 365 agent identity service principal ID.                  |
+| `A365_OBSERVABILITY_CLIENT_ID` or `agent365Observability__clientId`         | Blueprint application/client ID.                                |
 | `A365_OBSERVABILITY_CLIENT_SECRET` or `agent365Observability__clientSecret` | Blueprint client secret. Store this in Key Vault in production. |
-| `ENABLE_A365_OBSERVABILITY_EXPORTER` | Enables export to Agent 365. |
-| `A365_OBSERVABILITY_USE_S2S_ENDPOINT` | Uses the S2S Agent 365 ingestion path. |
-| `A365_OBSERVABILITY_LOG_LEVEL` | Microsoft distro Agent 365 log level. |
+| `ENABLE_A365_OBSERVABILITY_EXPORTER`                                        | Enables export to Agent 365.                                    |
+| `A365_OBSERVABILITY_USE_S2S_ENDPOINT`                                       | Uses the S2S Agent 365 ingestion path.                          |
+| `A365_OBSERVABILITY_LOG_LEVEL`                                              | Microsoft distro Agent 365 log level.                           |
 
 The package also accepts standard OpenTelemetry resource variables such as
 `OTEL_SERVICE_NAME` and `OTEL_SERVICE_VERSION`.
@@ -116,7 +124,7 @@ initialization without changing the command line.
 The adapter is `agent-core` first. Its default profile is `agent-core`, which
 keeps Microsoft exporters and processors active while disabling Microsoft's
 optional OpenAI Agents SDK and LangChain auto-instrumentations. `agent-core`
-already emits the AI SDK v7 telemetry used by `agents-ts`.
+execution is represented through the adapter's official A365 scope middleware.
 
 Use `instrumentationProfile: "microsoft-genai"` only when the same Node process
 also runs Microsoft's supported OpenAI Agents SDK or LangChain integrations. Use
@@ -146,25 +154,32 @@ adapters should use `createMicrosoftA365ObservedTurnSource()` instead.
 
 ## Package Boundary
 
-This package does not replace `agent-core` telemetry. Instead:
+This package does not replace `agent-core` execution. Instead:
+
+- `agent-core` runs the turn, model loop, tools, approvals, and event stream.
+- This package converts those lifecycle hooks into official A365 scopes.
+- `@microsoft/opentelemetry` owns the provider, span processors, exporters,
+  Azure Monitor, OTLP, and Agent 365 HTTP exporter.
 
-- `agent-core` creates the agent invocation/model/tool spans.
-- `@microsoft/opentelemetry` owns the provider/exporter pipeline.
-- This package maps Agent 365 identity and request metadata into baggage and
-  returns `agent-core` tracing defaults that avoid duplicate tool spans.
+The default tracing config disables agent-core's older generic OTel middleware
+and the local AI SDK GenAI integration so one `agents-ts` turn produces one
+official A365 scope tree. Applications can opt back into those lower-level
+spans with `useA365Scopes: false`, `useDefaultOtelMiddleware: true`, or
+`useGenAIOpenTelemetry: true`, but those settings should be deliberate because
+they can duplicate tool or model telemetry.
 
 ## Source Layout
 
 The source tree mirrors the adapter's ownership boundaries, not the full
 Microsoft distro implementation:
 
-| Folder | Owns |
-| --- | --- |
-| `src/a365` | Agent 365 request context, baggage attributes, and turn-source wrappers. |
-| `src/auth` | S2S token exchange and Agent 365 CLI environment compatibility. |
-| `src/runtime` | Microsoft distro startup, loader integration, destination helpers, instrumentation profiles, and exporter options. |
-| `src/tracing` | `agent-core` tracing defaults for Microsoft-backed pipelines. |
-| `src/common` and `src/internal` | Shared public types and package-private utilities. |
+| Folder                          | Owns                                                                                                               |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `src/a365`                      | Agent 365 request context, baggage attributes, official scope middleware, and turn-source wrappers.                |
+| `src/auth`                      | S2S token exchange and Agent 365 CLI environment compatibility.                                                    |
+| `src/runtime`                   | Microsoft distro startup, loader integration, destination helpers, instrumentation profiles, and exporter options. |
+| `src/tracing`                   | `agent-core` tracing defaults for Microsoft-backed pipelines.                                                      |
+| `src/common` and `src/internal` | Shared public types and package-private utilities.                                                                 |
 
 For details, see [docs/architecture.md](./docs/architecture.md).
 For a direct mapping to Microsoft's distro documentation, see

package/dist/{chunk-S7XVXBY3.js → chunk-K54CB7U4.js}

@@ -610,6 +610,16 @@ function buildMicrosoftA365BaggagePairs(context) {
   return pairs;
 }
 
+// src/a365/context-store.ts
+import { AsyncLocalStorage } from "async_hooks";
+var microsoftA365RequestContextStorage = new AsyncLocalStorage();
+function currentMicrosoftA365RequestContext() {
+  return microsoftA365RequestContextStorage.getStore();
+}
+function runWithMicrosoftA365RequestContext(requestContext, fn) {
+  return microsoftA365RequestContextStorage.run(requestContext, fn);
+}
+
 // src/runtime/module-loader.ts
 var MICROSOFT_OPENTELEMETRY_PACKAGE = "@microsoft/opentelemetry";
 var OTEL_RESOURCES_PACKAGE = "@opentelemetry/resources";
@@ -640,6 +650,400 @@ async function loadOpenTelemetryResourceModule(options = {}) {
   }
 }
 
+// src/a365/scope-middleware.ts
+import { context as otelContext } from "@opentelemetry/api";
+function createMicrosoftA365ScopeMiddleware(options = {}) {
+  const recordInputs = options.recordInputs ?? true;
+  const recordOutputs = options.recordOutputs ?? true;
+  const emitOutputScope = options.emitOutputScope ?? true;
+  const states = /* @__PURE__ */ new Map();
+  const statesByRequestContext = /* @__PURE__ */ new WeakMap();
+  return {
+    name: "microsoft-a365-scopes",
+    async onChatStart(sessionId, message, ctx) {
+      const requestContext = currentMicrosoftA365RequestContext();
+      if (!requestContext || !hasA365ScopeIdentity(requestContext)) {
+        return;
+      }
+      const module = await loadMicrosoftOpenTelemetryModule(options.runtime);
+      if (!module.InvokeAgentScope) {
+        return;
+      }
+      const scopedRequestContext = {
+        ...requestContext,
+        sessionId: requestContext.sessionId ?? sessionId,
+        conversationId: requestContext.conversationId ?? sessionId
+      };
+      const scope = safeStartScope(
+        () => module.InvokeAgentScope.start(
+          createRequest(scopedRequestContext, {
+            sessionId,
+            content: recordInputs ? message : void 0
+          }),
+          createInvokeScopeDetails(scopedRequestContext),
+          createAgentDetails(scopedRequestContext),
+          createCallerDetails(scopedRequestContext)
+        )
+      );
+      if (!scope) {
+        return;
+      }
+      const state = {
+        module,
+        requestContext: scopedRequestContext,
+        invokeScope: scope,
+        invokeContext: createOtelContext(module, scope.getSpanContext()),
+        inferenceScopes: /* @__PURE__ */ new Map(),
+        toolScopes: /* @__PURE__ */ new Map()
+      };
+      states.set(turnKey(sessionId, ctx?.turnId), state);
+      statesByRequestContext.set(requestContext, state);
+      statesByRequestContext.set(scopedRequestContext, state);
+    },
+    model: {
+      async input(input, ctx) {
+        const state = findState(states, ctx.sessionID, ctx.turnID);
+        if (!state?.module.InferenceScope) {
+          return void 0;
+        }
+        const key = modelKey(ctx);
+        disposeInferenceScope(state, key);
+        const messages = recordInputs ? inputMessages(input) : void 0;
+        const scope = safeStartScope(
+          () => state.module.InferenceScope.start(
+            createRequest(state.requestContext, {
+              sessionId: ctx.sessionID,
+              content: messages
+            }),
+            {
+              operationName: state.module.InferenceOperationType?.CHAT ?? "Chat",
+              model: modelName(input.model),
+              providerName: providerName(input.model)
+            },
+            createAgentDetails(state.requestContext),
+            createUserDetails(state.requestContext),
+            createSpanDetails(state.invokeScope)
+          )
+        );
+        if (!scope) {
+          return void 0;
+        }
+        if (messages && messages.length > 0) {
+          scope.recordInputMessages?.(messages);
+        }
+        state.inferenceScopes.set(key, {
+          scope,
+          otelContext: createOtelContext(state.module, scope.getSpanContext())
+        });
+        return void 0;
+      },
+      async output(output, ctx) {
+        const state = findState(states, ctx.sessionID, ctx.turnID);
+        const scopeState = state?.inferenceScopes.get(modelKey(ctx));
+        const scope = scopeState?.scope;
+        if (!state || !scope) {
+          return void 0;
+        }
+        if (recordOutputs && output.text) {
+          scope.recordOutputMessages?.(output.text);
+        }
+        if (output.usage?.inputTokens !== void 0) {
+          scope.recordInputTokens?.(output.usage.inputTokens);
+        }
+        if (output.usage?.outputTokens !== void 0) {
+          scope.recordOutputTokens?.(output.usage.outputTokens);
+        }
+        if (output.finishReason) {
+          scope.recordFinishReasons?.([output.finishReason]);
+        }
+        disposeInferenceScope(state, modelKey(ctx));
+        return output;
+      }
+    },
+    onEvent(event) {
+      const state = currentState(states, statesByRequestContext);
+      if (!state) {
+        return;
+      }
+      if (event.type === "tool-start") {
+        startToolScope(state, event, recordInputs);
+        return;
+      }
+      if (event.type === "tool-result") {
+        finishToolScope(state, event, recordOutputs);
+        return;
+      }
+      if (event.type === "tool-error") {
+        finishToolScopeWithError(state, event);
+        return;
+      }
+      if (event.type === "error") {
+        for (const key of state.inferenceScopes.keys()) {
+          const scope = state.inferenceScopes.get(key)?.scope;
+          scope?.recordError(event.error);
+          scope?.dispose();
+        }
+        state.inferenceScopes.clear();
+      }
+    },
+    async onChatEnd(sessionId, result, ctx) {
+      const key = turnKey(sessionId, ctx?.turnId);
+      const state = states.get(key) ?? currentState(states, statesByRequestContext);
+      if (!state) {
+        return;
+      }
+      for (const scopeState of state.inferenceScopes.values()) {
+        if (result.error) {
+          scopeState.scope.recordError(result.error);
+        }
+        scopeState.scope.dispose();
+      }
+      state.inferenceScopes.clear();
+      for (const scope of state.toolScopes.values()) {
+        if (result.error) {
+          scope.recordError(result.error);
+        }
+        scope.dispose();
+      }
+      state.toolScopes.clear();
+      if (result.error) {
+        state.invokeScope?.recordError(result.error);
+      } else if (recordOutputs && result.output) {
+        state.invokeScope?.recordResponse?.(result.output);
+      }
+      if (emitOutputScope && recordOutputs && result.output && state.module.OutputScope) {
+        const outputScope = safeStartScope(
+          () => state.module.OutputScope.start(
+            createRequest(state.requestContext, { sessionId }),
+            { messages: result.output },
+            createAgentDetails(state.requestContext),
+            createUserDetails(state.requestContext),
+            createSpanDetails(state.invokeScope)
+          )
+        );
+        outputScope?.dispose();
+      }
+      state.invokeScope?.dispose();
+      states.delete(key);
+      const requestContext = currentMicrosoftA365RequestContext();
+      if (requestContext) {
+        statesByRequestContext.delete(requestContext);
+      }
+      statesByRequestContext.delete(state.requestContext);
+    },
+    getOtelContext(sessionId, ctx) {
+      const state = findState(states, sessionId, ctx?.turnId);
+      if (!state) {
+        return void 0;
+      }
+      const inferenceContext = latestInferenceContext(state);
+      return inferenceContext ?? state.invokeContext;
+    }
+  };
+}
+function hasA365ScopeIdentity(context) {
+  return Boolean(context.tenantId && context.agentId);
+}
+function safeStartScope(start) {
+  try {
+    return start();
+  } catch {
+    return void 0;
+  }
+}
+function currentState(states, statesByRequestContext) {
+  const requestContext = currentMicrosoftA365RequestContext();
+  if (requestContext) {
+    const state = statesByRequestContext.get(requestContext);
+    if (state) {
+      return state;
+    }
+    if (requestContext.sessionId) {
+      return findState(states, requestContext.sessionId);
+    }
+  }
+  return latestState(states);
+}
+function startToolScope(state, event, recordInputs) {
+  if (!state.module.ExecuteToolScope) {
+    return;
+  }
+  const scope = safeStartScope(
+    () => state.module.ExecuteToolScope.start(
+      createRequest(state.requestContext),
+      {
+        toolName: event.toolName,
+        arguments: recordInputs ? safeJsonStringify(event.input) : void 0,
+        toolCallId: event.toolCallId,
+        toolType: "function"
+      },
+      createAgentDetails(state.requestContext),
+      createUserDetails(state.requestContext),
+      createSpanDetails(latestInferenceScope(state) ?? state.invokeScope)
+    )
+  );
+  if (!scope) {
+    return;
+  }
+  state.toolScopes.set(toolKey(event.toolName, event.toolCallId), scope);
+}
+function finishToolScope(state, event, recordOutputs) {
+  const key = toolKey(event.toolName, event.toolCallId);
+  const scope = state.toolScopes.get(key);
+  if (!scope) {
+    return;
+  }
+  if (recordOutputs) {
+    scope.recordResponse?.(safeJsonStringify(event.result));
+  }
+  scope.dispose();
+  state.toolScopes.delete(key);
+}
+function finishToolScopeWithError(state, event) {
+  const key = toolKey(event.toolName, event.toolCallId);
+  const scope = state.toolScopes.get(key);
+  if (!scope) {
+    return;
+  }
+  scope.recordError(new Error(event.error));
+  scope.dispose();
+  state.toolScopes.delete(key);
+}
+function disposeInferenceScope(state, key) {
+  const scope = state.inferenceScopes.get(key)?.scope;
+  if (scope) {
+    scope.dispose();
+    state.inferenceScopes.delete(key);
+  }
+}
+function latestInferenceScope(state) {
+  return Array.from(state.inferenceScopes.values()).at(-1)?.scope;
+}
+function latestInferenceContext(state) {
+  return Array.from(state.inferenceScopes.values()).at(-1)?.otelContext;
+}
+function createSpanDetails(scope) {
+  return scope ? { parentContext: scope.getSpanContext() } : void 0;
+}
+function createOtelContext(module, parent) {
+  return module.createContextWithParentSpanRef?.(otelContext.active(), parent);
+}
+function createRequest(context, options = {}) {
+  return {
+    ...options.content !== void 0 ? { content: options.content } : {},
+    sessionId: options.sessionId ?? context.sessionId,
+    conversationId: context.conversationId ?? options.sessionId,
+    ...context.channelName || context.channelLink ? {
+      channel: {
+        name: context.channelName,
+        description: context.channelLink
+      }
+    } : {}
+  };
+}
+function createInvokeScopeDetails(context) {
+  return {
+    ...context.serverAddress ? {
+      endpoint: {
+        host: context.serverAddress,
+        ...context.serverPort ? { port: context.serverPort } : {}
+      }
+    } : {}
+  };
+}
+function createAgentDetails(context) {
+  return {
+    agentId: context.agentId ?? "unknown",
+    agentName: context.agentName,
+    agentDescription: context.agentDescription,
+    agentVersion: context.agentVersion,
+    platformId: context.agentPlatformId,
+    agentAUID: context.agentAuid,
+    agentEmail: context.agentEmail,
+    agentBlueprintId: context.agentBlueprintId,
+    tenantId: context.tenantId
+  };
+}
+function createCallerDetails(context) {
+  const userDetails = createUserDetails(context);
+  const callerAgentDetails = context.callerAgentId || context.callerAgentName ? {
+    agentId: context.callerAgentId ?? "unknown",
+    agentName: context.callerAgentName,
+    agentAUID: context.callerAgentAuid,
+    agentEmail: context.callerAgentEmail,
+    agentBlueprintId: context.callerAgentBlueprintId,
+    platformId: context.callerAgentPlatformId,
+    agentVersion: context.callerAgentVersion,
+    tenantId: context.tenantId
+  } : void 0;
+  return userDetails || callerAgentDetails ? {
+    ...userDetails ? { userDetails } : {},
+    ...callerAgentDetails ? { callerAgentDetails } : {}
+  } : void 0;
+}
+function createUserDetails(context) {
+  return context.userId || context.userEmail || context.userName || context.callerClientIp ? {
+    userId: context.userId,
+    userEmail: context.userEmail,
+    userName: context.userName,
+    callerClientIp: context.callerClientIp
+  } : void 0;
+}
+function inputMessages(input) {
+  return [
+    ...input.system,
+    ...input.messages.map((message) => safeJsonStringify(message))
+  ].filter(Boolean);
+}
+function modelName(model) {
+  if (model && typeof model === "object" && "modelId" in model) {
+    return String(model.modelId ?? "unknown");
+  }
+  return String(model ?? "unknown");
+}
+function providerName(model) {
+  if (model && typeof model === "object" && "provider" in model) {
+    return String(model.provider ?? "") || void 0;
+  }
+  return void 0;
+}
+function safeJsonStringify(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+function turnKey(sessionId, turnId) {
+  return `${sessionId}:${turnId ?? ""}`;
+}
+function modelKey(ctx) {
+  return `${turnKey(ctx.sessionID, ctx.turnID)}:${ctx.step}`;
+}
+function toolKey(toolName, toolCallId) {
+  return `${toolName}:${toolCallId}`;
+}
+function findState(states, sessionId, turnId) {
+  const exact = states.get(turnKey(sessionId, turnId)) ?? states.get(turnKey(sessionId));
+  if (exact || turnId) {
+    return exact;
+  }
+  const prefix = `${sessionId}:`;
+  let latest;
+  for (const [key, state] of states) {
+    if (key.startsWith(prefix)) {
+      latest = state;
+    }
+  }
+  return latest;
+}
+function latestState(states) {
+  return Array.from(states.values()).at(-1);
+}
+
 // src/tracing/tracing-config.ts
 function createMicrosoftOpenTelemetryTracingConfig(options = {}) {
   const spanAttributes = {
@@ -648,6 +1052,7 @@ function createMicrosoftOpenTelemetryTracingConfig(options = {}) {
   if (isNonEmpty(options.tenantId)) {
     spanAttributes[MICROSOFT_A365_ATTRIBUTES.tenantId] = options.tenantId.trim();
   }
+  const useA365Scopes = options.useA365Scopes ?? true;
   return {
     ...isNonEmpty(options.agentId) ? { agentId: options.agentId.trim() } : {},
     ...isNonEmpty(options.agentDescription) ? { agentDescription: options.agentDescription.trim() } : {},
@@ -655,11 +1060,15 @@ function createMicrosoftOpenTelemetryTracingConfig(options = {}) {
     ...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 } : {},
+    useGenAIOpenTelemetry: options.useGenAIOpenTelemetry ?? (useA365Scopes ? false : true),
     ...options.telemetryIntegrations ? { telemetryIntegrations: options.telemetryIntegrations } : {},
     ...options.useGlobalTelemetryIntegrations !== void 0 ? {
       useGlobalTelemetryIntegrations: options.useGlobalTelemetryIntegrations
     } : {},
+    ...useA365Scopes ? {
+      middleware: createMicrosoftA365ScopeMiddleware(options.a365Scopes),
+      useDefaultOtelMiddleware: options.useDefaultOtelMiddleware ?? false
+    } : options.useDefaultOtelMiddleware !== void 0 ? { useDefaultOtelMiddleware: options.useDefaultOtelMiddleware } : {},
     ...Object.keys(spanAttributes).length > 0 ? { spanAttributes } : {}
   };
 }
@@ -793,10 +1202,10 @@ async function initMicrosoftOpenTelemetryFromEnv(options = {}) {
 }
 async function runWithMicrosoftA365Context(requestContext, fn, options = {}) {
   const module = await loadMicrosoftOpenTelemetryModule(options);
-  const runWithBaggage = () => {
+  const runWithBaggage = () => runWithMicrosoftA365RequestContext(requestContext, () => {
     const scope = new module.BaggageBuilder().setPairs(buildMicrosoftA365BaggagePairs(requestContext)).build();
     return scope.run(fn);
-  };
+  });
   const result = requestContext.exportToken && module.runWithExportToken ? module.runWithExportToken(requestContext.exportToken, runWithBaggage) : runWithBaggage();
   return await result;
 }
@@ -951,8 +1360,11 @@ export {
   createEnvReader,
   MICROSOFT_A365_ATTRIBUTES,
   buildMicrosoftA365BaggagePairs,
+  currentMicrosoftA365RequestContext,
+  runWithMicrosoftA365RequestContext,
   loadMicrosoftOpenTelemetryModule,
   loadOpenTelemetryResourceModule,
+  createMicrosoftA365ScopeMiddleware,
   createMicrosoftOpenTelemetryTracingConfig,
   createMicrosoftOpenTelemetryInstrumentationOptions,
   normalizeInstrumentationProfile,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { TelemetryOptions } from 'ai';
-import { AgentTurnSourceChatOptions, AgentTurnSource } from '@cuylabs/agent-core';
+import { AgentMiddleware, AgentTurnSourceChatOptions, AgentTurnSource } from '@cuylabs/agent-core';
 
 type MicrosoftOpenTelemetryTokenResolver = (agentId: string, tenantId: string, authScopes?: string[]) => string | null | Promise<string | null>;
 type MicrosoftOpenTelemetryLogger = {
@@ -25,6 +25,13 @@ type MicrosoftOpenTelemetryTracingConfigOptions = {
     telemetryIntegrations?: TelemetryOptions["integrations"];
     useGlobalTelemetryIntegrations?: boolean;
     spanAttributes?: Record<string, SpanAttributeValue>;
+    /**
+     * Use official Agent 365 scopes for invoke, inference, tool, and output
+     * telemetry. Defaults to true.
+     */
+    useA365Scopes?: boolean;
+    a365Scopes?: Omit<MicrosoftA365ScopeMiddlewareOptions, "runtime">;
+    useDefaultOtelMiddleware?: boolean;
 };
 type MicrosoftOpenTelemetryTracingConfig = {
     agentId?: string;
@@ -37,6 +44,8 @@ type MicrosoftOpenTelemetryTracingConfig = {
     telemetryIntegrations?: TelemetryOptions["integrations"];
     useGlobalTelemetryIntegrations?: boolean;
     spanAttributes?: Record<string, SpanAttributeValue>;
+    middleware?: AgentMiddleware | AgentMiddleware[];
+    useDefaultOtelMiddleware?: boolean;
 };
 
 type MicrosoftOpenTelemetryResourceOptions = {
@@ -145,6 +154,16 @@ type MicrosoftOpenTelemetryDistroModule = {
     useMicrosoftOpenTelemetry(options?: Record<string, unknown>): void;
     shutdownMicrosoftOpenTelemetry(): Promise<void>;
     BaggageBuilder: new () => MicrosoftBaggageBuilderLike;
+    InvokeAgentScope?: MicrosoftA365InvokeAgentScopeConstructor;
+    ExecuteToolScope?: MicrosoftA365ExecuteToolScopeConstructor;
+    InferenceScope?: MicrosoftA365InferenceScopeConstructor;
+    OutputScope?: MicrosoftA365OutputScopeConstructor;
+    InferenceOperationType?: {
+        CHAT?: string;
+        TEXT_COMPLETION?: string;
+        GENERATE_CONTENT?: string;
+    };
+    createContextWithParentSpanRef?: (baseContext: unknown, parent: MicrosoftA365ParentSpanRef) => unknown;
     runWithExportToken?: <T>(token: string, fn: () => T) => T;
     updateExportToken?: (token: string) => boolean;
     configureA365Hosting?: (adapter: MicrosoftA365HostingAdapterLike, options?: MicrosoftA365HostingOptions) => unknown;
@@ -161,6 +180,35 @@ type MicrosoftBaggageBuilderLike = {
         run<T>(fn: () => T): T;
     };
 };
+type MicrosoftA365ParentSpanRef = {
+    traceId: string;
+    spanId: string;
+    traceFlags?: number;
+    traceState?: unknown;
+    isRemote?: boolean;
+};
+type MicrosoftA365ScopeLike = {
+    getSpanContext(): MicrosoftA365ParentSpanRef;
+    withActiveSpanAsync?<T>(callback: () => Promise<T>): Promise<T>;
+    recordError(error: Error): void;
+    recordInputMessages?(messages: string | string[]): void;
+    recordOutputMessages?(messages: string | string[]): void;
+    recordResponse?(response: string | Record<string, unknown>): void;
+    recordInputTokens?(tokens: number): void;
+    recordOutputTokens?(tokens: number): void;
+    recordFinishReasons?(reasons: string[]): void;
+    dispose(): void;
+};
+type MicrosoftA365InvokeAgentScopeConstructor = {
+    start(request: Record<string, unknown>, details: Record<string, unknown>, agentDetails: Record<string, unknown>, callerDetails?: Record<string, unknown>, spanDetails?: Record<string, unknown>): MicrosoftA365ScopeLike;
+};
+type MicrosoftA365ExecuteToolScopeConstructor = {
+    start(request: Record<string, unknown>, details: Record<string, unknown>, agentDetails: Record<string, unknown>, userDetails?: Record<string, unknown>, spanDetails?: Record<string, unknown>): MicrosoftA365ScopeLike;
+};
+type MicrosoftA365InferenceScopeConstructor = MicrosoftA365ExecuteToolScopeConstructor;
+type MicrosoftA365OutputScopeConstructor = {
+    start(request: Record<string, unknown>, response: Record<string, unknown>, agentDetails: Record<string, unknown>, userDetails?: Record<string, unknown>, spanDetails?: Record<string, unknown>): MicrosoftA365ScopeLike;
+};
 
 type MicrosoftOpenTelemetryA365Options = {
     /**
@@ -248,6 +296,25 @@ type MicrosoftA365RequestContext = {
     exportToken?: string;
     extraBaggage?: Record<string, string | number | boolean | null | undefined>;
 };
+type MicrosoftA365ScopeMiddlewareOptions = {
+    /**
+     * Capture prompt/user content on invoke and inference scopes.
+     *
+     * Defaults to true to match Agent 365 validation expectations. Disable for
+     * deployments that must export metadata only.
+     */
+    recordInputs?: boolean;
+    /**
+     * Capture response/tool result content on invoke, inference, tool, and output
+     * scopes. Defaults to true.
+     */
+    recordOutputs?: boolean;
+    /**
+     * Emit an `OutputScope` at turn completion in addition to recording the
+     * response on the invoke scope. Defaults to true.
+     */
+    emitOutputScope?: boolean;
+};
 type MicrosoftA365ActivityAccountLike = {
     id?: string;
     name?: string;
@@ -377,6 +444,9 @@ declare const MICROSOFT_A365_ATTRIBUTES: {
 
 declare function buildMicrosoftA365BaggagePairs(context: MicrosoftA365RequestContext): Record<string, string>;
 
+declare function currentMicrosoftA365RequestContext(): MicrosoftA365RequestContext | undefined;
+declare function runWithMicrosoftA365RequestContext<T>(requestContext: MicrosoftA365RequestContext, fn: () => T): T;
+
 /**
  * Registers Microsoft's A365 hosting middleware on a TurnContext-style adapter.
  *
@@ -386,6 +456,11 @@ declare function buildMicrosoftA365BaggagePairs(context: MicrosoftA365RequestCon
  */
 declare function configureMicrosoftA365Hosting(adapter: MicrosoftA365HostingAdapterLike, options?: MicrosoftA365HostingConfigurationOptions): Promise<unknown>;
 
+type MicrosoftA365ScopeMiddlewareConfig = MicrosoftA365ScopeMiddlewareOptions & {
+    runtime?: MicrosoftOpenTelemetryRuntimeOptions;
+};
+declare function createMicrosoftA365ScopeMiddleware(options?: MicrosoftA365ScopeMiddlewareConfig): AgentMiddleware;
+
 declare function createMicrosoftA365ContextFromTurnContext(turnContext: MicrosoftA365TurnContextLike, options?: MicrosoftA365TurnContextOptions): MicrosoftA365RequestContext;
 
 type MicrosoftA365ObservedTurnSourceContextInput = {
@@ -437,4 +512,4 @@ declare function loadOpenTelemetryResourceModule(options?: MicrosoftOpenTelemetr
 
 declare function createMicrosoftOpenTelemetryTracingConfig(options?: MicrosoftOpenTelemetryTracingConfigOptions): MicrosoftOpenTelemetryTracingConfig;
 
-export { MICROSOFT_A365_ATTRIBUTES, MICROSOFT_A365_FMI_SCOPE, MICROSOFT_A365_OBSERVABILITY_SCOPE, type MicrosoftA365ActivityAccountLike, type MicrosoftA365ActivityLike, type MicrosoftA365HostingAdapterLike, type MicrosoftA365HostingConfigurationOptions, type MicrosoftA365HostingOptions, type MicrosoftA365ObservedTurnSourceContextFactory, type MicrosoftA365ObservedTurnSourceContextInput, type MicrosoftA365ObservedTurnSourceOptions, type MicrosoftA365RequestContext, type MicrosoftA365S2STokenResolver, type MicrosoftA365S2STokenResolverFromEnvOptions, type MicrosoftA365S2STokenResolverLogger, type MicrosoftA365S2STokenResolverOptions, type MicrosoftA365TurnContextLike, type MicrosoftA365TurnContextOptions, type MicrosoftBaggageBuilderLike, type MicrosoftLangChainInstrumentationOptions, type MicrosoftManagedIdentityAssertionProvider, type MicrosoftOpenAIAgentsInstrumentationOptions, type MicrosoftOpenTelemetryA365Options, type MicrosoftOpenTelemetryAzureMonitorOptions, type MicrosoftOpenTelemetryDestinationSummary, type MicrosoftOpenTelemetryDistroModule, type MicrosoftOpenTelemetryEnvironment, type MicrosoftOpenTelemetryHandle, type MicrosoftOpenTelemetryInstrumentationConfig, type MicrosoftOpenTelemetryInstrumentationOptions, type MicrosoftOpenTelemetryInstrumentationProfile, type MicrosoftOpenTelemetryLogger, MicrosoftOpenTelemetryModuleLoadError, type MicrosoftOpenTelemetryOptions, type MicrosoftOpenTelemetryResolvedEnvironment, type MicrosoftOpenTelemetryResourceModule, MicrosoftOpenTelemetryResourceModuleLoadError, type MicrosoftOpenTelemetryResourceOptions, type MicrosoftOpenTelemetryRuntimeOptions, type MicrosoftOpenTelemetryTokenResolver, type MicrosoftOpenTelemetryTracingConfig, type MicrosoftOpenTelemetryTracingConfigOptions, type SpanAttributeValue, buildMicrosoftA365BaggagePairs, configureMicrosoftA365Hosting, createAzureMonitorOptionsFromEnv, createEnvReader, createMicrosoftA365ContextFromTurnContext, createMicrosoftA365ObservedTurnSource, createMicrosoftA365S2STokenResolver, createMicrosoftA365S2STokenResolverFromEnv, createMicrosoftOpenTelemetryInstrumentationOptions, createMicrosoftOpenTelemetryTracingConfig, initMicrosoftOpenTelemetry, initMicrosoftOpenTelemetryFromEnv, isAzureMonitorEnvironmentEnabled, isMicrosoftOtlpEnvironmentEnabled, loadMicrosoftOpenTelemetryModule, loadOpenTelemetryResourceModule, mergeInstrumentationOptions, normalizeInstrumentationProfile, resolveMicrosoftOpenTelemetryBooleanEnv, resolveMicrosoftOpenTelemetryEnvironment, resolveMicrosoftOpenTelemetryNumberEnv, runWithMicrosoftA365Context, summarizeMicrosoftOpenTelemetryDestinations, updateMicrosoftA365ExportToken };
+export { MICROSOFT_A365_ATTRIBUTES, MICROSOFT_A365_FMI_SCOPE, MICROSOFT_A365_OBSERVABILITY_SCOPE, type MicrosoftA365ActivityAccountLike, type MicrosoftA365ActivityLike, type MicrosoftA365ExecuteToolScopeConstructor, type MicrosoftA365HostingAdapterLike, type MicrosoftA365HostingConfigurationOptions, type MicrosoftA365HostingOptions, type MicrosoftA365InferenceScopeConstructor, type MicrosoftA365InvokeAgentScopeConstructor, type MicrosoftA365ObservedTurnSourceContextFactory, type MicrosoftA365ObservedTurnSourceContextInput, type MicrosoftA365ObservedTurnSourceOptions, type MicrosoftA365OutputScopeConstructor, type MicrosoftA365ParentSpanRef, type MicrosoftA365RequestContext, type MicrosoftA365S2STokenResolver, type MicrosoftA365S2STokenResolverFromEnvOptions, type MicrosoftA365S2STokenResolverLogger, type MicrosoftA365S2STokenResolverOptions, type MicrosoftA365ScopeLike, type MicrosoftA365ScopeMiddlewareConfig, type MicrosoftA365ScopeMiddlewareOptions, type MicrosoftA365TurnContextLike, type MicrosoftA365TurnContextOptions, type MicrosoftBaggageBuilderLike, type MicrosoftLangChainInstrumentationOptions, type MicrosoftManagedIdentityAssertionProvider, type MicrosoftOpenAIAgentsInstrumentationOptions, type MicrosoftOpenTelemetryA365Options, type MicrosoftOpenTelemetryAzureMonitorOptions, type MicrosoftOpenTelemetryDestinationSummary, type MicrosoftOpenTelemetryDistroModule, type MicrosoftOpenTelemetryEnvironment, type MicrosoftOpenTelemetryHandle, type MicrosoftOpenTelemetryInstrumentationConfig, type MicrosoftOpenTelemetryInstrumentationOptions, type MicrosoftOpenTelemetryInstrumentationProfile, type MicrosoftOpenTelemetryLogger, MicrosoftOpenTelemetryModuleLoadError, type MicrosoftOpenTelemetryOptions, type MicrosoftOpenTelemetryResolvedEnvironment, type MicrosoftOpenTelemetryResourceModule, MicrosoftOpenTelemetryResourceModuleLoadError, type MicrosoftOpenTelemetryResourceOptions, type MicrosoftOpenTelemetryRuntimeOptions, type MicrosoftOpenTelemetryTokenResolver, type MicrosoftOpenTelemetryTracingConfig, type MicrosoftOpenTelemetryTracingConfigOptions, type SpanAttributeValue, buildMicrosoftA365BaggagePairs, configureMicrosoftA365Hosting, createAzureMonitorOptionsFromEnv, createEnvReader, createMicrosoftA365ContextFromTurnContext, createMicrosoftA365ObservedTurnSource, createMicrosoftA365S2STokenResolver, createMicrosoftA365S2STokenResolverFromEnv, createMicrosoftA365ScopeMiddleware, createMicrosoftOpenTelemetryInstrumentationOptions, createMicrosoftOpenTelemetryTracingConfig, currentMicrosoftA365RequestContext, initMicrosoftOpenTelemetry, initMicrosoftOpenTelemetryFromEnv, isAzureMonitorEnvironmentEnabled, isMicrosoftOtlpEnvironmentEnabled, loadMicrosoftOpenTelemetryModule, loadOpenTelemetryResourceModule, mergeInstrumentationOptions, normalizeInstrumentationProfile, resolveMicrosoftOpenTelemetryBooleanEnv, resolveMicrosoftOpenTelemetryEnvironment, resolveMicrosoftOpenTelemetryNumberEnv, runWithMicrosoftA365Context, runWithMicrosoftA365RequestContext, summarizeMicrosoftOpenTelemetryDestinations, updateMicrosoftA365ExportToken };

package/dist/index.js

@@ -10,8 +10,10 @@ import {
   createEnvReader,
   createMicrosoftA365S2STokenResolver,
   createMicrosoftA365S2STokenResolverFromEnv,
+  createMicrosoftA365ScopeMiddleware,
   createMicrosoftOpenTelemetryInstrumentationOptions,
   createMicrosoftOpenTelemetryTracingConfig,
+  currentMicrosoftA365RequestContext,
   firstNonEmpty,
   initMicrosoftOpenTelemetry,
   initMicrosoftOpenTelemetryFromEnv,
@@ -25,8 +27,9 @@ import {
   resolveMicrosoftOpenTelemetryEnvironment,
   resolveMicrosoftOpenTelemetryNumberEnv,
   runWithMicrosoftA365Context,
+  runWithMicrosoftA365RequestContext,
   updateMicrosoftA365ExportToken
-} from "./chunk-S7XVXBY3.js";
+} from "./chunk-K54CB7U4.js";
 
 // src/a365/hosting.ts
 async function configureMicrosoftA365Hosting(adapter, options = {}) {
@@ -239,10 +242,15 @@ function createMicrosoftA365ObservedTurnSource({
         message,
         options
       });
+      const scopedRequestContext = {
+        ...requestContext,
+        sessionId: requestContext.sessionId ?? sessionId,
+        conversationId: requestContext.conversationId ?? sessionId
+      };
       const queue = new AsyncQueue();
       let failure;
       void runWithMicrosoftA365Context(
-        requestContext,
+        scopedRequestContext,
         async () => {
           try {
             for await (const event of source.chat(
@@ -344,8 +352,10 @@ export {
   createMicrosoftA365ObservedTurnSource,
   createMicrosoftA365S2STokenResolver,
   createMicrosoftA365S2STokenResolverFromEnv,
+  createMicrosoftA365ScopeMiddleware,
   createMicrosoftOpenTelemetryInstrumentationOptions,
   createMicrosoftOpenTelemetryTracingConfig,
+  currentMicrosoftA365RequestContext,
   initMicrosoftOpenTelemetry,
   initMicrosoftOpenTelemetryFromEnv,
   isAzureMonitorEnvironmentEnabled,
@@ -358,6 +368,7 @@ export {
   resolveMicrosoftOpenTelemetryEnvironment,
   resolveMicrosoftOpenTelemetryNumberEnv,
   runWithMicrosoftA365Context,
+  runWithMicrosoftA365RequestContext,
   summarizeMicrosoftOpenTelemetryDestinations,
   updateMicrosoftA365ExportToken
 };

package/dist/register.js

@@ -1,6 +1,6 @@
 import {
   initMicrosoftOpenTelemetryFromEnv
-} from "./chunk-S7XVXBY3.js";
+} from "./chunk-K54CB7U4.js";
 
 // src/register.ts
 var DISABLED_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);

package/docs/architecture.md

@@ -7,8 +7,8 @@ adapter for `agents-ts`.
 
 The package keeps three boundaries separate.
 
-First, `@cuylabs/agent-core` remains the owner of agent execution telemetry. It
-configures AI SDK v7 GenAI telemetry for model calls and tool execution and
+First, `@cuylabs/agent-core` remains the owner of agent execution. It runs the
+turn loop, model calls, tool execution, approvals, and event stream, and it
 provides `createAgent({ tracing })` as the app-facing integration point.
 
 Second, `@microsoft/opentelemetry` owns the Microsoft OpenTelemetry provider,
@@ -17,8 +17,8 @@ export, and Microsoft-supported framework instrumentation.
 
 Third, this package bridges the two. It starts the Microsoft distro, creates
 Agent 365 S2S token resolvers, applies Agent 365 baggage around turns, and
-returns `agent-core` tracing defaults that align with Microsoft Agent 365
-schemas.
+returns `agent-core` tracing defaults that install official A365 scope
+middleware.
 
 The adapter default instrumentation profile is `agent-core`. It disables
 Microsoft's optional framework auto-instrumentations for OpenAI Agents SDK and
@@ -33,14 +33,14 @@ A365 processors/exporters/scopes, Azure Monitor, OTLP, GenAI instrumentation,
 and shared distro setup. This package does not copy those internals. It keeps
 only the adapter responsibilities:
 
-| Folder | Responsibility |
-| --- | --- |
-| `src/a365` | Normalize channel/runtime data into Microsoft A365 baggage. |
-| `src/auth` | Resolve Agent 365 S2S tokens from CLI-generated configuration or host-provided managed identity assertions. |
-| `src/runtime` | Call `useMicrosoftOpenTelemetry()`, map adapter options to distro options, expose destination helpers, expose instrumentation profiles, and load Microsoft modules lazily. |
-| `src/tracing` | Produce `agent-core` tracing config that avoids duplicate tool spans and carries Microsoft attributes. |
-| `src/common` | Public cross-cutting type aliases. |
-| `src/internal` | Small helpers that are not part of the package API. |
+| Folder         | Responsibility                                                                                                                                                             |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/a365`     | Normalize channel/runtime data into Microsoft A365 baggage and create official A365 scopes from agent-core lifecycle hooks.                                                |
+| `src/auth`     | Resolve Agent 365 S2S tokens from CLI-generated configuration or host-provided managed identity assertions.                                                                |
+| `src/runtime`  | Call `useMicrosoftOpenTelemetry()`, map adapter options to distro options, expose destination helpers, expose instrumentation profiles, and load Microsoft modules lazily. |
+| `src/tracing`  | Produce `agent-core` tracing config that avoids duplicate tool spans and carries Microsoft attributes.                                                                     |
+| `src/common`   | Public cross-cutting type aliases.                                                                                                                                         |
+| `src/internal` | Small helpers that are not part of the package API.                                                                                                                        |
 
 ## Agent 365 Flow
 
@@ -62,6 +62,22 @@ observed turn source. That scope creates Microsoft baggage values such as
 `microsoft.channel.name`, and `gen_ai.conversation.id`. The Microsoft distro
 copies those baggage values onto spans before export.
 
+The tracing config returned by this package installs a scope middleware that
+maps agent-core lifecycle hooks to Microsoft's official A365 scope classes:
+
+```text
+AgentTurnSource.chat()
+  └─ runWithMicrosoftA365Context()
+       ├─ InvokeAgentScope      turn start/end
+       ├─ InferenceScope        each model step
+       ├─ ExecuteToolScope      tool-start/tool-result/tool-error events
+       └─ OutputScope           final turn output
+```
+
+The middleware also exposes the active A365 parent context back to agent-core so
+the actual model call can run under the inference span. This keeps the scope
+tree coherent without asking the application to manually create scopes.
+
 For Microsoft Agent Hosting compatible adapters, the package can also delegate
 to the official distro's hosting middleware with
 `configureMicrosoftA365Hosting()`. This keeps Microsoft TurnContext middleware
@@ -74,16 +90,20 @@ the Agent 365 FMI flow and caches the resulting Observability API token.
 
 ## Tool Spans
 
-The default tracing helper returns `emitToolSpans: false`. This is intentional.
-AI SDK v7 GenAI telemetry already emits standard tool spans for normal
-`streamText()` tool execution. Enabling both AI SDK tool spans and agent-core
-custom tool spans creates duplicate `execute_tool` telemetry for one tool call.
+The default tracing helper returns `useA365Scopes: true`,
+`useDefaultOtelMiddleware: false`, `useGenAIOpenTelemetry: false`, and
+`emitToolSpans: false`. This is intentional. The official A365 scope middleware
+now owns `ExecuteToolScope` creation for `agents-ts` turns. Enabling the older
+generic middleware or local AI SDK GenAI telemetry at the same time can create
+duplicate `execute_tool` records.
 
-If an application has a custom execution path that does not emit AI SDK tool
-spans, it can opt in with:
+If an application has a custom execution path that should bypass the official
+A365 scope middleware, it can opt out and use generic agent-core OTel spans:
 
 ```ts
 createMicrosoftOpenTelemetryTracingConfig({
+  useA365Scopes: false,
+  useDefaultOtelMiddleware: true,
   emitToolSpans: true,
 });
 ```
@@ -91,7 +111,7 @@ createMicrosoftOpenTelemetryTracingConfig({
 ## Content Capture
 
 The package does not force a privacy policy. `recordInputs` and `recordOutputs`
-are explicit `agent-core` tracing settings. Set them to `true` when Agent 365
+control what the official A365 scopes record. Set them to `true` when Agent 365
 validation or audit scenarios require prompt, response, tool argument, and tool
 result attributes. Set them to `false` when an application needs metadata-only
 telemetry.

package/docs/destinations-and-instrumentation.md

@@ -7,12 +7,12 @@ telemetry is created.
 
 Destinations are exporters attached to the same OpenTelemetry pipeline.
 
-| Destination | Purpose | How to enable |
-| --- | --- | --- |
-| Agent 365 | Microsoft 365 admin, Defender, and Purview agent activity. | `a365.enabled: true` plus `a365.enableObservabilityExporter: true`. |
-| Azure Monitor | Application operations, traces, dependencies, logs, metrics, dashboards, and alerts. | `azureMonitor: { enabled: true }` or `APPLICATIONINSIGHTS_CONNECTION_STRING`. |
-| OTLP | Vendor-neutral export to collectors or backends such as Grafana, Datadog, or New Relic. | Standard `OTEL_EXPORTER_OTLP_*` environment variables. |
-| Console | Local validation when no remote exporter is active, or explicit debugging. | `enableConsoleExporters: true`. |
+| Destination   | Purpose                                                                                 | How to enable                                                                 |
+| ------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Agent 365     | Microsoft 365 admin, Defender, and Purview agent activity.                              | `a365.enabled: true` plus `a365.enableObservabilityExporter: true`.           |
+| Azure Monitor | Application operations, traces, dependencies, logs, metrics, dashboards, and alerts.    | `azureMonitor: { enabled: true }` or `APPLICATIONINSIGHTS_CONNECTION_STRING`. |
+| OTLP          | Vendor-neutral export to collectors or backends such as Grafana, Datadog, or New Relic. | Standard `OTEL_EXPORTER_OTLP_*` environment variables.                        |
+| Console       | Local validation when no remote exporter is active, or explicit debugging.              | `enableConsoleExporters: true`.                                               |
 
 The same spans can flow to multiple destinations. Agent 365 enrichment still
 helps Azure Monitor and OTLP when `a365.enabled` is true because the Microsoft
@@ -22,12 +22,12 @@ distro's `A365SpanProcessor` copies baggage onto spans before export.
 
 Instrumentation controls which libraries create spans.
 
-| Instrumentation | Purpose |
-| --- | --- |
-| `http`, `azureSdk`, databases, Redis, Bunyan, Winston | Infrastructure and application telemetry. |
-| `openaiAgents` | Optional Microsoft auto-instrumentation for the OpenAI Agents SDK when `@openai/agents` is installed. |
-| `langchain` | Optional Microsoft auto-instrumentation for LangChain when `@langchain/core` is installed. |
-| `agent-core` tracing | Emits `agents-ts` agent invocation spans and passes AI SDK v7 GenAI telemetry into `streamText()`. |
+| Instrumentation                                       | Purpose                                                                                                                     |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `http`, `azureSdk`, databases, Redis, Bunyan, Winston | Infrastructure and application telemetry.                                                                                   |
+| `openaiAgents`                                        | Optional Microsoft auto-instrumentation for the OpenAI Agents SDK when `@openai/agents` is installed.                       |
+| `langchain`                                           | Optional Microsoft auto-instrumentation for LangChain when `@langchain/core` is installed.                                  |
+| A365 scope middleware                                 | Converts `agents-ts` turns into official `InvokeAgentScope`, `InferenceScope`, `ExecuteToolScope`, and `OutputScope` spans. |
 
 `@cuylabs/agent-core` does not use OpenAI Agents SDK or LangChain internally.
 Those Microsoft framework instrumentations are useful only when an application
@@ -43,13 +43,13 @@ await initMicrosoftOpenTelemetry({
 });
 ```
 
-| Profile | Behavior |
-| --- | --- |
-| `agent-core` | Disables Microsoft infra and framework auto-instrumentation. Best default for `agents-ts`, where `agent-core` emits the agent/model/tool telemetry. |
-| `microsoft-genai` | Disables infrastructure auto-instrumentation and enables Microsoft's OpenAI Agents SDK and LangChain auto-instrumentations. |
-| `full-stack` | Enables infrastructure and Microsoft framework auto-instrumentation. Best when sending to Azure Monitor or a general OTLP backend too. |
-| `manual` | Disables built-in auto-instrumentation. Best when the app supplies its own processors/instrumentation. |
-| `microsoft-default` | Leaves `instrumentationOptions` unset so the official distro applies its native defaults. |
+| Profile             | Behavior                                                                                                                                                                            |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent-core`        | Disables Microsoft infra and optional framework auto-instrumentation. Best default for `agents-ts`, where the adapter's A365 scope middleware emits the agent/model/tool telemetry. |
+| `microsoft-genai`   | Disables infrastructure auto-instrumentation and enables Microsoft's OpenAI Agents SDK and LangChain auto-instrumentations.                                                         |
+| `full-stack`        | Enables infrastructure and Microsoft framework auto-instrumentation. Best when sending to Azure Monitor or a general OTLP backend too.                                              |
+| `manual`            | Disables built-in auto-instrumentation. Best when the app supplies its own processors/instrumentation.                                                                              |
+| `microsoft-default` | Leaves `instrumentationOptions` unset so the official distro applies its native defaults.                                                                                           |
 
 Explicit `instrumentationOptions` always override the selected profile.
 The old pre-release name `agent365-genai` is still accepted as an alias for
@@ -60,9 +60,11 @@ The old pre-release name `agent365-genai` is still accepted as an alias for
 There are two content-recording surfaces only if the application uses both
 `agent-core` and Microsoft's optional framework auto-instrumentations.
 
-`agent-core` uses `agent.recordInputs` and `agent.recordOutputs` in this
-adapter's tracing config. Those settings control AI SDK v7 GenAI telemetry
-created by `@cuylabs/agent-core`.
+For normal `agents-ts` turns, use `agent.recordInputs` and
+`agent.recordOutputs` in this adapter's tracing config. Those settings control
+content recording on the official A365 scopes created by the adapter:
+invocation input/output, inference input/output, tool arguments/results, and
+final output.
 
 Microsoft's optional OpenAI Agents and LangChain auto-instrumentations use their
 own official flags:
@@ -83,7 +85,7 @@ await initMicrosoftOpenTelemetry({
 ```
 
 Set these only when the process actually uses those frameworks. They do not
-control `agent-core`'s AI SDK spans.
+control the A365 scopes created for `@cuylabs/agent-core`.
 
 ## Example: Agent 365 and Azure Monitor
 

package/docs/distro-alignment.md

@@ -24,17 +24,17 @@ Apps that initialize observability in code can call
 
 `initMicrosoftOpenTelemetry()` maps directly to `useMicrosoftOpenTelemetry()`.
 
-| Microsoft distro option | Adapter option |
-| --- | --- |
-| `resource` | `resource` with `serviceName`, `serviceVersion`, and custom attributes. |
-| `azureMonitor` | `azureMonitor`. |
-| `instrumentationOptions` | `instrumentationOptions`. |
-| `agent-core`-focused instrumentation defaults | `instrumentationProfile: "agent-core"`. |
-| `a365.enabled` | `a365.enabled`. |
-| `a365.enableObservabilityExporter` | `a365.enableObservabilityExporter`. |
-| `a365.tokenResolver` | `a365.tokenResolver`. |
-| `a365.useS2SEndpoint` | `a365.useS2SEndpoint`. |
-| Export queue, timeout, batch, cluster, domain, and scope options | Same A365 option names. |
+| Microsoft distro option                                          | Adapter option                                                          |
+| ---------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `resource`                                                       | `resource` with `serviceName`, `serviceVersion`, and custom attributes. |
+| `azureMonitor`                                                   | `azureMonitor`.                                                         |
+| `instrumentationOptions`                                         | `instrumentationOptions`.                                               |
+| `agent-core`-focused instrumentation defaults                    | `instrumentationProfile: "agent-core"`.                                 |
+| `a365.enabled`                                                   | `a365.enabled`.                                                         |
+| `a365.enableObservabilityExporter`                               | `a365.enableObservabilityExporter`.                                     |
+| `a365.tokenResolver`                                             | `a365.tokenResolver`.                                                   |
+| `a365.useS2SEndpoint`                                            | `a365.useS2SEndpoint`.                                                  |
+| Export queue, timeout, batch, cluster, domain, and scope options | Same A365 option names.                                                 |
 
 The adapter also accepts `a365.exporterEnabled` as a compatibility alias for
 `a365.enableObservabilityExporter`. New code should use Microsoft's official
@@ -80,10 +80,11 @@ For apps that do use Microsoft Agent Hosting compatible adapters, call
 to the official distro's `configureA365Hosting()` helper, with a fallback for
 older distro versions that expose `ObservabilityHostingManager` instead.
 
-## Agent-Core Tracing
+## Official A365 Scope Model
 
 The adapter does not create a second agent runtime. It returns tracing settings
-for `createAgent({ tracing })`:
+for `createAgent({ tracing })` that install an `AgentMiddleware` backed by the
+official Microsoft A365 scope classes:
 
 ```ts
 const microsoftOtel = await initMicrosoftOpenTelemetryFromEnv();
@@ -95,10 +96,34 @@ const agent = createAgent({
 });
 ```
 
-`agent-core` emits the agent invocation span and passes AI SDK v7 GenAI telemetry
-into `streamText()`. The Microsoft distro owns the provider, span processors,
-and exporters. This keeps one OpenTelemetry pipeline while avoiding duplicate
-tool spans.
+The middleware maps one `agents-ts` turn into A365 scopes:
+
+| agent-core signal                                | Microsoft scope    |
+| ------------------------------------------------ | ------------------ |
+| chat start/end                                   | `InvokeAgentScope` |
+| model step start/output                          | `InferenceScope`   |
+| `tool-start`, `tool-result`, `tool-error` events | `ExecuteToolScope` |
+| final turn output                                | `OutputScope`      |
+
+It also returns the active A365 parent context to agent-core so the underlying
+model call is executed under the inference span. The Microsoft distro owns the
+provider, span processors, and exporters. This keeps one OpenTelemetry pipeline
+while avoiding duplicate generic tool spans.
+
+The default tracing values are:
+
+```ts
+{
+  useA365Scopes: true,
+  useDefaultOtelMiddleware: false,
+  useGenAIOpenTelemetry: false,
+  emitToolSpans: false,
+}
+```
+
+Use `useA365Scopes: false` only when an application intentionally wants the
+older generic agent-core OTel lifecycle instead of Microsoft's A365 product
+scope model.
 
 ## Optional Microsoft Framework Instrumentation
 
@@ -113,9 +138,9 @@ frameworks. The adapter's default `agent-core` profile disables them because the
 normal `agents-ts` path does not execute through those frameworks.
 
 The adapter types expose Microsoft's `isContentRecordingEnabled` flags for
-those framework instrumentations. They are separate from `agent-core`
-`recordInputs` and `recordOutputs`, which control AI SDK v7 telemetry produced
-through `@cuylabs/agent-core`.
+those framework instrumentations. They are separate from the adapter's
+`recordInputs` and `recordOutputs`, which control content recording on the
+official A365 scopes created for `@cuylabs/agent-core`.
 
 The early pre-release profile name `agent365-genai` remains accepted as a
 compatibility alias for `microsoft-genai`, but new code should use

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-microsoft-opentelemetry",
-  "version": "4.8.0",
+  "version": "4.8.1",
   "description": "Microsoft OpenTelemetry distro adapter for @cuylabs/agent-core",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,6 +30,7 @@
   ],
   "devDependencies": {
     "@ai-sdk/openai": "4.0.0-beta.38",
+    "@opentelemetry/api": "^1.9.0",
     "@types/node": "^22.0.0",
     "ai": "7.0.0-beta.111",
     "dotenv": "^17.2.3",
@@ -37,11 +38,12 @@
     "typescript": "^5.7.0",
     "vitest": "^4.0.18",
     "zod": "^3.25.76 || ^4.1.8",
-    "@cuylabs/agent-core": "^4.8.0"
+    "@cuylabs/agent-core": "^4.8.1"
   },
   "peerDependencies": {
     "@cuylabs/agent-core": "^4.0.0",
     "@microsoft/opentelemetry": ">=1.0.1 <2.0.0",
+    "@opentelemetry/api": "^1.9.0",
     "ai": "7.0.0-beta.111"
   },
   "keywords": [