@microsoft/agents-a365-observability 0.1.0-preview.93 → 0.2.0-preview.1

package/dist/cjs/tracing/constants.js

@@ -1,9 +1,9 @@
 "use strict";
-// ------------------------------------------------------------------------------
-// Copyright (c) Microsoft Corporation. All rights reserved.
-// ------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenTelemetryConstants = void 0;
+const version_1 = require("../version");
 /**
  * OpenTelemetry constants for Agent 365
  */
@@ -13,8 +13,11 @@ exports.OpenTelemetryConstants = OpenTelemetryConstants;
 // Span operation names
 OpenTelemetryConstants.INVOKE_AGENT_OPERATION_NAME = 'invoke_agent';
 OpenTelemetryConstants.EXECUTE_TOOL_OPERATION_NAME = 'execute_tool';
+OpenTelemetryConstants.OUTPUT_MESSAGES_OPERATION_NAME = 'output_messages';
+OpenTelemetryConstants.CHAT_OPERATION_NAME = 'chat';
 // OpenTelemetry semantic conventions
 OpenTelemetryConstants.ERROR_TYPE_KEY = 'error.type';
+OpenTelemetryConstants.ERROR_TYPE_CANCELLED = 'TaskCanceledException';
 OpenTelemetryConstants.ERROR_MESSAGE_KEY = 'error.message';
 OpenTelemetryConstants.AZ_NAMESPACE_KEY = 'az.namespace';
 OpenTelemetryConstants.SERVER_ADDRESS_KEY = 'server.address';
@@ -36,18 +39,16 @@ OpenTelemetryConstants.GEN_AI_REQUEST_MAX_TOKENS_KEY = 'gen_ai.request.max_token
 OpenTelemetryConstants.GEN_AI_REQUEST_MODEL_KEY = 'gen_ai.request.model';
 OpenTelemetryConstants.GEN_AI_REQUEST_TEMPERATURE_KEY = 'gen_ai.request.temperature';
 OpenTelemetryConstants.GEN_AI_REQUEST_TOP_P_KEY = 'gen_ai.request.top_p';
-OpenTelemetryConstants.GEN_AI_RESPONSE_ID_KEY = 'gen_ai.response.id';
 OpenTelemetryConstants.GEN_AI_RESPONSE_FINISH_REASONS_KEY = 'gen_ai.response.finish_reasons';
 OpenTelemetryConstants.GEN_AI_RESPONSE_MODEL_KEY = 'gen_ai.response.model';
-OpenTelemetryConstants.GEN_AI_SYSTEM_KEY = 'gen_ai.system';
-OpenTelemetryConstants.GEN_AI_SYSTEM_VALUE = 'az.ai.agent365';
 OpenTelemetryConstants.GEN_AI_AGENT_ID_KEY = 'gen_ai.agent.id';
 OpenTelemetryConstants.GEN_AI_AGENT_NAME_KEY = 'gen_ai.agent.name';
-OpenTelemetryConstants.GEN_AI_AGENT_TYPE_KEY = 'gen_ai.agent.type';
 OpenTelemetryConstants.GEN_AI_AGENT_DESCRIPTION_KEY = 'gen_ai.agent.description';
-OpenTelemetryConstants.GEN_AI_AGENT_PLATFORM_ID_KEY = 'gen_ai.agent.platformid';
+OpenTelemetryConstants.GEN_AI_AGENT_VERSION_KEY = 'gen_ai.agent.version';
+OpenTelemetryConstants.GEN_AI_AGENT_PLATFORM_ID_KEY = 'microsoft.a365.agent.platform.id';
+OpenTelemetryConstants.GEN_AI_AGENT_THOUGHT_PROCESS_KEY = 'microsoft.a365.agent.thought.process';
 OpenTelemetryConstants.GEN_AI_CONVERSATION_ID_KEY = 'gen_ai.conversation.id';
-OpenTelemetryConstants.GEN_AI_CONVERSATION_ITEM_LINK_KEY = 'gen_ai.conversation.item.link';
+OpenTelemetryConstants.GEN_AI_CONVERSATION_ITEM_LINK_KEY = 'microsoft.conversation.item.link';
 OpenTelemetryConstants.GEN_AI_TOKEN_TYPE_KEY = 'gen_ai.token.type';
 OpenTelemetryConstants.GEN_AI_USAGE_INPUT_TOKENS_KEY = 'gen_ai.usage.input_tokens';
 OpenTelemetryConstants.GEN_AI_USAGE_OUTPUT_TOKENS_KEY = 'gen_ai.usage.output_tokens';
