feat: add User-Agent tracking for analytics

src/bin/cmd-agent.ts

@@ -7,6 +7,7 @@ import * as readline from "readline";
 import { CLIAgent, type Provider } from "../clients/cli-agent.js";
 import { MultiIndexRunner } from "../clients/multi-index-runner.js";
 import { CompositeStoreReader, parseIndexSpecs } from "../stores/index.js";
+import { buildClientUserAgent } from "../core/utils.js";
 
 const PROVIDER_DEFAULTS: Record<Provider, string> = {
   openai: "gpt-5-mini",
@@ -50,9 +51,13 @@ export const agentCommand = new Command("agent")
       const store = await CompositeStoreReader.fromSpecs(specs);
 
       // Create multi-index runner
+      // Build User-Agent for analytics tracking
+      const clientUserAgent = buildClientUserAgent("cli-agent");
+
       const runner = await MultiIndexRunner.create({
         store,
         searchOnly: options.searchOnly,
+        clientUserAgent,
       });
 
       console.log("\x1b[1;36mContext Connectors Minimal Agent\x1b[0m");
@@ -73,6 +78,7 @@ export const agentCommand = new Command("agent")
         model,
         maxSteps: options.maxSteps,
         verbose: options.verbose,
+        clientUserAgent,
       });
       await agent.initialize();
 

src/bin/cmd-index.ts

@@ -7,6 +7,7 @@ import { Indexer } from "../core/indexer.js";
 import { Source } from "../sources/types.js";
 import { FilesystemStore } from "../stores/filesystem.js";
 import { getS3Config } from "../stores/s3-config.js";
+import { buildClientUserAgent } from "../core/utils.js";
 
 // Shared store options
 interface StoreOptions {
@@ -49,7 +50,9 @@ async function runIndex(
   sourceType: string
 ) {
   console.log(`Indexing ${sourceType} source...`);
-  const indexer = new Indexer();
+  const indexer = new Indexer({
+    clientUserAgent: buildClientUserAgent("cli-index"),
+  });
   const result = await indexer.index(source, store, indexKey);
 
   console.log(`\nIndexing complete!`);

src/bin/cmd-search.ts

@@ -9,6 +9,7 @@ import { getSourceIdentifier } from "../core/types.js";
 import { getS3Config } from "../stores/s3-config.js";
 import { parseIndexSpec } from "../stores/index-spec.js";
 import type { IndexStoreReader } from "../stores/types.js";
+import { buildClientUserAgent } from "../core/utils.js";
 
 export const searchCommand = new Command("search")
   .description("Search indexed content and answer questions (use --raw for raw results)")
@@ -83,6 +84,7 @@ export const searchCommand = new Command("search")
       const client = new SearchClient({
         store,
         indexName: indexKey,
+        clientUserAgent: buildClientUserAgent("cli-search"),
       });
 
       await client.initialize();

src/clients/cli-agent.ts

@@ -79,6 +79,12 @@
   stream?: boolean;
   /** Custom system prompt. Uses a sensible default if not provided. */
   systemPrompt?: string;
+  /**
+   * Custom User-Agent string for analytics tracking.
+   * When provided, this is sent to the Augment API for usage analytics.
+   * Only used when provider is 'augment'.
+   */
+  clientUserAgent?: string;
 }
 
 /**
@@ -110,6 +116,12 @@
   stream?: boolean;
   /** Custom system prompt. Uses a sensible default if not provided. */
   systemPrompt?: string;
+  /**
+   * Custom User-Agent string for analytics tracking.
+   * When provided, this is sent to the Augment API for usage analytics.
+   * Only used when provider is 'augment'.
+   */
+  clientUserAgent?: string;
 }
 
 /** Configuration for the CLI agent */
