@cuylabs/agent-microsoft-opentelemetry 6.0.0 → 6.2.0

package/README.md

@@ -168,6 +168,15 @@ spans with `useA365Scopes: false`, `useDefaultOtelMiddleware: true`, or
 `useGenAIOpenTelemetry: true`, but those settings should be deliberate because
 they can duplicate tool or model telemetry.
 
+When static identity fields such as `tenantId`, `agentId`, `agentName`,
+`agentDescription`, `agentVersion`, `serviceName`, and `serverEndpoint` are supplied to
+`createMicrosoftOpenTelemetryTracingConfig()` or `initMicrosoftOpenTelemetry()`,
+the A365 scope middleware uses them as static request identity for local agents
+and background jobs that are not already wrapped in
+`runWithMicrosoftA365Context()`. Real channel turns should still provide the
+ambient request context so user, conversation, channel, and export-token
+metadata can flow with the turn.
+
 ## Source Layout
 
 The source tree mirrors the adapter's ownership boundaries, not the full

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

@@ -656,12 +656,25 @@ function createMicrosoftA365ScopeMiddleware(options = {}) {
   const recordInputs = options.recordInputs ?? true;
   const recordOutputs = options.recordOutputs ?? true;
   const emitOutputScope = options.emitOutputScope ?? true;
+  const defaultRequestContext = options.defaultRequestContext;
   const states = /* @__PURE__ */ new Map();
   const statesByRequestContext = /* @__PURE__ */ new WeakMap();
+  function getTraceContext(sessionId, ctx) {
+    const state = findState(states, sessionId, ctx?.turnId);
+    if (!state) {
+      return void 0;
+    }
+    const inferenceContext = latestInferenceContext(state);
+    return inferenceContext ?? state.invokeContext;
+  }
   return {
     name: "microsoft-a365-scopes",
     async onChatStart(sessionId, message, ctx) {
-      const requestContext = currentMicrosoftA365RequestContext();
+      const activeRequestContext = currentMicrosoftA365RequestContext();
+      const requestContext = mergeRequestContexts(
+        defaultRequestContext,
+        activeRequestContext
+      );
       if (!requestContext || !hasA365ScopeIdentity(requestContext)) {
         return;
       }
@@ -697,7 +710,9 @@ function createMicrosoftA365ScopeMiddleware(options = {}) {
         toolScopes: /* @__PURE__ */ new Map()
       };
       states.set(turnKey(sessionId, ctx?.turnId), state);
-      statesByRequestContext.set(requestContext, state);
+      if (activeRequestContext) {
+        statesByRequestContext.set(activeRequestContext, state);
+      }
       statesByRequestContext.set(scopedRequestContext, state);
     },
     model: {
@@ -831,19 +846,32 @@ function createMicrosoftA365ScopeMiddleware(options = {}) {
       }
       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;
-    }
+    getTraceContext,
+    getOtelContext: getTraceContext
   };
 }
 function hasA365ScopeIdentity(context) {
   return Boolean(context.tenantId && context.agentId);
 }