@@ -56,52 +57,53 @@ OpenTelemetryConstants.GEN_AI_PROVIDER_NAME_KEY = 'gen_ai.provider.name';
 OpenTelemetryConstants.GEN_AI_SYSTEM_INSTRUCTIONS_KEY = 'gen_ai.system_instructions';
 OpenTelemetryConstants.GEN_AI_INPUT_MESSAGES_KEY = 'gen_ai.input.messages';
 OpenTelemetryConstants.GEN_AI_OUTPUT_MESSAGES_KEY = 'gen_ai.output.messages';
-OpenTelemetryConstants.GEN_AI_EVENT_CONTENT = 'gen_ai.event.content';
+OpenTelemetryConstants.A365_MESSAGES_SCHEMA_VERSION_KEY = 'microsoft.a365.messages.schema_version';
 // Tool execution constants
 OpenTelemetryConstants.GEN_AI_TOOL_CALL_ID_KEY = 'gen_ai.tool.call.id';
 OpenTelemetryConstants.GEN_AI_TOOL_NAME_KEY = 'gen_ai.tool.name';
 OpenTelemetryConstants.GEN_AI_TOOL_DESCRIPTION_KEY = 'gen_ai.tool.description';
 OpenTelemetryConstants.GEN_AI_TOOL_ARGS_KEY = 'gen_ai.tool.call.arguments';
-OpenTelemetryConstants.GEN_AI_TOOL_CALL_RESULT_KEY = 'gen_ai.event.content'; // GEN_AI_EVENT_CONTENT
+OpenTelemetryConstants.GEN_AI_TOOL_CALL_RESULT_KEY = 'gen_ai.tool.call.result';
 OpenTelemetryConstants.GEN_AI_TOOL_TYPE_KEY = 'gen_ai.tool.type';
-// Agent user (user tied to agent instance during creation) or caller dimensions
-OpenTelemetryConstants.GEN_AI_AGENT_USER_ID_KEY = 'gen_ai.agent.userid';
-OpenTelemetryConstants.GEN_AI_CALLER_TENANT_ID_KEY = 'gen_ai.caller.tenantid';
-OpenTelemetryConstants.GEN_AI_CALLER_ID_KEY = 'gen_ai.caller.id';
-OpenTelemetryConstants.GEN_AI_CALLER_NAME_KEY = 'gen_ai.caller.name';
-OpenTelemetryConstants.GEN_AI_CALLER_UPN_KEY = 'gen_ai.caller.upn';
-OpenTelemetryConstants.GEN_AI_CALLER_CLIENT_IP_KEY = 'gen_ai.caller.client.ip';
+// Human caller dimensions (OTel user.* namespace)
+OpenTelemetryConstants.USER_ID_KEY = 'user.id';
+OpenTelemetryConstants.USER_NAME_KEY = 'user.name';
+OpenTelemetryConstants.USER_EMAIL_KEY = 'user.email';
+OpenTelemetryConstants.GEN_AI_CALLER_CLIENT_IP_KEY = 'client.address';
 // Agent to Agent caller agent dimensions
-OpenTelemetryConstants.GEN_AI_CALLER_AGENT_USER_ID_KEY = 'gen_ai.caller.agent.userid';
-OpenTelemetryConstants.GEN_AI_CALLER_AGENT_UPN_KEY = 'gen_ai.caller.agent.upn';
-OpenTelemetryConstants.GEN_AI_CALLER_AGENT_TENANT_ID_KEY = 'gen_ai.caller.agent.tenantid';
-OpenTelemetryConstants.GEN_AI_CALLER_AGENT_NAME_KEY = 'gen_ai.caller.agent.name';
-OpenTelemetryConstants.GEN_AI_CALLER_AGENT_ID_KEY = 'gen_ai.caller.agent.id';
-OpenTelemetryConstants.GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY = 'gen_ai.caller.agent.applicationid';
-OpenTelemetryConstants.GEN_AI_CALLER_AGENT_CLIENT_IP_KEY = 'gen_ai.caller.agent.user.client.ip';
-OpenTelemetryConstants.GEN_AI_CALLER_AGENT_PLATFORM_ID_KEY = 'gen_ai.caller.agent.platformid';
+OpenTelemetryConstants.GEN_AI_CALLER_AGENT_USER_ID_KEY = 'microsoft.a365.caller.agent.user.id';
+OpenTelemetryConstants.GEN_AI_CALLER_AGENT_EMAIL_KEY = 'microsoft.a365.caller.agent.user.email';
+OpenTelemetryConstants.GEN_AI_CALLER_AGENT_NAME_KEY = 'microsoft.a365.caller.agent.name';
+OpenTelemetryConstants.GEN_AI_CALLER_AGENT_ID_KEY = 'microsoft.a365.caller.agent.id';
+OpenTelemetryConstants.GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY = 'microsoft.a365.caller.agent.blueprint.id';
+OpenTelemetryConstants.GEN_AI_CALLER_AGENT_PLATFORM_ID_KEY = 'microsoft.a365.caller.agent.platform.id';
+OpenTelemetryConstants.GEN_AI_CALLER_AGENT_VERSION_KEY = 'microsoft.a365.caller.agent.version';
 // Agent-specific dimensions
 OpenTelemetryConstants.AGENT_ID_KEY = 'gen_ai.agent.id';
 OpenTelemetryConstants.GEN_AI_TASK_ID_KEY = 'gen_ai.task.id';