@@ -136,7 +148,8 @@
  */
 async function loadModel(
   provider: Provider,
-  modelName: string
+  modelName: string,
+  clientUserAgent?: string
 ): Promise<LanguageModel> {
   switch (provider) {
     case "openai": {
@@ -179,6 +192,7 @@
       return new AugmentLanguageModel(modelName, {
         apiKey: credentials.apiKey,
         apiUrl: credentials.apiUrl,
+        clientUserAgent,
       }) as unknown as LanguageModel;
     }
     default:
@@ -223,6 +237,7 @@
   private readonly verbose: boolean;
   private readonly stream: boolean;
   private readonly systemPrompt: string;
+  private readonly clientUserAgent?: string;
   private readonly tools: ToolSet;
   private messages: CoreMessage[] = [];
 
@@ -242,6 +257,7 @@
     this.verbose = config.verbose ?? false;
     this.stream = config.stream ?? true;
     this.systemPrompt = config.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+    this.clientUserAgent = config.clientUserAgent;
     this.tools = this.runner ? this.createMultiIndexTools() : this.createSingleClientTools();
   }
 
@@ -393,7 +409,7 @@
    * @throws Error if the provider package is not installed
    */
   async initialize(): Promise<void> {
-    this.model = await loadModel(this.provider, this.modelName);
+    this.model = await loadModel(this.provider, this.modelName, this.clientUserAgent);
   }
 
   /**

src/clients/mcp-server.ts

@@ -39,6 +39,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import type { IndexStoreReader } from "../stores/types.js";
 import { MultiIndexRunner } from "./multi-index-runner.js";
+import { buildClientUserAgent } from "../core/utils.js";
 import {
   SEARCH_DESCRIPTION,
   LIST_FILES_DESCRIPTION,
@@ -96,10 +97,14 @@ export async function createMCPServer(
   config: MCPServerConfig
 ): Promise<Server> {
   // Create shared runner for multi-index operations
+  // Build User-Agent for analytics tracking
+  const clientUserAgent = buildClientUserAgent("mcp");
+
   const runner = await MultiIndexRunner.create({
     store: config.store,
     indexNames: config.indexNames,
     searchOnly: config.searchOnly,
+    clientUserAgent,
   });
 
   const { indexNames, indexes } = runner;

src/clients/multi-index-runner.ts

@@ -36,6 +36,11 @@ export interface MultiIndexRunnerConfig {
    * When true, only search is available.
    */
   searchOnly?: boolean;
+  /**
+   * Custom User-Agent string for analytics tracking.
+   * When provided, this is passed to SearchClient instances for API requests.
+   */
+  clientUserAgent?: string;
 }
 
 /** Create a Source from index state metadata */
@@ -65,6 +70,7 @@ async function createSourceFromState(state: IndexStateSearchOnly): Promise<Sourc
 export class MultiIndexRunner {
   private readonly store: IndexStoreReader;
   private readonly searchOnly: boolean;
+  private readonly clientUserAgent?: string;
   private readonly clientCache = new Map<string, SearchClient>();
 
   /** Available index names */
@@ -77,12 +83,14 @@ export class MultiIndexRunner {
     store: IndexStoreReader,
     indexNames: string[],
     indexes: IndexInfo[],
-    searchOnly: boolean
+    searchOnly: boolean,
+    clientUserAgent?: string
   ) {
     this.store = store;
     this.indexNames = indexNames;
     this.indexes = indexes;
     this.searchOnly = searchOnly;
+    this.clientUserAgent = clientUserAgent;
   }
 
   /**
@@ -132,7 +140,7 @@ export class MultiIndexRunner {
       throw new Error("No valid indexes available (all indexes failed to load)");
     }
 
-    return new MultiIndexRunner(store, validIndexNames, indexes, searchOnly);
+    return new MultiIndexRunner(store, validIndexNames, indexes, searchOnly, config.clientUserAgent);
   }
 
   /**
@@ -158,6 +166,7 @@ export class MultiIndexRunner {
         store: this.store,
         source,
         indexName,
+        clientUserAgent: this.clientUserAgent,
       });
       await client.initialize();
       this.clientCache.set(indexName, client);

src/clients/search-client.ts

@@ -66,6 +66,11 @@
    * @default process.env.AUGMENT_API_URL
    */
   apiUrl?: string;
+  /**
+   * Custom User-Agent string for analytics tracking.
+   * When provided, this is sent to the Augment API for usage analytics.
+   */
+  clientUserAgent?: string;
 }
 
 /**
@@ -106,6 +111,7 @@
   private indexName: string;
   private apiKey: string;
   private apiUrl: string;
+  private clientUserAgent?: string;
 
   private context: DirectContext | null = null;
   private state: IndexStateSearchOnly | null = null;
@@ -123,6 +129,7 @@
     this.indexName = config.indexName;
     this.apiKey = config.apiKey ?? process.env.AUGMENT_API_TOKEN ?? "";
     this.apiUrl = config.apiUrl ?? process.env.AUGMENT_API_URL ?? "";
+    this.clientUserAgent = config.clientUserAgent;
   }
 
   /**
@@ -162,6 +169,7 @@
     this.context = await DirectContext.import(this.state.contextState, {
       apiKey: this.apiKey,
       apiUrl: this.apiUrl,
+      clientUserAgent: this.clientUserAgent,
     });
   }
 

src/core/index.ts

@@ -20,7 +20,8 @@ export {
   shouldFilterFile,
 } from "./file-filter.js";
 
-export { sanitizeKey, isoTimestamp } from "./utils.js";
+export { sanitizeKey, isoTimestamp, buildClientUserAgent } from "./utils.js";
+export type { ClientInterface, MCPClientInfo } from "./utils.js";
 
 export { Indexer } from "./indexer.js";
 export type { IndexerConfig } from "./indexer.js";

src/core/indexer.ts

@@ -53,6 +53,11 @@
    * @default process.env.AUGMENT_API_URL
    */
   apiUrl?: string;