+function mergeRequestContexts(defaults, active) {
+  if (!defaults && !active) {
+    return void 0;
+  }
+  const merged = {};
+  assignDefinedRequestContextValues(merged, defaults);
+  assignDefinedRequestContextValues(merged, active);
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function assignDefinedRequestContextValues(target, source) {
+  if (!source) {
+    return;
+  }
+  for (const [key, value] of Object.entries(source)) {
+    if (value !== void 0) {
+      target[key] = value;
+    }
+  }
+}
 function safeStartScope(start) {
   try {
     return start();
@@ -862,7 +890,7 @@ function currentState(states, statesByRequestContext) {
       return findState(states, requestContext.sessionId);
     }
   }
-  return latestState(states);
+  return states.size === 1 ? latestState(states) : void 0;
 }
 function startToolScope(state, event, recordInputs) {
   if (!state.module.ExecuteToolScope) {
@@ -1053,25 +1081,68 @@ function createMicrosoftOpenTelemetryTracingConfig(options = {}) {
     spanAttributes[MICROSOFT_A365_ATTRIBUTES.tenantId] = options.tenantId.trim();
   }
   const useA365Scopes = options.useA365Scopes ?? true;
+  const defaultRequestContext = mergeA365RequestContexts(
+    createStaticA365RequestContext(options),
+    options.a365Scopes?.defaultRequestContext
+  );
   return {
     ...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.emitToolSpans !== void 0 ? { emitToolSpans: options.emitToolSpans } : useA365Scopes ? { emitToolSpans: false } : {},
     useGenAIOpenTelemetry: options.useGenAIOpenTelemetry ?? (useA365Scopes ? false : true),
     ...options.telemetryIntegrations ? { telemetryIntegrations: options.telemetryIntegrations } : {},
     ...options.useGlobalTelemetryIntegrations !== void 0 ? {
       useGlobalTelemetryIntegrations: options.useGlobalTelemetryIntegrations
     } : {},
     ...useA365Scopes ? {
-      middleware: createMicrosoftA365ScopeMiddleware(options.a365Scopes),
+      middleware: createMicrosoftA365ScopeMiddleware({
+        ...options.a365Scopes,
+        ...defaultRequestContext ? { defaultRequestContext } : {}
+      }),
       useDefaultOtelMiddleware: options.useDefaultOtelMiddleware ?? false
     } : options.useDefaultOtelMiddleware !== void 0 ? { useDefaultOtelMiddleware: options.useDefaultOtelMiddleware } : {},
     ...Object.keys(spanAttributes).length > 0 ? { spanAttributes } : {}
   };
 }
+function createStaticA365RequestContext(options) {
+  const context = {};
+  setIfNonEmpty(context, "tenantId", options.tenantId);
+  setIfNonEmpty(context, "agentId", options.agentId);
+  setIfNonEmpty(context, "agentName", options.agentName);
+  setIfNonEmpty(context, "agentDescription", options.agentDescription);
+  setIfNonEmpty(context, "agentVersion", options.agentVersion);
+  setIfNonEmpty(context, "serviceName", options.serviceName);
+  setIfNonEmpty(
+    context,
+    "serverAddress",
+    options.serverEndpoint?.serverAddress
+  );
+  if (options.serverEndpoint?.serverPort !== void 0) {
+    context.serverPort = options.serverEndpoint.serverPort;
+  }
+  return Object.keys(context).length > 0 ? context : void 0;
+}
+function setIfNonEmpty(context, key, value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const trimmed = value.trim();
+  if (trimmed) {
+    context[key] = trimmed;
+  }
+}
+function mergeA365RequestContexts(defaults, overrides) {
+  if (!defaults && !overrides) {
+    return void 0;
+  }
+  return {
+    ...defaults ?? {},
+    ...overrides ?? {}
+  };
+}
 
 // src/runtime/instrumentation.ts
 var INFRA_INSTRUMENTATION_KEYS = [
@@ -1164,6 +1235,64 @@ function mergeConfig(base, override) {
   };
 }
 
+// src/runtime/destinations.ts
+var TRUE_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+function isMicrosoftOtlpEnvironmentEnabled(env = process.env) {
+  return Boolean(
+    readFirst(
+      env,
+      "OTEL_EXPORTER_OTLP_ENDPOINT",
+      "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+      "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
+      "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"
+    )
+  );
+}
+function isAzureMonitorEnvironmentEnabled(env = process.env) {
+  if (isTruthy(readFirst(env, "MICROSOFT_OTEL_AZURE_MONITOR_ENABLED"))) {
+    return true;
+  }
+  return Boolean(readFirst(env, "APPLICATIONINSIGHTS_CONNECTION_STRING"));
+}
+function createAzureMonitorOptionsFromEnv(env = process.env) {
+  const enabled = isAzureMonitorEnvironmentEnabled(env);
+  const connectionString = readFirst(
+    env,
+    "APPLICATIONINSIGHTS_CONNECTION_STRING"
+  );
+  if (!enabled && !connectionString) {
+    return void 0;
+  }
+  return {
+    enabled,
+    ...connectionString ? { azureMonitorExporterOptions: { connectionString } } : {}
+  };
+}
+function summarizeMicrosoftOpenTelemetryDestinations(options = {}) {
+  const env = options.env ?? process.env;
+  const azureMonitor = options.azureMonitor === false ? false : options.azureMonitor?.enabled ?? isAzureMonitorEnvironmentEnabled(env);
+  const agent365 = options.a365?.enabled === true && options.a365.enableObservabilityExporter === true;
+  const otlp = isMicrosoftOtlpEnvironmentEnabled(env);
+  return {
+    agent365,
+    azureMonitor,
+    otlp,
+    console: options.enableConsoleExporters ?? (!agent365 && !azureMonitor && !otlp)
+  };
+}
+function readFirst(env, ...names) {
+  for (const name of names) {
+    const value = env[name]?.trim();
+    if (value) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function isTruthy(value) {
+  return TRUE_VALUES.has((value ?? "").trim().toLowerCase());
+}
+
 // src/runtime/lifecycle.ts
 async function initMicrosoftOpenTelemetry(options = {}) {
   const module = await loadMicrosoftOpenTelemetryModule(options.runtime);
@@ -1171,7 +1300,10 @@ async function initMicrosoftOpenTelemetry(options = {}) {
   const distroOptions = await createDistroOptions(options, resource);
   module.useMicrosoftOpenTelemetry(distroOptions);
   return {
-    tracing: createMicrosoftOpenTelemetryTracingConfig(options.agent),
+    tracing: createMicrosoftOpenTelemetryTracingConfig({
+      ...options.agent,
+      ...options.resource?.serviceName && !options.agent?.serviceName ? { serviceName: options.resource.serviceName } : {}
+    }),
     shutdown: () => module.shutdownMicrosoftOpenTelemetry()
   };
 }
@@ -1195,11 +1327,32 @@ async function initMicrosoftOpenTelemetryFromEnv(options = {}) {
         env: options.env
       }) : void 0)
     } : void 0,
-    azureMonitor: env.azureMonitorEnabled !== void 0 ? { enabled: env.azureMonitorEnabled } : void 0,
+    azureMonitor: createEnvAzureMonitorOptions(
+      options.env,
+      env.azureMonitorEnabled,
+      options.azureMonitor
+    ),
     instrumentationProfile: options.instrumentationProfile ?? env.instrumentationProfile,
     enableConsoleExporters: options.enableConsoleExporters ?? env.enableConsoleExporters
   });
 }