-OpenTelemetryConstants.SESSION_ID_KEY = 'session.id';
-OpenTelemetryConstants.SESSION_DESCRIPTION_KEY = 'session.description';
+OpenTelemetryConstants.SESSION_ID_KEY = 'microsoft.session.id';
+OpenTelemetryConstants.SESSION_DESCRIPTION_KEY = 'microsoft.session.description';
 OpenTelemetryConstants.GEN_AI_ICON_URI_KEY = 'gen_ai.agent365.icon_uri';
-OpenTelemetryConstants.TENANT_ID_KEY = 'tenant.id';
+OpenTelemetryConstants.TENANT_ID_KEY = 'microsoft.tenant.id';
 // Baggage keys
-OpenTelemetryConstants.OPERATION_SOURCE_KEY = 'operation.source';
-OpenTelemetryConstants.GEN_AI_AGENT_AUID_KEY = 'gen_ai.agent.user.id';
-OpenTelemetryConstants.GEN_AI_AGENT_UPN_KEY = 'gen_ai.agent.upn';
-OpenTelemetryConstants.GEN_AI_AGENT_BLUEPRINT_ID_KEY = 'gen_ai.agent.applicationid';
-OpenTelemetryConstants.CORRELATION_ID_KEY = 'correlation.id';
-OpenTelemetryConstants.HIRING_MANAGER_ID_KEY = 'hiring.manager.id';
+OpenTelemetryConstants.GEN_AI_AGENT_AUID_KEY = 'microsoft.agent.user.id';
+OpenTelemetryConstants.GEN_AI_AGENT_EMAIL_KEY = 'microsoft.agent.user.email';
+OpenTelemetryConstants.GEN_AI_AGENT_BLUEPRINT_ID_KEY = 'microsoft.a365.agent.blueprint.id';
 // Execution context dimensions
-OpenTelemetryConstants.GEN_AI_EXECUTION_TYPE_KEY = 'gen_ai.execution.type';
 OpenTelemetryConstants.GEN_AI_EXECUTION_PAYLOAD_KEY = 'gen_ai.execution.payload';
-// Source metadata dimensions
-OpenTelemetryConstants.GEN_AI_EXECUTION_SOURCE_ID_KEY = 'gen_ai.execution.sourceMetadata.id';
-OpenTelemetryConstants.GEN_AI_EXECUTION_SOURCE_NAME_KEY = 'gen_ai.channel.name';
-OpenTelemetryConstants.GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY = 'gen_ai.channel.link';
+// Channel dimensions
+OpenTelemetryConstants.CHANNEL_NAME_KEY = 'microsoft.channel.name';
+OpenTelemetryConstants.CHANNEL_LINK_KEY = 'microsoft.channel.link';
 // Custom parent id and parent name key
 OpenTelemetryConstants.CUSTOM_PARENT_SPAN_ID_KEY = 'custom.parent.span.id';
 OpenTelemetryConstants.CUSTOM_SPAN_NAME_KEY = 'custom.span.name';
+// Service attributes
+OpenTelemetryConstants.SERVICE_NAME_KEY = 'service.name';
+// Telemetry SDK attributes
+OpenTelemetryConstants.TELEMETRY_SDK_NAME_KEY = 'telemetry.sdk.name';
+OpenTelemetryConstants.TELEMETRY_SDK_LANGUAGE_KEY = 'telemetry.sdk.language';
+OpenTelemetryConstants.TELEMETRY_SDK_VERSION_KEY = 'telemetry.sdk.version';
+OpenTelemetryConstants.TELEMETRY_SDK_NAME_VALUE = 'A365ObservabilitySDK';
+OpenTelemetryConstants.TELEMETRY_SDK_LANGUAGE_VALUE = 'nodejs';
+OpenTelemetryConstants.TELEMETRY_SDK_VERSION_VALUE = version_1.LIB_VERSION;
 //# sourceMappingURL=constants.js.map