+  /**
+   * Custom User-Agent string for analytics tracking.
+   * When provided, this is sent to the Augment API for usage analytics.
+   */
+  clientUserAgent?: string;
 }
 
 /**
@@ -82,6 +87,7 @@
 export class Indexer {
   private readonly apiKey?: string;
   private readonly apiUrl?: string;
+  private readonly clientUserAgent?: string;
 
   /**
    * Create a new Indexer instance.
@@ -91,6 +97,7 @@
   constructor(config: IndexerConfig = {}) {
     this.apiKey = config.apiKey ?? process.env.AUGMENT_API_TOKEN;
     this.apiUrl = config.apiUrl ?? process.env.AUGMENT_API_URL;
+    this.clientUserAgent = config.clientUserAgent;
   }
 
   /**
@@ -191,6 +198,7 @@
     const context = await DirectContext.create({
       apiKey: this.apiKey,
       apiUrl: this.apiUrl,
+      clientUserAgent: this.clientUserAgent,
     });
 
     // Fetch all files from source
@@ -254,6 +262,7 @@
     const context = await DirectContext.import(previousState.contextState, {
       apiKey: this.apiKey,
       apiUrl: this.apiUrl,
+      clientUserAgent: this.clientUserAgent,
     });
 
     // Remove deleted files

src/core/utils.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Tests for utility functions
+ */
+
+import { describe, it, expect } from "vitest";
+import { buildClientUserAgent } from "./utils.js";
+
+describe("buildClientUserAgent", () => {
+  it("should build basic user agent for cli-search", () => {
+    const ua = buildClientUserAgent("cli-search");
+    expect(ua).toMatch(/^context-connectors\/\d+\.\d+\.\d+ via:cli-search$/);
+  });
+
+  it("should build basic user agent for cli-index", () => {
+    const ua = buildClientUserAgent("cli-index");
+    expect(ua).toMatch(/^context-connectors\/\d+\.\d+\.\d+ via:cli-index$/);
+  });
+
+  it("should build basic user agent for mcp", () => {
+    const ua = buildClientUserAgent("mcp");
+    expect(ua).toMatch(/^context-connectors\/\d+\.\d+\.\d+ via:mcp$/);
+  });
+
+  it("should include MCP client info when provided", () => {
+    const ua = buildClientUserAgent("mcp", { name: "claude-desktop", version: "1.2.0" });
+    expect(ua).toMatch(/^context-connectors\/\d+\.\d+\.\d+ via:mcp client:claude-desktop\/1\.2\.0$/);
+  });
+
+  it("should handle all interface types", () => {
+    const interfaces = [
+      "cli-search",
+      "sdk-search",
+      "cli-index",
+      "sdk-index",
+      "mcp",
+      "cli-agent",
+      "sdk-agent-provider",
+    ] as const;
+
+    for (const iface of interfaces) {
+      const ua = buildClientUserAgent(iface);
+      expect(ua).toContain(`via:${iface}`);
+      expect(ua).toContain("context-connectors/");
+    }
+  });
+});