[nodejs] Add automatic caller identity enrichment#260
Draft
DheerajPannala wants to merge 2 commits into
Draft
Conversation
Add opt-in trusted invocation identity resolution, request-local OpenTelemetry propagation, span enrichment, diagnostics, hosting integration, documentation, and coverage. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 26200287-5b13-4c4b-9746-938ff2301a4c
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds an opt-in, request-local “resolved invocation identity” pipeline for hosted turns, allowing the SDK to enrich core and extension OpenTelemetry spans with validated caller/target identity (while preventing identity spoofing via baggage and preserving feature-off behavior).
Changes:
- Introduces a request-local
ResolvedInvocationIdentitystored in a private OpenTelemetry context key, plus span enrichment + diagnostics in the core observability package. - Adds hosting-side identity resolution (trusted principal + Activity evidence), a new
InvocationIdentityMiddleware, and updates hosting utilities/middleware to prefer resolved identity when present. - Expands test coverage and documentation for identity resolution, precedence, validation, and rollback behavior.
Reviewed changes
Copilot reviewed 26 out of 27 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/observability/extension/invocation-identity-extensions.test.ts | Verifies resolved identity enrichment flows into LangChain/OpenAI extension spans. |
| tests/observability/extension/hosting/scope-utils.test.ts | Adds coverage for ScopeUtils preferring resolved identity and merging explicit/derived values. |
| tests/observability/extension/hosting/output-logging-middleware.test.ts | Ensures output logging spans pick up resolved identity regardless of middleware order. |
| tests/observability/extension/hosting/observability-hosting-manager.test.ts | Validates opt-in registration behavior, ordering, and deduplication semantics. |
| tests/observability/extension/hosting/invocation-identity-resolver.test.ts | Comprehensive tests for trust boundary, classification, precedence, normalization, and validation errors. |
| tests/observability/extension/hosting/invocation-identity-middleware.test.ts | Covers middleware control flow, hooks, strict vs non-strict behavior, and error handling. |
| tests/observability/core/trace-context-propagation.test.ts | Ensures resolved identity can combine with extracted remote parent trace context. |
| tests/observability/core/invocation-identity.test.ts | Tests core context storage semantics and SpanProcessor identity/baggage precedence + diagnostics. |
| pnpm-lock.yaml | Locks @microsoft/agents-activity dependency resolution. |
| packages/agents-a365-observability/src/tracing/scopes/OpenTelemetryScope.ts | Combines resolved identity with parent context; blocks blank identity attribute writes when identity exists. |
| packages/agents-a365-observability/src/tracing/processors/SpanProcessor.ts | Enriches spans from resolved identity, blocks identity-baggage overwrites, and triggers diagnostics on end. |
| packages/agents-a365-observability/src/tracing/invocation-identity-attributes.ts | Defines the identity attribute key set and helper utilities for blank/nonblank checks. |
| packages/agents-a365-observability/src/tracing/diagnostics/invocation-identity-diagnostics.ts | Adds warning diagnostics for incomplete identity on invoke_agent spans with deduplication. |
| packages/agents-a365-observability/src/tracing/context/invocation-identity-context.ts | Adds the private OTel context key and create/get/run helpers for resolved identity. |
| packages/agents-a365-observability/src/tracing/constants.ts | Adds microsoft.a365.invocation.role attribute key constant. |
| packages/agents-a365-observability/src/index.ts | Exports the new invocation identity context APIs from the package public surface. |
| packages/agents-a365-observability/docs/design.md | Documents request-local identity + enrichment behavior in observability design doc. |
| packages/agents-a365-observability-hosting/src/utils/ScopeUtils.ts | Prefers resolved identity for derived caller/target details and adjusts merge rules accordingly. |
| packages/agents-a365-observability-hosting/src/middleware/OutputLoggingMiddleware.ts | Uses resolved identity snapshots/rehydration to ensure output spans get correct identity even with ordering differences. |
| packages/agents-a365-observability-hosting/src/middleware/ObservabilityHostingManager.ts | Adds opt-in identity middleware registration and adapter-level deduplication. |
| packages/agents-a365-observability-hosting/src/middleware/InvocationIdentityMiddleware.ts | New middleware that resolves identity once per turn, validates it, runs hooks, and executes downstream in the resolved context. |
| packages/agents-a365-observability-hosting/src/index.ts | Exposes identity middleware + resolver APIs from hosting package. |
| packages/agents-a365-observability-hosting/src/identity/InvocationIdentityResolver.ts | New resolver implementing trust gating, normalization, precedence, conflict reporting, and validation. |
| packages/agents-a365-observability-hosting/package.json | Adds docs to package files and introduces @microsoft/agents-activity dependency via catalog:. |
| packages/agents-a365-observability-hosting/docs/invocation-identity.md | New feature documentation: enabling, trust boundary, precedence, validation, diagnostics, backend contract. |
| packages/agents-a365-observability-hosting/docs/design.md | Updates hosting design doc to include identity middleware/resolver architecture and references. |
| docs/design.md | Updates repo-level design doc to mention resolved invocation identity and hosting opt-in. |
Files not reviewed (1)
- pnpm-lock.yaml: Generated file
Comment on lines
+72
to
+74
| logger.info( | ||
| `[ObservabilityHostingManager] Configured. InvocationIdentity: ${enableInvocationIdentity}, Baggage: ${enableBaggage}, OutputLogging: ${enableOutputLogging}.`, | ||
| ); |
Comment on lines
40
to
44
| const globalProvider: any = trace.getTracerProvider(); | ||
| if (globalProvider && typeof globalProvider.addSpanProcessor === 'function') { | ||
| globalProvider.addSpanProcessor(identityProcessor); | ||
| globalProvider.addSpanProcessor(processor); | ||
| flushProvider = globalProvider; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Validation performed
pnpm -r build