package/dist/cjs/tracing/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/tracing/constants.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/tracing/constants.ts"],"names":[],"mappings":"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"}

package/dist/cjs/tracing/context/parent-span-context.d.ts

@@ -1,4 +1,4 @@
-import { Context, TraceFlags } from '@opentelemetry/api';
+import { Context, TraceFlags, TraceState } from '@opentelemetry/api';
 /**
  * Reference to a parent span for explicit parent-child linking across async boundaries.
  * Used when automatic context propagation fails (e.g., WebSocket callbacks, external event handlers).
@@ -12,9 +12,18 @@ export interface ParentSpanRef {
      * Span ID (16-character hex string)
      */
     spanId: string;
-    /**  * Optional trace flags
+    /**
+     * Optional trace flags
      */
     traceFlags?: TraceFlags;
+    /**
+     * Optional W3C trace state for vendor-specific trace context data
+     */
+    traceState?: TraceState;
+    /**
+     * Whether the span originated from a remote service (default: true)
+     */
+    isRemote?: boolean;
 }
 /**
  * Creates a new Context with an explicit parent span reference.

package/dist/cjs/tracing/context/parent-span-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parent-span-context.d.ts","sourceRoot":"","sources":["../../../../src/tracing/context/parent-span-context.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,OAAO,EAAe,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGtF;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;OACG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAUD;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CA8B5F;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAKnF"}
+{"version":3,"file":"parent-span-context.d.ts","sourceRoot":"","sources":["../../../../src/tracing/context/parent-span-context.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,OAAO,EAAe,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGlG;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;OAEG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAUD;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAoC5F;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAKnF"}

package/dist/cjs/tracing/context/parent-span-context.js

@@ -29,16 +29,21 @@ function createContextWithParentSpanRef(base, parent) {
         logging_1.default.warn(`[ParentSpanContext] Invalid parent span reference; returning base context. traceId=${parent.traceId}, spanId=${parent.spanId}`);
         return base;
     }
-    // If the base context already has an active span for the same trace, reuse its traceFlags.
-    // Otherwise, default to NONE to avoid up-sampling.
-    const active = api_1.trace.getSpan(base)?.spanContext();
-    const derivedFlags = active?.traceId === parent.traceId ? active.traceFlags : undefined;
-    const traceFlags = derivedFlags ?? api_1.TraceFlags.NONE;
+    // Determine traceFlags:
+    // 1. Use parent.traceFlags if explicitly provided
+    // 2. Inherit from active span if its traceId matches
+    // 3. Default to SAMPLED — manually instrumented spans should always be captured
+    const activeCtx = api_1.trace.getSpan(base)?.spanContext();
+    const traceFlags = parent.traceFlags
+        ?? (activeCtx?.traceId === parent.traceId ? activeCtx.traceFlags : undefined)
+        ?? api_1.TraceFlags.SAMPLED;
     // Create a SpanContext from the parent reference
     const parentSpanContext = {
         traceId: parent.traceId,
         spanId: parent.spanId,
         traceFlags,
+        traceState: parent.traceState,
+        isRemote: parent.isRemote ?? true,
     };
     // Create a non-recording span with the parent context
     const parentSpan = api_1.trace.wrapSpanContext(parentSpanContext);

package/dist/cjs/tracing/context/parent-span-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"parent-span-context.js","sourceRoot":"","sources":["../../../../src/tracing/context/parent-span-context.ts"],"names":[],"mappings":";AAAA,uCAAuC;AACvC,kCAAkC;;;;;AAyClC,wEA8BC;AAUD,oDAKC;AApFD,4CAAsF;AACtF,kEAAyC;AAsBzC,SAAS,cAAc,CAAC,OAAe;IACrC,OAAO,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,kCAAkC,CAAC;AAC3F,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,OAAO,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,kBAAkB,CAAC;AACzE,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,8BAA8B,CAAC,IAAa,EAAE,MAAqB;IACjF,iBAAM,CAAC,IAAI,CAAC,kEAAkE,MAAM,CAAC,OAAO,YAAY,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAEzH,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QACrE,iBAAM,CAAC,IAAI,CACT,sFAAsF,MAAM,CAAC,OAAO,YAAY,MAAM,CAAC,MAAM,EAAE,CAChI,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2FAA2F;IAC3F,mDAAmD;IACnD,MAAM,MAAM,GAAG,WAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;IAClD,MAAM,YAAY,GAAG,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IACxF,MAAM,UAAU,GAAG,YAAY,IAAI,gBAAU,CAAC,IAAI,CAAC;IAEnD,iDAAiD;IACjD,MAAM,iBAAiB,GAAgB;QACrC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,UAAU;KACX,CAAC;IAEF,sDAAsD;IACtD,MAAM,UAAU,GAAG,WAAK,CAAC,eAAe,CAAC,iBAAiB,CAAC,CAAC;IAE5D,oCAAoC;IACpC,MAAM,iBAAiB,GAAG,WAAK,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAE1D,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,oBAAoB,CAAI,MAAqB,EAAE,QAAiB;IAC9E,MAAM,IAAI,GAAG,aAAO,CAAC,MAAM,EAAE,CAAC;IAC9B,MAAM,iBAAiB,GAAG,8BAA8B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvE,iBAAM,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IAC9E,OAAO,aAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"parent-span-context.js","sourceRoot":"","sources":["../../../../src/tracing/context/parent-span-context.ts"],"names":[],"mappings":";AAAA,uCAAuC;AACvC,kCAAkC;;;;;AAoDlC,wEAoCC;AAUD,oDAKC;AArGD,4CAAkG;AAClG,kEAAyC;AAiCzC,SAAS,cAAc,CAAC,OAAe;IACrC,OAAO,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,kCAAkC,CAAC;AAC3F,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,OAAO,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,kBAAkB,CAAC;AACzE,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,8BAA8B,CAAC,IAAa,EAAE,MAAqB;IACjF,iBAAM,CAAC,IAAI,CAAC,kEAAkE,MAAM,CAAC,OAAO,YAAY,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAEzH,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QACrE,iBAAM,CAAC,IAAI,CACT,sFAAsF,MAAM,CAAC,OAAO,YAAY,MAAM,CAAC,MAAM,EAAE,CAChI,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wBAAwB;IACxB,kDAAkD;IAClD,qDAAqD;IACrD,gFAAgF;IAChF,MAAM,SAAS,GAAG,WAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;IACrD,MAAM,UAAU,GACd,MAAM,CAAC,UAAU;WACd,CAAC,SAAS,EAAE,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;WAC1E,gBAAU,CAAC,OAAO,CAAC;IAExB,iDAAiD;IACjD,MAAM,iBAAiB,GAAgB;QACrC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,UAAU;QACV,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;KAClC,CAAC;IAEF,sDAAsD;IACtD,MAAM,UAAU,GAAG,WAAK,CAAC,eAAe,CAAC,iBAAiB,CAAC,CAAC;IAE5D,oCAAoC;IACpC,MAAM,iBAAiB,GAAG,WAAK,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAE1D,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,oBAAoB,CAAI,MAAqB,EAAE,QAAiB;IAC9E,MAAM,IAAI,GAAG,aAAO,CAAC,MAAM,EAAE,CAAC;IAC9B,MAAM,iBAAiB,GAAG,8BAA8B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvE,iBAAM,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IAC9E,OAAO,aAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC;AACnD,CAAC"}

package/dist/cjs/tracing/context/token-context.d.ts

@@ -2,8 +2,22 @@ import { Context } from '@opentelemetry/api';
 /**
  * Run a function within a Context that carries the per-request export token.
  * This keeps the token only in OTel Context (ALS), never in any registry.
+ *
+ * The token can be updated later via `updateExportToken()` before the trace
+ * is flushed — useful when the callback is long-running and the original
+ * token may expire before export.
  */
 export declare function runWithExportToken<T>(token: string, fn: () => T): T;
