feat: add the driving agent to the CLI's API User-Agent (#8505)

## Summary

Adds `agent/<name>` to the User-Agent of the CLI's API client when
`getDrivingAgent()` detects an agent, so the API can attribute deploys,
site creation, and other command calls to agents without relying on
telemetry. Also fires a telemetry event when `netlify recipes
ai-context` installs context.

## What changed

- `getRequestUserAgent()` in `command-helpers.ts` returns `USER_AGENT`,
plus ` agent/<name>` when an agent is detected (name only, no version or
source). `base-command.ts` passes it to the API client, so anonymous
deploys and the commands that reuse `apiOpts.userAgent` get it too. The
`USER_AGENT` text printed by `--version` and help is unchanged.
- `ai-context` recipe fires `sites_aiContextInstalled` with `{ consumer
}` when it creates or updates a context file.
`downloadAndWriteContextFiles` now returns whether it wrote anything and
rejects on a failed download or write, so failures and no-ops don't
count. The ticket's `ai_context_installed` fails the CLI's event-name
validation, so this uses the `sites` object like `sites_initStarted`.
`agent` comes from `track()` (#8504).

Linear:
https://linear.app/netlify/issue/EX-3044/augment-cli-calls-to-identify-if-an-agent-is-performing-the-call

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01Nq1RjpFnzzsfZf5qHLCH36

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: seancdavis

src/commands/base-command.ts

@@ -24,6 +24,7 @@ import {
   logAndThrowError,
   logJson,
   exit,
+  getRequestUserAgent,
   getToken,
   log,
   version,
@@ -670,7 +671,7 @@ export default class BaseCommand extends Command {
       host?: string
       pathPrefix?: string
     } = {
-      userAgent: USER_AGENT,
+      userAgent: getRequestUserAgent(),
     }
 
     if (process.env.NETLIFY_API_URL) {

src/recipes/ai-context/context.ts

@@ -221,8 +221,11 @@ export const deleteFile = async (path: string) => {
   }
 }
 
-export const downloadAndWriteContextFiles = async (consumer: ConsumerConfig, { command }: RunRecipeOptions) => {
-  await Promise.allSettled(
+export const downloadAndWriteContextFiles = async (
+  consumer: ConsumerConfig,
+  { command }: RunRecipeOptions,
+): Promise<boolean> => {
+  const results = await Promise.allSettled(
     Object.keys(consumer.contextScopes).map(async (contextKey) => {
       const contextConfig = consumer.contextScopes[contextKey]
 
@@ -264,7 +267,7 @@ export const downloadAndWriteContextFiles = async (consumer: ConsumerConfig, { c
                 absoluteFilePath,
               )} contains the latest version of the context files.`,
             )
-            return
+            return false
           }
 
           // We must preserve any overrides found in the existing file.
@@ -289,6 +292,14 @@ export const downloadAndWriteContextFiles = async (consumer: ConsumerConfig, { c
       await writeFile(absoluteFilePath, contents)
 
       log(`${existing ? 'Updated' : 'Created'} context files at ${chalk.underline(absoluteFilePath)}`)
+      return true
     }),
   )
+
+  const failure = results.find((result): result is PromiseRejectedResult => result.status === 'rejected')
+  if (failure) {
+    throw failure.reason
+  }
+
+  return results.some((result) => result.status === 'fulfilled' && result.value)
 }

src/recipes/ai-context/index.ts

@@ -5,6 +5,7 @@ import execa from 'execa'
 
 import type { RunRecipeOptions } from '../../commands/recipes/recipes.js'
 import { logAndThrowError, log, version } from '../../utils/command-helpers.js'
+import { track } from '../../utils/telemetry/index.js'
 
 import {
   getExistingContext,
@@ -156,8 +157,9 @@ export const run = async (runOptions: RunRecipeOptions) => {
     return
   }
 
+  let wroteFiles = false
   try {
-    await downloadAndWriteContextFiles(consumer, runOptions)
+    wroteFiles = await downloadAndWriteContextFiles(consumer, runOptions)
 
     // the deprecated MCP file path
     // let's remove that file if it exists.
@@ -171,4 +173,8 @@ export const run = async (runOptions: RunRecipeOptions) => {
   } catch (error) {
     logAndThrowError(error)
   }
+
+  if (wroteFiles) {
+    await track('sites_aiContextInstalled', { consumer: consumer.key })
+  }
 }

src/utils/command-helpers.ts

@@ -12,6 +12,7 @@ import terminalLink from 'terminal-link'
 
 import { startSpinner } from '../lib/spinner.js'
 
+import { getDrivingAgent } from './agent-detection.js'
 import getCLIPackageJson from './get-cli-package-json.js'
 import { reportError } from './telemetry/report-error.js'
 import type { TokenLocation } from './types.js'
@@ -54,6 +55,11 @@ const { name, version: packageVersion } = await getCLIPackageJson()
 export const version = packageVersion
 export const USER_AGENT = `${name}/${version} ${platform}-${arch} node-${process.version}`
 
+export const getRequestUserAgent = (env: NodeJS.ProcessEnv = process.env): string => {
+  const agent = getDrivingAgent(env)
+  return agent ? `${USER_AGENT} agent/${agent.name}` : USER_AGENT
+}
+
 /** A list of base command flags that needs to be sorted down on documentation and on help pages */
 const BASE_FLAGS = new Set(['--debug', '--http-proxy', '--http-proxy-certificate-filename'])
 

tests/unit/recipes/ai-context/download-context-files.test.ts

@@ -98,7 +98,7 @@ describe('downloadAndWriteContextFiles', () => {
 
   test('downloads and writes context files for all scopes', async () => {
     // Execute the actual function
-    await downloadAndWriteContextFiles(mockConsumer, mockRunOptions)
+    await expect(downloadAndWriteContextFiles(mockConsumer, mockRunOptions)).resolves.toBe(true)
 
     // Verify expected calls
     expect(mockFetch).toHaveBeenCalledTimes(2) // Once for each scope
@@ -124,12 +124,19 @@ describe('downloadAndWriteContextFiles', () => {
     fs.readFile.mockResolvedValue(mockProviderContent)
 
     // Execute the actual function
-    await downloadAndWriteContextFiles(mockConsumer, mockRunOptions)
+    await expect(downloadAndWriteContextFiles(mockConsumer, mockRunOptions)).resolves.toBe(false)
 
     // Verify expected behavior - no writes when versions match
     expect(fs.writeFile).not.toHaveBeenCalled()
   })
 
+  test('reports no writes when the consumer has no context scopes', async () => {
+    await expect(downloadAndWriteContextFiles({ ...mockConsumer, contextScopes: {} }, mockRunOptions)).resolves.toBe(
+      false,
+    )
+    expect(fs.writeFile).not.toHaveBeenCalled()
+  })
+
   test('applies overrides when updating existing Netlify files', async () => {
     // Mock existing file with different version
     const existingContent =
@@ -199,22 +206,25 @@ describe('downloadAndWriteContextFiles', () => {
     )
   })
 
-  test('handles download errors gracefully', async () => {
+  test('rejects when a context file cannot be downloaded', async () => {
     // Mock fetch to return not ok
     // @ts-expect-error mocking is not 100% consistent with full API and types for
     fetch.mockResolvedValue({
       ok: false,
     })
 
-    // Execute the actual function and expect error
-    await expect(downloadAndWriteContextFiles(mockConsumer, mockRunOptions)).resolves.toBeUndefined()
+    await expect(downloadAndWriteContextFiles(mockConsumer, mockRunOptions)).rejects.toThrow(
+      'An error occurred when pulling the latest context file',
+    )
+    expect(fs.writeFile).not.toHaveBeenCalled()
   })
 
-  test('checks CLI version compatibility', async () => {
+  test('rejects when the CLI is older than the minimum version', async () => {
     // Set higher minimum CLI version
     // @ts-expect-error mocking is not 100% consistent with full API and types for
     fetch.mockResolvedValue({
       ok: true,
+      text: () => Promise.resolve(mockProviderContent),
       headers: {
         get: (header: string) => {
           if (header === 'x-cli-min-ver') return '2.0.0' // Higher than the mocked current version
@@ -223,7 +233,9 @@ describe('downloadAndWriteContextFiles', () => {
       },
     })
 
-    // Execute the actual function and expect error
-    await expect(downloadAndWriteContextFiles(mockConsumer, mockRunOptions)).resolves.toBeUndefined()
+    await expect(downloadAndWriteContextFiles(mockConsumer, mockRunOptions)).rejects.toThrow(
+      'This command requires version 2.0.0',
+    )
+    expect(fs.writeFile).not.toHaveBeenCalled()
   })
 })

tests/unit/recipes/ai-context/index.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, beforeEach, expect, test, vi } from 'vitest'
+
+import type { RunRecipeOptions } from '../../../../src/commands/recipes/recipes.js'
+
+const { cursorConsumer } = vi.hoisted(() => ({
+  cursorConsumer: {
+    key: 'cursor',
+    presentedName: 'Cursor',
+    consumerProcessCmd: 'cursor',
+    path: './.cursor/rules',
+    ext: 'mdc',
+    contextScopes: { serverless: { scope: 'Serverless functions' } },
+  },
+}))
+
+vi.mock('../../../../src/recipes/ai-context/context.js', () => ({
+  NTL_DEV_MCP_FILE_NAME: 'netlify-development.mdc',
+  getContextConsumers: vi.fn().mockResolvedValue([cursorConsumer]),
+  downloadAndWriteContextFiles: vi.fn().mockResolvedValue(true),
+  getExistingContext: vi.fn().mockResolvedValue(null),
+  deleteFile: vi.fn(),
+}))
+
+vi.mock('../../../../src/utils/command-helpers.js', () => ({
+  log: vi.fn(),
+  logAndThrowError: vi.fn((error: unknown) => {
+    throw error
+  }),
+  version: '1.0.0',
+}))
+
+vi.mock('../../../../src/utils/telemetry/index.js', () => ({
+  track: vi.fn(),
+}))
+
+vi.mock('inquirer', () => ({
+  default: { prompt: vi.fn().mockResolvedValue({ consumerKey: 'cursor' }) },
+}))
+
+import { downloadAndWriteContextFiles } from '../../../../src/recipes/ai-context/context.js'
+import { run } from '../../../../src/recipes/ai-context/index.js'
+import { track } from '../../../../src/utils/telemetry/index.js'
+
+const runRecipe = () => run({ args: [], command: { workingDir: '/project' } } as unknown as RunRecipeOptions)
+
+beforeEach(() => {
+  vi.mocked(track).mockClear()
+  vi.stubEnv('AI_CONTEXT_SKIP_DETECTION', 'true')
+})
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+test('tracks sites_aiContextInstalled with the consumer the context was installed for', async () => {
+  await runRecipe()
+
+  expect(track).toHaveBeenCalledWith('sites_aiContextInstalled', { consumer: 'cursor' })
+})
+
+test('does not track an install when every context file was already current', async () => {
+  vi.mocked(downloadAndWriteContextFiles).mockResolvedValueOnce(false)
+
+  await runRecipe()
+
+  expect(track).not.toHaveBeenCalled()
+})
+
+test('does not track an install when writing the context files fails', async () => {
+  vi.mocked(downloadAndWriteContextFiles).mockRejectedValueOnce(new Error('download failed'))
+
+  await expect(runRecipe()).rejects.toThrow('download failed')
+  expect(track).not.toHaveBeenCalled()
+})

tests/unit/utils/command-helpers.test.ts

@@ -1,6 +1,16 @@
 import { describe, expect, test } from 'vitest'
 
-import { normalizeConfig } from '../../../src/utils/command-helpers.js'
+import { USER_AGENT, getRequestUserAgent, normalizeConfig } from '../../../src/utils/command-helpers.js'
+
+describe('getRequestUserAgent', () => {
+  test('appends only the agent name, without its version or source', () => {
+    expect(getRequestUserAgent({ AI_AGENT: 'claude-code@2.1.0' })).toBe(`${USER_AGENT} agent/claude`)
+  })
+
+  test('returns the User-Agent unchanged when no agent is detected', () => {
+    expect(getRequestUserAgent({})).toBe(USER_AGENT)
+  })
+})
 
 describe('normalizeConfig', () => {
   test('should remove publish and publishOrigin property if publishOrigin is "default"', () => {