+function createEnvAzureMonitorOptions(sourceEnv, envEnabled, options) {
+  if (options === false) {
+    return false;
+  }
+  const envOptions = createAzureMonitorOptionsFromEnv(sourceEnv);
+  const resolvedEnvOptions = envEnabled !== void 0 ? {
+    ...envOptions ?? {},
+    enabled: envEnabled
+  } : envOptions;
+  if (!resolvedEnvOptions && !options) {
+    return void 0;
+  }
+  return {
+    ...resolvedEnvOptions ?? {},
+    ...options ?? {}
+  };
+}
 async function runWithMicrosoftA365Context(requestContext, fn, options = {}) {
   const module = await loadMicrosoftOpenTelemetryModule(options);
   const runWithBaggage = () => runWithMicrosoftA365RequestContext(requestContext, () => {
@@ -1369,6 +1522,10 @@ export {
   createMicrosoftOpenTelemetryInstrumentationOptions,
   normalizeInstrumentationProfile,
   mergeInstrumentationOptions,
+  isMicrosoftOtlpEnvironmentEnabled,
+  isAzureMonitorEnvironmentEnabled,
+  createAzureMonitorOptionsFromEnv,
+  summarizeMicrosoftOpenTelemetryDestinations,
   initMicrosoftOpenTelemetry,
   initMicrosoftOpenTelemetryFromEnv,
   runWithMicrosoftA365Context,

package/dist/index.d.ts

@@ -11,8 +11,14 @@ type SpanAttributeValue = string | number | boolean | string[] | number[] | bool
 
 type MicrosoftOpenTelemetryTracingConfigOptions = {
     agentId?: string;
+    agentName?: string;
     agentDescription?: string;
     agentVersion?: string;
+    serviceName?: string;
+    serverEndpoint?: {
+        serverAddress: string;
+        serverPort?: number;
+    };
     recordInputs?: boolean;
     recordOutputs?: boolean;
     /**
@@ -297,6 +303,15 @@ type MicrosoftA365RequestContext = {
     extraBaggage?: Record<string, string | number | boolean | null | undefined>;
 };
 type MicrosoftA365ScopeMiddlewareOptions = {
+    /**
+     * Static Agent 365 request identity used when a turn is not already running
+     * inside `runWithMicrosoftA365Context()`.
+     *
+     * Ambient request context values override these defaults. This is useful for
+     * local agents or background jobs that have stable tenant/agent identity but
+     * no channel turn context.
+     */
+    defaultRequestContext?: MicrosoftA365RequestContext;
     /**
      * Capture prompt/user content on invoke and inference scopes.
      *
@@ -498,9 +513,10 @@ declare function mergeInstrumentationOptions(base: MicrosoftOpenTelemetryInstrum
 
 declare function initMicrosoftOpenTelemetry(options?: MicrosoftOpenTelemetryOptions): Promise<MicrosoftOpenTelemetryHandle>;
 declare function initMicrosoftOpenTelemetryFromEnv(options?: Omit<MicrosoftOpenTelemetryOptions, "resource" | "a365" | "azureMonitor"> & {
-    env?: NodeJS.ProcessEnv;
+    env?: MicrosoftOpenTelemetryEnvironment;
     resource?: Partial<MicrosoftOpenTelemetryResourceOptions>;
     a365?: Partial<MicrosoftOpenTelemetryA365Options>;
+    azureMonitor?: Partial<MicrosoftOpenTelemetryAzureMonitorOptions> | false;
 }): Promise<MicrosoftOpenTelemetryHandle>;
 declare function runWithMicrosoftA365Context<T>(requestContext: MicrosoftA365RequestContext, fn: () => T, options?: MicrosoftOpenTelemetryRuntimeOptions): Promise<Awaited<T>>;
 declare function updateMicrosoftA365ExportToken(token: string, options?: MicrosoftOpenTelemetryRuntimeOptions): Promise<boolean>;

package/dist/index.js

@@ -7,6 +7,7 @@ import {
   buildMicrosoftA365BaggagePairs,
   callOptionalBooleanMethod,
   callOptionalStringMethod,
+  createAzureMonitorOptionsFromEnv,
   createEnvReader,
   createMicrosoftA365S2STokenResolver,
   createMicrosoftA365S2STokenResolverFromEnv,
@@ -17,6 +18,8 @@ import {
   firstNonEmpty,
   initMicrosoftOpenTelemetry,
   initMicrosoftOpenTelemetryFromEnv,
+  isAzureMonitorEnvironmentEnabled,
+  isMicrosoftOtlpEnvironmentEnabled,
   loadMicrosoftOpenTelemetryModule,
   loadOpenTelemetryResourceModule,
   mergeInstrumentationOptions,
@@ -28,8 +31,9 @@ import {
   resolveMicrosoftOpenTelemetryNumberEnv,
   runWithMicrosoftA365Context,
   runWithMicrosoftA365RequestContext,
+  summarizeMicrosoftOpenTelemetryDestinations,
   updateMicrosoftA365ExportToken
-} from "./chunk-K54CB7U4.js";
+} from "./chunk-YDQDDNWT.js";
 
 // src/a365/hosting.ts
 async function configureMicrosoftA365Hosting(adapter, options = {}) {
@@ -280,64 +284,6 @@ function createMicrosoftA365ObservedTurnSource({
     }
   };
 }
-
-// src/runtime/destinations.ts
-var TRUE_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
-function isMicrosoftOtlpEnvironmentEnabled(env = process.env) {
-  return Boolean(
-    readFirst(
-      env,
-      "OTEL_EXPORTER_OTLP_ENDPOINT",
-      "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
-      "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
-      "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"
-    )
-  );
-}
-function isAzureMonitorEnvironmentEnabled(env = process.env) {
-  if (isTruthy(readFirst(env, "MICROSOFT_OTEL_AZURE_MONITOR_ENABLED"))) {
-    return true;
-  }
-  return Boolean(readFirst(env, "APPLICATIONINSIGHTS_CONNECTION_STRING"));
-}
-function createAzureMonitorOptionsFromEnv(env = process.env) {
-  const enabled = isAzureMonitorEnvironmentEnabled(env);
-  const connectionString = readFirst(
-    env,
-    "APPLICATIONINSIGHTS_CONNECTION_STRING"
-  );
-  if (!enabled && !connectionString) {
-    return void 0;
-  }
-  return {
-    enabled,
-    ...connectionString ? { azureMonitorExporterOptions: { connectionString } } : {}
-  };
-}
-function summarizeMicrosoftOpenTelemetryDestinations(options = {}) {
-  const env = options.env ?? process.env;
-  const azureMonitor = options.azureMonitor === false ? false : options.azureMonitor?.enabled ?? isAzureMonitorEnvironmentEnabled(env);
-  const agent365 = options.a365?.enabled === true && options.a365.enableObservabilityExporter === true;
-  const otlp = isMicrosoftOtlpEnvironmentEnabled(env);
-  return {
-    agent365,
-    azureMonitor,
-    otlp,
-    console: options.enableConsoleExporters ?? (!agent365 && !azureMonitor && !otlp)
-  };
-}
-function readFirst(env, ...names) {
-  for (const name of names) {
-    const value = env[name]?.trim();
-    if (value) {
-      return value;
-    }
-  }
-  return void 0;
-}
-function isTruthy(value) {
-  return TRUE_VALUES.has((value ?? "").trim().toLowerCase());
-}
 export {
   MICROSOFT_A365_ATTRIBUTES,
   MICROSOFT_A365_FMI_SCOPE,

package/dist/register.js

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

package/docs/architecture.md

@@ -97,6 +97,14 @@ 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 the tracing config includes static `tenantId`, `agentId`, `agentName`,
+`agentDescription`, `agentVersion`, `serviceName`, or `serverEndpoint` values,
+the A365 scope middleware uses them when no ambient A365 request context exists.
+This keeps local agents and background jobs observable without requiring a channel
+turn wrapper. Channel adapters should still run each turn inside
+`runWithMicrosoftA365Context()` so per-user and per-conversation dimensions are
+not flattened into static process identity.
+
 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:
 

package/docs/distro-alignment.md

@@ -125,6 +125,11 @@ Use `useA365Scopes: false` only when an application intentionally wants the
 older generic agent-core OTel lifecycle instead of Microsoft's A365 product
 scope model.
 
+Static tracing identity from `tenantId`, `agentId`, `agentName`,
+`agentDescription`, `agentVersion`, `serviceName`, and `serverEndpoint` is used
+as a fallback request context for local/background turns. Ambient channel
+request context still takes precedence.
+
 ## Optional Microsoft Framework Instrumentation
 
 The Microsoft distro's OpenAI Agents and LangChain integrations are optional

package/examples/01-agent365-s2s.ts

@@ -22,6 +22,7 @@ const observability = await initMicrosoftOpenTelemetry({
   },
   instrumentationProfile: "agent-core",
   agent: {
+    tenantId: process.env.A365_OBSERVABILITY_TENANT_ID,
     agentId: process.env.A365_OBSERVABILITY_AGENT_ID,
     agentDescription: "Example Agent 365 S2S agent",
     recordInputs: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-microsoft-opentelemetry",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "Microsoft OpenTelemetry distro adapter for @cuylabs/agent-core",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,7 +39,7 @@
     "typescript": "^5.7.0",
     "vitest": "^4.0.18",
     "zod": "^3.25.76 || ^4.1.8",
-    "@cuylabs/agent-core": "^6.0.0"
+    "@cuylabs/agent-core": "^6.2.0"
   },
   "peerDependencies": {
     "@cuylabs/agent-core": "^6.0.0",