+/**
+ * Update the export token in the active OTel Context.
+ * Call this to refresh the token before ending the root span when the
+ * original token may have expired during a long-running request.
+ *
+ * Must be called within the same async context created by `runWithExportToken`.
+ * @param token The fresh token to use for export.
+ * @returns true if the token was updated successfully, false if no token holder was found.
+ */
+export declare function updateExportToken(token: string): boolean;
 /**
  * Retrieve the per-request export token from a given OTel Context (or the active one).
  */

package/dist/cjs/tracing/context/token-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-context.d.ts","sourceRoot":"","sources":["../../../../src/tracing/context/token-context.ts"],"names":[],"mappings":"AAIA,OAAO,EAA6B,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAKxE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAInE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,OAA0B,GAAG,MAAM,GAAG,SAAS,CAElF"}
+{"version":3,"file":"token-context.d.ts","sourceRoot":"","sources":["../../../../src/tracing/context/token-context.ts"],"names":[],"mappings":"AAIA,OAAO,EAA6B,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAcxE;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAKnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CASxD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,OAA0B,GAAG,MAAM,GAAG,SAAS,CAUlF"}

package/dist/cjs/tracing/context/token-context.js

@@ -7,6 +7,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runWithExportToken = runWithExportToken;
+exports.updateExportToken = updateExportToken;
 exports.getExportToken = getExportToken;
 const api_1 = require("@opentelemetry/api");
 const logging_1 = __importDefault(require("../../utils/logging"));
