[WIP] Add session description baggage setter in OpenTelemetry

[Copilot]

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.

Original prompt

Implement a feature analogous to the merged .NET change in microsoft/Agent365-dotnet PR #100 ([Observability] Session description baggage setter). The .NET PR added: (1) a baggage builder method to set a session description, (2) propagation of that value onto spans in the activity/span processor, and (3) a test.

Task for Node.js/TypeScript repository (microsoft/Agent365-nodejs):

1. OpenTelemetry Constants

   • Introduce a new constant for session description. Follow existing naming patterns used in constants.ts (e.g., GEN_AI_AGENT_DESCRIPTION_KEY maps to 'gen_ai.agent.description'). Proposed key: GEN_AI_SESSION_DESCRIPTION_KEY with value 'gen_ai.session.description'. Place it near other GEN_AI_* description/name/id keys for consistency.

2. BaggageBuilder Enhancement (packages/agents-a365-observability/src/tracing/middleware/BaggageBuilder.ts)

   • Add a fluent setter method: sessionDescription(value: string | null | undefined): BaggageBuilder
     • Uses the new OpenTelemetry constant.
     • Mirrors style and implementation of agentDescription() and callerName().
     • Ensure trimming and null/empty handling remains consistent via the existing private set() helper.
   • If there is already a sessionId() setter, do not modify it except to keep ordering logical (sessionId then sessionDescription). Ensure method ordering groups session-related setters.

3. Span / Activity Processing Propagation

   • Identify where baggage entries are read and turned into span attributes (likely in a SpanProcessor or during scope creation). Extend logic so that if baggage contains GEN_AI_SESSION_DESCRIPTION_KEY it sets a span attribute with the same key (or, if existing pattern adds a prefix like baggage., follow current pattern). Review existing propagation for agent description to mimic approach.
   • If there is a central array/list of allowed baggage attribute keys (e.g., in processors/util.ts where arrays of constants are enumerated), append the new constant so it propagates.

4. Tests

   • Update tests/observability/core/BaggageBuilder.test.ts (or create a new test file if more appropriate) to include a test verifying:
     • builder.sessionDescription('My session for onboarding') returns the builder instance (fluent API).
     • After build(), the baggage scope includes the key with trimmed value.
   • Add / update a SpanProcessor test (tests/observability/core/SpanProcessor.test.ts) to confirm a span started with baggage containing the session description ends up with the attribute set. Mirror existing tests for GEN_AI_AGENT_DESCRIPTION_KEY.

5. Documentation (optional but recommended)

   • Update README or any observability usage guide sample (e.g., tests-agent/basic-agent-sdk-sample/src/agent.ts) to show usage of the new sessionDescription() setter if there is already a block constructing a BaggageBuilder. Keep changes minimal—add one chained call .sessionDescription('...').

6. Code Style & Linting

   • Run existing lint/test scripts to ensure compliance. No breaking changes.

Acceptance Criteria:

• New constant defined and exported.
• BaggageBuilder has working sessionDescription() method.
• Span attributes include session description when baggage is set.
• Tests pass and cover new functionality (builder + propagation).
• Optional doc/sample update reflects usage.

Do not modify unrelated functionality. Keep naming consistent with existing patterns. If an alternative naming convention for session constants already exists (e.g., GEN_AI_CONVERSATION_ID_KEY), ensure alignment (session vs conversation). If the repository already has a session ID constant, prefer session description naming consistent with that (e.g., GEN_AI_SESSION_DESCRIPTION_KEY).

This pull request was created as a result of the following prompt from Copilot chat.

Implement a feature analogous to the merged .NET change in microsoft/Agent365-dotnet PR #100 ([Observability] Session description baggage setter). The .NET PR added: (1) a baggage builder method to set a session description, (2) propagation of that value onto spans in the activity/span processor, and (3) a test.

Task for Node.js/TypeScript repository (microsoft/Agent365-nodejs):

1. OpenTelemetry Constants

   • Introduce a new constant for session description. Follow existing naming patterns used in constants.ts (e.g., GEN_AI_AGENT_DESCRIPTION_KEY maps to 'gen_ai.agent.description'). Proposed key: GEN_AI_SESSION_DESCRIPTION_KEY with value 'gen_ai.session.description'. Place it near other GEN_AI_* description/name/id keys for consistency.

2. BaggageBuilder Enhancement (packages/agents-a365-observability/src/tracing/middleware/BaggageBuilder.ts)

   • Add a fluent setter method: sessionDescription(value: string | null | undefined): BaggageBuilder
     • Uses the new OpenTelemetry constant.
     • Mirrors style and implementation of agentDescription() and callerName().
     • Ensure trimming and null/empty handling remains consistent via the existing private set() helper.
   • If there is already a sessionId() setter, do not modify it except to keep ordering logical (sessionId then sessionDescription). Ensure method ordering groups session-related setters.

3. Span / Activity Processing Propagation

   • Identify where baggage entries are read and turned into span attributes (likely in a SpanProcessor or during scope creation). Extend logic so that if baggage contains GEN_AI_SESSION_DESCRIPTION_KEY it sets a span attribute with the same key (or, if existing pattern adds a prefix like baggage., follow current pattern). Review existing propagation for agent description to mimic approach.
   • If there is a central array/list of allowed baggage attribute keys (e.g., in processors/util.ts where arrays of constants are enumerated), append the new constant so it propagates.

4. Tests

   • Update tests/observability/core/BaggageBuilder.test.ts (or create a new test file if more appropriate) to include a test verifying:
     • builder.sessionDescription('My session for onboarding') returns the builder instance (fluent API).
     • After build(), the baggage scope includes the key with trimmed value.
   • Add / update a SpanProcessor test (tests/observability/core/SpanProcessor.test.ts) to confirm a span started with baggage containing the session description ends up with the attribute set. Mirror existing tests for GEN_AI_AGENT_DESCRIPTION_KEY.

5. Documentation (optional but recommended)

   • Update README or any observability usage guide sample (e.g., tests-agent/basic-agent-sdk-sample/src/agent.ts) to show usage of the new sessionDescription() setter if there is already a block constructing a BaggageBuilder. Keep changes minimal—add one chained call .sessionDescription('...').

6. Code Style & Linting

   • Run existing lint/test scripts to ensure compliance. No breaking changes.

Acceptance Criteria:

• New constant defined and exported.
• BaggageBuilder has working sessionDescription() method.
• Span attributes include session description when baggage is set.
• Tests pass and cover new functionality (builder + propagation).
• Optional doc/sample update reflects usage.

Do not modify unrelated functionality. Keep naming consistent with existing patterns. If an alternative naming convention for session constants already exists (e.g., GEN_AI_CONVERSATION_ID_KEY), ensure alignment (session vs conversation). If the repository already has a session ID constant, prefer session description naming consistent with that (e.g., GEN_AI_SESSION_DESCRIPTION_KEY).

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[fpfp100]

@copilot what is the propsoal change

[Copilot]

@copilot what is the propsoal change

This PR adds session description support to the observability layer, similar to the .NET implementation in PR #100. The changes include:

1. New constant: GEN_AI_SESSION_DESCRIPTION_KEY = 'gen_ai.session.description' in constants.ts
2. BaggageBuilder method: sessionDescription(value) fluent setter to set session descriptions in baggage
3. Span propagation: Session description from baggage will be propagated to span attributes via SpanProcessor
4. Tests: Coverage for the new builder method and span attribute propagation

This allows tracing session-level context (e.g., "Onboarding session", "Customer support chat") alongside the existing session ID.