[johnmtll]

Description

Summary of Changes

1. Adds an AI agent identifier, env.agent, to the client metadata handshake.
2. Refactors how the env sub-document is built and truncated.
3. Alters the way we populate metadata documents so changes can be mutative instead of just additive (adding logic to handle considering existing values when calling LimitedSizeDocument.ifItFitsItSits)

Notes for Reviewers

env.agent

env.agent is populated using first-match, order-bound logic over the agent-related environment variables defined in the spec. Depending on which variable matches, the value is either a generic marker (AI_AGENT) or the variable's literal value.

Per the spec, "a variable is considered populated if it is present in the environment with a non-empty value." We treat any value that is empty after normalization/truncation as unpopulated and skip it.

env construction and truncation

The incoming spec's truncation order is:

1. Omit fields from env except env.name and env.agent.
2. Omit env.agent. If env then has no remaining fields, omit env entirely.
3. Omit fields from os except os.type.
4. Omit the env document entirely.
5. Truncate platform. -- special we do not truncate this field

env.agent is omitted before env.name because drivers have reported env.name since before
env.agent existed.

• Note: The truncation order compliance is to be done in NODE-7851 as we're currently not compliant with even the previous version of the spec.

  env is built by progressively appending members to the live metadata document, and the spec was partially-satisfied somewhat incidentally: env.name happened to be the last FaaS member added, so it was deleted last — but env.container is appended after that, making it theoretically possible to end up with an env containing container but no name. This is incorrect.

  env is now constructed as a standalone document, truncated independently. This prepares us for a future spec alignment effort tracked in NODE-7851.

Truncation is a byte-op. This means that we can potentially slice multi-byte values during truncation. The remnants of a multi-byte slice are discarded. This allows us to also close out an outstanding bug (NODE-5150) via the use of a shared util (DriverStringUtils.truncateStringBytes) where multi-byte partials remained when constructing appName.

Other info

Refer to: mongodb/specifications#1967 for the incoming changes.

What is the motivation for this change?

For bug fixes

Current (incorrect) behavior:

Expected behavior:

How to reproduce:

Affected versions:

Release Highlight

AI agent identifier now in client metadata

The Node.js driver now includes additional runtime environment details, including AI agent information, when connecting to MongoDB. This provides better visibility into the applications and environments using the driver.

Double check the following

• Lint is passing (npm run check:lint)
• Self-review completed using the steps outlined here
• PR title follows the correct format: type(NODE-xxxx)[!]: description
  • Example: feat(NODE-1234)!: rewriting everything in coffeescript
• Changes are covered by tests
• New TODOs have a related JIRA ticket

[Copilot]

🟡 Changes recommended

The tests retain host Kubernetes state that causes failures on Kubernetes runners, and the application-name assertions no longer verify output correctness for the multibyte truncation fix.

2 open issues

• Clear Kubernetes host variable in test environment stub · New
• Retain output-based coverage for multibyte name truncation · New

What changed in this PR

Adds AI-agent identification to the MongoDB driver’s handshake metadata and refactors environment metadata handling. Full alignment with the specification’s truncation order remains deferred to NODE-7851.

Changes:

• Detects and normalizes agent environment variables using ordered precedence.
• Refactors environment construction and size accounting to support field replacement.
• Adds UTF-8-safe byte truncation for agent identifiers and application names, with unit and integration coverage.

File	Description
test/​unit/​utils.test.ts	Tests byte-limited string truncation and invalid limits.
test/​unit/​cmap/​handshake/​client_metadata.test.ts	Updates metadata sizing, truncation, and agent-detection tests.
test/​mongodb_bundled.ts	Exposes new helpers to bundled tests.
test/​integration/​mongodb-handshake/​mongodb-handshake.prose.test.ts	Adds agent handshake cases and environment-isolation helpers.
src/​utils.ts	Adds UTF-8-safe byte truncation.
src/​sdam/​monitor.ts	Adapts FaaS detection to the empty-map return value.
src/​cmap/​handshake/​client_metadata.ts	Adds agent metadata and refactors environment construction and sizing.

_{Review effort: Balanced}

[PavelSafronov]

After restoring this test, we can flip it to check for 126, thus ensuring that the truncation worked.

[PavelSafronov]

Changes look good, no blockers, approving.
Will merge once Team Review is done, we have release notes, and NODE-7851 is ready to be merged.

[tadjik1]

Suggested change

	// Env var value length after truncating bytes
	const APP_NAME_TRUNCATION_LIMIT_BYTES = 128;
	// Maximum size of application.name in bytes
	const APP_NAME_TRUNCATION_LIMIT_BYTES = 128;

This limit (value length) applies to appName, not to an environment variable value.

[tadjik1]

Suggested change

	// Env var value length after first 2 forms of normalization
	const AGENT_ENV_LIMIT_BYTES = 64;
	// Maximum size of env.agent in bytes, applied after trim and lowercase
	const AGENT_ENV_LIMIT_BYTES = 64;

Just a little bit more direct

[tadjik1]

Thanks @johnmtll! I left few suggestions for the comments (I found it a bit difficult to follow the spec with the current ones), but both are not blocking, up to you if you want to apply them.