@@ -14,16 +15,48 @@ const EXPORT_TOKEN_KEY = (0, api_1.createContextKey)('a365_export_token');
 /**
  * Run a function within a Context that carries the per-request export token.
  * This keeps the token only in OTel Context (ALS), never in any registry.
+ *
+ * The token can be updated later via `updateExportToken()` before the trace
+ * is flushed — useful when the callback is long-running and the original
+ * token may expire before export.
  */
 function runWithExportToken(token, fn) {
-    const ctxWithToken = api_1.context.active().setValue(EXPORT_TOKEN_KEY, token);
+    const holder = { token };
+    const ctxWithToken = api_1.context.active().setValue(EXPORT_TOKEN_KEY, holder);
     logging_1.default.info('[TokenContext] Running function with export token in context.');
     return api_1.context.with(ctxWithToken, fn);
 }
+/**
+ * Update the export token in the active OTel Context.
+ * Call this to refresh the token before ending the root span when the
+ * original token may have expired during a long-running request.
+ *
+ * Must be called within the same async context created by `runWithExportToken`.
+ * @param token The fresh token to use for export.
+ * @returns true if the token was updated successfully, false if no token holder was found.
+ */
+function updateExportToken(token) {
+    const value = api_1.context.active().getValue(EXPORT_TOKEN_KEY);
+    if (value && typeof value === 'object' && 'token' in value) {
+        value.token = token;
+        logging_1.default.info('[TokenContext] Export token updated in context.');
+        return true;
+    }
+    logging_1.default.warn('[TokenContext] updateExportToken called but no token holder found in active context. Was runWithExportToken called?');
+    return false;
+}
 /**
  * Retrieve the per-request export token from a given OTel Context (or the active one).
  */
 function getExportToken(ctx = api_1.context.active()) {
-    return ctx.getValue(EXPORT_TOKEN_KEY);
+    const value = ctx.getValue(EXPORT_TOKEN_KEY);
+    if (value && typeof value === 'object' && 'token' in value) {
+        return value.token;
+    }
+    // Backward compat: support raw string values from older callers
+    if (typeof value === 'string') {
+        return value;
+    }
+    return undefined;
 }
 //# sourceMappingURL=token-context.js.map

package/dist/cjs/tracing/context/token-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-context.js","sourceRoot":"","sources":["../../../../src/tracing/context/token-context.ts"],"names":[],"mappings":";AAAA,iFAAiF;AACjF,4DAA4D;AAC5D,iFAAiF;;;;;AAWjF,gDAIC;AAKD,wCAEC;AApBD,4CAAwE;AACxE,kEAAyC;AAEzC,MAAM,gBAAgB,GAAG,IAAA,sBAAgB,EAAC,mBAAmB,CAAC,CAAC;AAE/D;;;GAGG;AACH,SAAgB,kBAAkB,CAAI,KAAa,EAAE,EAAW;IAC9D,MAAM,YAAY,GAAG,aAAO,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACxE,iBAAM,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC;IAC7E,OAAO,aAAO,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAAC,MAAe,aAAO,CAAC,MAAM,EAAE;IAC5D,OAAO,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAuB,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"token-context.js","sourceRoot":"","sources":["../../../../src/tracing/context/token-context.ts"],"names":[],"mappings":";AAAA,iFAAiF;AACjF,4DAA4D;AAC5D,iFAAiF;;;;;AAwBjF,gDAKC;AAWD,8CASC;AAKD,wCAUC;AA9DD,4CAAwE;AACxE,kEAAyC;AAEzC,MAAM,gBAAgB,GAAG,IAAA,sBAAgB,EAAC,mBAAmB,CAAC,CAAC;AAW/D;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAI,KAAa,EAAE,EAAW;IAC9D,MAAM,MAAM,GAAgB,EAAE,KAAK,EAAE,CAAC;IACtC,MAAM,YAAY,GAAG,aAAO,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IACzE,iBAAM,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC;IAC7E,OAAO,aAAO,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAAC,KAAa;IAC7C,MAAM,KAAK,GAAG,aAAO,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC1D,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;QAC1D,KAAqB,CAAC,KAAK,GAAG,KAAK,CAAC;QACrC,iBAAM,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,iBAAM,CAAC,IAAI,CAAC,qHAAqH,CAAC,CAAC;IACnI,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAAC,MAAe,aAAO,CAAC,MAAM,EAAE;IAC5D,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC7C,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;QAC3D,OAAQ,KAAqB,CAAC,KAAK,CAAC;IACtC,CAAC;IACD,gEAAgE;IAChE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/cjs/tracing/context/trace-context-propagation.d.ts

