[PECOBLR-1928] Add AI coding agent detection to User-Agent header

[vikrantpuppala]

Summary

• Adds agentDetector.ts module that detects 7 AI coding agents (Claude Code, Cursor, Gemini CLI, Cline, Codex, OpenCode, Antigravity) by checking well-known environment variables they set in spawned shell processes
• Integrates detection into buildUserAgentString() to append agent/<product> to the User-Agent header
• Uses exactly-one detection rule: if zero or multiple agent env vars are set, no agent is attributed (avoids ambiguity)

Approach

Mirrors the implementation in databricks/cli#4287 and aligns with the latest agent list in libs/agent/agent.go.

Agent	Product String	Environment Variable
Google Antigravity	antigravity	ANTIGRAVITY_AGENT
Claude Code	claude-code	CLAUDECODE
Cline	cline	CLINE_ACTIVE
OpenAI Codex	codex	CODEX_CI
Cursor	cursor	CURSOR_AGENT
Gemini CLI	gemini-cli	GEMINI_CLI
OpenCode	opencode	OPENCODE

Adding a new agent requires only a new entry in the knownAgents array.

Changes

• New: lib/utils/agentDetector.ts — environment-variable-based agent detection with injectable env object for testability
• Modified: lib/utils/buildUserAgentString.ts — calls detectAgent() and appends agent/<product> to the User-Agent string
• Modified: tests/unit/utils/utils.test.ts — updated User-Agent regex to allow optional agent/<product> suffix; added test asserting suffix is appended when agent env var is set
• New: tests/unit/utils/agentDetector.test.ts — 11 test cases covering all agents, no agent, multiple agents, empty/undefined values

Test plan

• agentDetector.test.ts — 11 tests pass
• utils.test.ts (buildUserAgentString) — all 4 tests pass (including new agent suffix assertion)
• Manual: verified User-Agent contains agent/claude-code when run from Claude Code via NODE_DEBUG=http

  'User-Agent': [
    'NodejsDatabricksSqlConnector/1.12.0 (Node.js 22.19.0; Linux 5.4.0-1154-aws-fips) agent/claude-code'
  

• Executed SELECT 1 successfully against dogfood warehouse: [{"1":1}]

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds AI coding agent attribution to the connector’s User-Agent header by detecting well-known agent environment variables and appending an agent/<product> suffix when exactly one agent is detected.

Changes:

• Introduce detectAgent() utility to identify a single active AI agent via environment variables.
• Update buildUserAgentString() to append agent/<product> to the User-Agent when detection succeeds.
• Extend unit tests to cover detection logic and the optional User-Agent suffix.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
lib/utils/agentDetector.ts	New env-var-based agent detection helper with “exactly one match” behavior.
lib/utils/buildUserAgentString.ts	Appends agent/<product> to the generated User-Agent when an agent is detected.
tests/unit/utils/agentDetector.test.ts	Adds unit coverage for all known agents and ambiguous/empty cases.
tests/unit/utils/utils.test.ts	Updates UA regex to allow optional agent suffix and adds a suffix assertion test.

Comments suppressed due to low confidence (1)

tests/unit/utils/utils.test.ts:36

• The test’s inline User-Agent format description (immediately above) still describes a UA that ends at the closing ")". With the new optional agent/<product> suffix, that description is now misleading—RFC 7231 allows additional product tokens after the initial product/comment. Update the comment/docs near this regex to reflect the optional agent/... suffix so future changes don’t “fix” the regex back to the old format.

  function checkUserAgentString(ua: string, userAgentEntry?: string) {
    // Prefix: 'NodejsDatabricksSqlConnector/'
    // Version: three period-separated digits and optional suffix
    const re =
      /^(?<productName>NodejsDatabricksSqlConnector)\/(?<productVersion>\d+\.\d+\.\d+(-[^(]+)?)\s*\((?<comment>[^)]+)\)(\s+agent\/[a-z-]+)?$/i;
    const match = re.exec(ua);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.