[PECOBLR-1928] Add AI coding agent detection to User-Agent header (#333)

Add AI coding agent detection to User-Agent header

Detect when the Node.js SQL driver is invoked by an AI coding agent
(e.g. Claude Code, Cursor, Gemini CLI) by checking well-known
environment variables, and append `agent/<product>` to the User-Agent
string.

This enables Databricks to understand how much driver usage originates
from AI coding agents. Detection only succeeds when exactly one agent
is detected to avoid ambiguous attribution.

Mirrors the approach in databricks/cli#4287.

Signed-off-by: Vikrant Puppala <vikrant.puppala@databricks.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: vikrantpuppala

lib/utils/agentDetector.ts

@@ -0,0 +1,38 @@
+/**
+ * Detects whether the Node.js SQL driver is being invoked by an AI coding agent
+ * by checking for well-known environment variables that agents set in their
+ * spawned shell processes.
+ *
+ * Detection only succeeds when exactly one agent environment variable is present,
+ * to avoid ambiguous attribution when multiple agent environments overlap.
+ *
+ * Adding a new agent requires only a new entry in `knownAgents`.
+ *
+ * References for each environment variable:
+ *   - ANTIGRAVITY_AGENT: Closed source. Google Antigravity sets this variable.
+ *   - CLAUDECODE: https://github.com/anthropics/claude-code (sets CLAUDECODE=1)
+ *   - CLINE_ACTIVE: https://github.com/cline/cline (shipped in v3.24.0)
+ *   - CODEX_CI: https://github.com/openai/codex (part of UNIFIED_EXEC_ENV array in codex-rs)
+ *   - CURSOR_AGENT: Closed source. Referenced in a gist by johnlindquist.
+ *   - GEMINI_CLI: https://google-gemini.github.io/gemini-cli/docs/tools/shell.html (sets GEMINI_CLI=1)
+ *   - OPENCODE: https://github.com/opencode-ai/opencode (sets OPENCODE=1)
+ */
+
+const knownAgents: Array<{ envVar: string; product: string }> = [
+  { envVar: 'ANTIGRAVITY_AGENT', product: 'antigravity' },
+  { envVar: 'CLAUDECODE', product: 'claude-code' },
+  { envVar: 'CLINE_ACTIVE', product: 'cline' },
+  { envVar: 'CODEX_CI', product: 'codex' },
+  { envVar: 'CURSOR_AGENT', product: 'cursor' },
+  { envVar: 'GEMINI_CLI', product: 'gemini-cli' },
+  { envVar: 'OPENCODE', product: 'opencode' },
+];
+
+export default function detectAgent(env: Record<string, string | undefined> = process.env): string {
+  const detected = knownAgents.filter((a) => env[a.envVar]).map((a) => a.product);
+
+  if (detected.length === 1) {
+    return detected[0];
+  }
+  return '';
+}

lib/utils/buildUserAgentString.ts

@@ -1,5 +1,6 @@
 import os from 'os';
 import packageVersion from '../version';
+import detectAgent from './agentDetector';
 
 const productName = 'NodejsDatabricksSqlConnector';
 
@@ -27,5 +28,12 @@ export default function buildUserAgentString(userAgentEntry?: string): string {
   }
 
   const extra = [userAgentEntry, getNodeVersion(), getOperatingSystemVersion()].filter(Boolean);
-  return `${productName}/${packageVersion} (${extra.join('; ')})`;
+  let ua = `${productName}/${packageVersion} (${extra.join('; ')})`;
+
+  const agentProduct = detectAgent();
+  if (agentProduct) {
+    ua += ` agent/${agentProduct}`;
+  }
+
+  return ua;
 }

tests/unit/utils/agentDetector.test.ts

@@ -0,0 +1,36 @@
+import { expect } from 'chai';
+import detectAgent from '../../../lib/utils/agentDetector';
+
+describe('detectAgent', () => {
+  const allAgents = [
+    { envVar: 'ANTIGRAVITY_AGENT', product: 'antigravity' },
+    { envVar: 'CLAUDECODE', product: 'claude-code' },
+    { envVar: 'CLINE_ACTIVE', product: 'cline' },
+    { envVar: 'CODEX_CI', product: 'codex' },
+    { envVar: 'CURSOR_AGENT', product: 'cursor' },
+    { envVar: 'GEMINI_CLI', product: 'gemini-cli' },
+    { envVar: 'OPENCODE', product: 'opencode' },
+  ];
+
+  for (const { envVar, product } of allAgents) {
+    it(`detects ${product} when ${envVar} is set`, () => {
+      expect(detectAgent({ [envVar]: '1' })).to.equal(product);
+    });
+  }
+
+  it('returns empty string when no agent is detected', () => {
+    expect(detectAgent({})).to.equal('');
+  });
+
+  it('returns empty string when multiple agents are detected', () => {
+    expect(detectAgent({ CLAUDECODE: '1', CURSOR_AGENT: '1' })).to.equal('');
+  });
+
+  it('ignores empty env var values', () => {
+    expect(detectAgent({ CLAUDECODE: '' })).to.equal('');
+  });
+
+  it('ignores undefined env var values', () => {
+    expect(detectAgent({ CLAUDECODE: undefined })).to.equal('');
+  });
+});

tests/unit/utils/utils.test.ts

@@ -32,7 +32,7 @@ describe('buildUserAgentString', () => {
     // Prefix: 'NodejsDatabricksSqlConnector/'
     // Version: three period-separated digits and optional suffix
     const re =
-      /^(?<productName>NodejsDatabricksSqlConnector)\/(?<productVersion>\d+\.\d+\.\d+(-[^(]+)?)\s*\((?<comment>[^)]+)\)$/i;
+      /^(?<productName>NodejsDatabricksSqlConnector)\/(?<productVersion>\d+\.\d+\.\d+(-[^(]+)?)\s*\((?<comment>[^)]+)\)(\s+agent\/[a-z-]+)?$/i;
     const match = re.exec(ua);
     expect(match).to.not.be.eq(null);
 
@@ -62,6 +62,21 @@ describe('buildUserAgentString', () => {
     const userAgentString = buildUserAgentString(userAgentEntry);
     expect(userAgentString).to.include('<REDACTED>');
   });
+
+  it('appends agent suffix when agent env var is set', () => {
+    const orig = process.env.CLAUDECODE;
+    try {
+      process.env.CLAUDECODE = '1';
+      const ua = buildUserAgentString();
+      expect(ua).to.include('agent/claude-code');
+    } finally {
+      if (orig === undefined) {
+        delete process.env.CLAUDECODE;
+      } else {
+        process.env.CLAUDECODE = orig;
+      }
+    }
+  });
 });
 
 describe('formatProgress', () => {