@@ -0,0 +1,68 @@
+import { Context } from '@opentelemetry/api';
+import { ParentSpanRef } from './parent-span-context';
+/**
+ * Carrier type for HTTP headers used in trace context propagation.
+ * Compatible with Node.js IncomingHttpHeaders and plain string maps.
+ */
+export type HeadersCarrier = Record<string, string | string[] | undefined>;
+/**
+ * A parent context for span creation. Accepts either:
+ * - {@link ParentSpanRef}: explicit traceId/spanId pair (manual approach)
+ * - {@link Context}: an OTel Context, typically from {@link extractContextFromHeaders} or `propagation.extract()`
+ */
+export type ParentContext = ParentSpanRef | Context;
+/**
+ * Type guard to distinguish a {@link ParentSpanRef} from an OTel {@link Context}.
+ */
+export declare function isParentSpanRef(value: ParentContext): value is ParentSpanRef;
+/**
+ * Injects the current trace context (`traceparent`/`tracestate` headers) into
+ * the provided headers object using the globally registered W3C propagator.
+ *
+ * @param headers Mutable object where trace context headers will be written.
+ * @param ctx Optional OTel Context to inject from. Defaults to the active context.
+ * @returns The same `headers` object, for chaining convenience.
+ *
+ * @example
+ * ```typescript
+ * const headers: Record<string, string> = {};
+ * injectContextToHeaders(headers);
+ * await fetch('http://service-b/process', { headers });
+ * ```
+ */
+export declare function injectContextToHeaders(headers: Record<string, string>, ctx?: Context): Record<string, string>;
+/**
+ * Extracts trace context from incoming HTTP headers using the globally
+ * registered W3C propagator. Returns an OTel {@link Context} that can be
+ * passed to scope classes as a {@link ParentContext}.
+ *
+ * @param headers The incoming HTTP request headers containing `traceparent`/`tracestate`.
+ * @param baseCtx Optional base context to extend. Defaults to the active context.
+ * @returns An OTel Context containing the extracted trace information.
+ *
+ * @example
+ * ```typescript
+ * const parentCtx = extractContextFromHeaders(req.headers);
+ * const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });
+ * ```
+ */
+export declare function extractContextFromHeaders(headers: HeadersCarrier, baseCtx?: Context): Context;
+/**
+ * Extracts trace context from incoming HTTP headers and runs the callback
+ * within that context. Any spans created inside the callback will be
+ * parented to the extracted trace.
+ *
+ * @param headers The incoming HTTP request headers containing `traceparent`/`tracestate`.
+ * @param callback The function to execute within the extracted context.
+ * @returns The result of the callback.
+ *
+ * @example
+ * ```typescript
+ * runWithExtractedTraceContext(req.headers, () => {
+ *   const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
+ *   scope.dispose();
+ * });
+ * ```
+ */
+export declare function runWithExtractedTraceContext<T>(headers: HeadersCarrier, callback: () => T): T;
+//# sourceMappingURL=trace-context-propagation.d.ts.map

package/dist/cjs/tracing/context/trace-context-propagation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context-propagation.d.ts","sourceRoot":"","sources":["../../../../src/tracing/context/trace-context-propagation.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwB,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAE3E;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,OAAO,CAAC;AAEpD;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,aAAa,CAmB5E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,GAAG,CAAC,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAET;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAE7F"}

package/dist/cjs/tracing/context/trace-context-propagation.js

@@ -0,0 +1,85 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isParentSpanRef = isParentSpanRef;
+exports.injectContextToHeaders = injectContextToHeaders;
+exports.extractContextFromHeaders = extractContextFromHeaders;
+exports.runWithExtractedTraceContext = runWithExtractedTraceContext;
+const api_1 = require("@opentelemetry/api");
+/**
+ * Type guard to distinguish a {@link ParentSpanRef} from an OTel {@link Context}.
+ */
+function isParentSpanRef(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const maybeCtx = value;
+    if (typeof maybeCtx.getValue === 'function' &&
+        typeof maybeCtx.setValue === 'function' &&
+        typeof maybeCtx.deleteValue === 'function') {
+        return false;
+    }
+    const maybeRef = value;
+    return ('traceId' in maybeRef &&
+        typeof maybeRef.traceId === 'string' &&
+        'spanId' in maybeRef &&
+        typeof maybeRef.spanId === 'string');
+}
+/**
+ * Injects the current trace context (`traceparent`/`tracestate` headers) into
+ * the provided headers object using the globally registered W3C propagator.
+ *
+ * @param headers Mutable object where trace context headers will be written.
+ * @param ctx Optional OTel Context to inject from. Defaults to the active context.
+ * @returns The same `headers` object, for chaining convenience.
+ *
+ * @example
+ * ```typescript
+ * const headers: Record<string, string> = {};
+ * injectContextToHeaders(headers);
+ * await fetch('http://service-b/process', { headers });
+ * ```
+ */
+function injectContextToHeaders(headers, ctx) {
+    api_1.propagation.inject(ctx ?? api_1.context.active(), headers);
+    return headers;
+}
+/**
+ * Extracts trace context from incoming HTTP headers using the globally
+ * registered W3C propagator. Returns an OTel {@link Context} that can be
+ * passed to scope classes as a {@link ParentContext}.
+ *
+ * @param headers The incoming HTTP request headers containing `traceparent`/`tracestate`.
+ * @param baseCtx Optional base context to extend. Defaults to the active context.
+ * @returns An OTel Context containing the extracted trace information.
+ *
+ * @example
+ * ```typescript
+ * const parentCtx = extractContextFromHeaders(req.headers);
+ * const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });
+ * ```
+ */
+function extractContextFromHeaders(headers, baseCtx) {
+    return api_1.propagation.extract(baseCtx ?? api_1.context.active(), headers);
+}
+/**
+ * Extracts trace context from incoming HTTP headers and runs the callback
+ * within that context. Any spans created inside the callback will be
+ * parented to the extracted trace.
+ *
+ * @param headers The incoming HTTP request headers containing `traceparent`/`tracestate`.
+ * @param callback The function to execute within the extracted context.
+ * @returns The result of the callback.
+ *
+ * @example
+ * ```typescript
+ * runWithExtractedTraceContext(req.headers, () => {
+ *   const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
+ *   scope.dispose();
+ * });
+ * ```
+ */
+function runWithExtractedTraceContext(headers, callback) {
+    return api_1.context.with(extractContextFromHeaders(headers), callback);
+}
+//# sourceMappingURL=trace-context-propagation.js.map

package/dist/cjs/tracing/context/trace-context-propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context-propagation.js","sourceRoot":"","sources":["../../../../src/tracing/context/trace-context-propagation.ts"],"names":[],"mappings":";AAAA,uCAAuC;AACvC,kCAAkC;;AAqBlC,0CAmBC;AAiBD,wDAMC;AAiBD,8DAKC;AAmBD,oEAEC;AAxGD,4CAAmE;AAgBnE;;GAEG;AACH,SAAgB,eAAe,CAAC,KAAoB;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAE9D,MAAM,QAAQ,GAAG,KAAgB,CAAC;IAClC,IACE,OAAO,QAAQ,CAAC,QAAQ,KAAK,UAAU;QACvC,OAAO,QAAQ,CAAC,QAAQ,KAAK,UAAU;QACvC,OAAO,QAAQ,CAAC,WAAW,KAAK,UAAU,EAC1C,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,KAAsB,CAAC;IACxC,OAAO,CACL,SAAS,IAAI,QAAQ;QACrB,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ;QACpC,QAAQ,IAAI,QAAQ;QACpB,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ,CACpC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,sBAAsB,CACpC,OAA+B,EAC/B,GAAa;IAEb,iBAAW,CAAC,MAAM,CAAC,GAAG,IAAI,aAAO,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,yBAAyB,CACvC,OAAuB,EACvB,OAAiB;IAEjB,OAAO,iBAAW,CAAC,OAAO,CAAC,OAAO,IAAI,aAAO,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,4BAA4B,CAAI,OAAuB,EAAE,QAAiB;IACxF,OAAO,aAAO,CAAC,IAAI,CAAC,yBAAyB,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;AACpE,CAAC"}