feat: add telemetry notice and preference management

Author: Hweinstock

integ-tests/telemetry.test.ts

@@ -0,0 +1,32 @@
+import { spawnAndCollect } from '../src/test-utils/cli-runner.js';
+import { mkdtempSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, describe, expect, it } from 'vitest';
+
+const testConfigDir = mkdtempSync(join(tmpdir(), 'agentcore-integ-'));
+const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.mjs');
+
+function run(args: string[]) {
+  return spawnAndCollect('node', [cliPath, ...args], tmpdir(), {
+    AGENTCORE_SKIP_INSTALL: '1',
+    AGENTCORE_CONFIG_DIR: testConfigDir,
+  });
+}
+
+describe('telemetry e2e', () => {
+  afterAll(() => rm(testConfigDir, { recursive: true, force: true }));
+
+  it('disable → status shows Disabled, enable → status shows Enabled', async () => {
+    await run(['telemetry', 'disable']);
+    let status = await run(['telemetry', 'status']);
+    expect(status.stdout).toContain('Disabled');
+    expect(status.stdout).toContain('global config');
+
+    await run(['telemetry', 'enable']);
+    status = await run(['telemetry', 'status']);
+    expect(status.stdout).toContain('Enabled');
+    expect(status.stdout).toContain('global config');
+  });
+});

src/cli/__tests__/global-config.test.ts

@@ -0,0 +1,99 @@
+import { getOrCreateInstallationId, readGlobalConfig, updateGlobalConfig } from '../global-config';
+import { createTempConfig } from './helpers/temp-config';
+import { readFile, writeFile } from 'fs/promises';
+import { afterAll, beforeEach, describe, expect, it } from 'vitest';
+
+const tmp = createTempConfig('gc');
+
+describe('global-config', () => {
+  beforeEach(() => tmp.setup());
+  afterAll(() => tmp.cleanup());
+
+  describe('readGlobalConfig', () => {
+    it('returns parsed config when file exists', async () => {
+      await writeFile(tmp.configFile, JSON.stringify({ telemetry: { enabled: false } }));
+
+      const config = await readGlobalConfig(tmp.configFile);
+
+      expect(config).toEqual({ telemetry: { enabled: false } });
+    });
+
+    it('returns empty object when file is missing or invalid', async () => {
+      expect(await readGlobalConfig(tmp.testDir + '/nonexistent.json')).toEqual({});
+
+      await writeFile(tmp.configFile, JSON.stringify({ telemetry: { enabled: 'false' } }));
+      expect(await readGlobalConfig(tmp.configFile)).toEqual({});
+    });
+
+    it('preserves unknown fields via passthrough', async () => {
+      const full = {
+        installationId: 'abc-123',
+        telemetry: { enabled: true, endpoint: 'https://example.com', audit: false },
+        futureField: 'hello',
+      };
+      await writeFile(tmp.configFile, JSON.stringify(full));
+
+      const config = await readGlobalConfig(tmp.configFile);
+
+      expect(config).toEqual(full);
+    });
+  });
+
+  describe('updateGlobalConfig', () => {
+    it('creates directory and writes config when none exists', async () => {
+      const fresh = createTempConfig('gc-fresh');
+
+      const ok = await updateGlobalConfig({ telemetry: { enabled: false } }, fresh.configDir, fresh.configFile);
+
+      expect(ok).toBe(true);
+      const written = JSON.parse(await readFile(fresh.configFile, 'utf-8'));
+      expect(written).toEqual({ telemetry: { enabled: false } });
+
+      await fresh.cleanup();
+    });
+
+    it('deep-merges telemetry sub-object with existing config', async () => {
+      await writeFile(
+        tmp.configFile,
+        JSON.stringify({ installationId: 'keep-me', telemetry: { enabled: true, endpoint: 'https://x.com' } })
+      );
+
+      await updateGlobalConfig({ telemetry: { enabled: false } }, tmp.configDir, tmp.configFile);
+
+      const written = JSON.parse(await readFile(tmp.configFile, 'utf-8'));
+      expect(written).toEqual({
+        installationId: 'keep-me',
+        telemetry: { enabled: false, endpoint: 'https://x.com' },
+      });
+    });
+
+    it('returns false on write failures', async () => {
+      const ok = await updateGlobalConfig(
+        { telemetry: { enabled: true } },
+        tmp.testDir + '/\0invalid',
+        tmp.testDir + '/\0invalid/config.json'
+      );
+
+      expect(ok).toBe(false);
+    });
+  });
+
+  describe('getOrCreateInstallationId', () => {
+    it('generates installationId on first run and returns created: true', async () => {
+      const result = await getOrCreateInstallationId(tmp.configDir, tmp.configFile);
+
+      expect(result.created).toBe(true);
+      expect(result.id).toMatch(/^[0-9a-f-]{36}$/);
+      const config = await readGlobalConfig(tmp.configFile);
+      expect(config.installationId).toBe(result.id);
+    });
+
+    it('returns existing id with created: false', async () => {
+      await writeFile(tmp.configFile, JSON.stringify({ installationId: 'existing-id' }));
+
+      const result = await getOrCreateInstallationId(tmp.configDir, tmp.configFile);
+
+      expect(result).toEqual({ id: 'existing-id', created: false });
+    });
+  });
+});

src/cli/__tests__/helpers/temp-config.ts

@@ -0,0 +1,28 @@
+import { mkdir, rm } from 'fs/promises';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export interface TempConfigPaths {
+  testDir: string;
+  configDir: string;
+  configFile: string;
+  setup: () => Promise<void>;
+  cleanup: () => Promise<void>;
+}
+
+export function createTempConfig(label: string): TempConfigPaths {
+  const testDir = join(tmpdir(), `agentcore-${label}-${randomUUID()}`);
+  const configDir = join(testDir, '.agentcore');
+  const configFile = join(configDir, 'config.json');
+  return {
+    testDir,
+    configDir,
+    configFile,
+    setup: async () => {
+      await rm(testDir, { recursive: true, force: true });
+      await mkdir(configDir, { recursive: true });
+    },
+    cleanup: () => rm(testDir, { recursive: true, force: true }),
+  };
+}

src/cli/cli.ts

@@ -14,10 +14,12 @@ import { registerRemove } from './commands/remove';
 import { registerResume } from './commands/resume';
 import { registerRun } from './commands/run';
 import { registerStatus } from './commands/status';
+import { registerTelemetry } from './commands/telemetry';
 import { registerTraces } from './commands/traces';
 import { registerUpdate } from './commands/update';
 import { registerValidate } from './commands/validate';
 import { PACKAGE_VERSION } from './constants';
+import { getOrCreateInstallationId } from './global-config';
 import { ALL_PRIMITIVES } from './primitives';
 import { App } from './tui/App';
 import { LayoutProvider } from './tui/context';
@@ -61,10 +63,37 @@ function setupGlobalCleanup() {
   });
 }
 
+function printTelemetryNotice(): void {
+  const yellow = '\x1b[33m';
+  const reset = '\x1b[0m';
+  process.stderr.write(
+    [
+      '',
+      `${yellow}The AgentCore CLI will soon begin collecting aggregated, anonymous usage`,
+      'analytics to help improve the tool.',
+      'To opt out:          agentcore telemetry disable',
+      `To learn more:       agentcore telemetry --help${reset}`,
+      '',
+      '',
+    ].join('\n')
+  );
+}
+
+function printPostCommandNotices(isFirstRun: boolean, updateCheck: Promise<UpdateCheckResult | null>): Promise<void> {
+  if (isFirstRun) {
+    printTelemetryNotice();
+  }
+  return updateCheck.then(result => {
+    if (result?.updateAvailable) {
+      printUpdateNotification(result);
+    }
+  });
+}
+
 /**
  * Render the TUI in alternate screen buffer mode.
  */
-function renderTUI(updateCheck: Promise<UpdateCheckResult | null>) {
+function renderTUI(updateCheck: Promise<UpdateCheckResult | null>, isFirstRun: boolean) {
   inAltScreen = true;
   process.stdout.write(ENTER_ALT_SCREEN);
 
@@ -82,11 +111,7 @@ function renderTUI(updateCheck: Promise<UpdateCheckResult | null>) {
       clearExitMessage();
     }
 
-    // Print update notification after TUI exits
-    const result = await updateCheck;
-    if (result?.updateAvailable) {
-      printUpdateNotification(result);
-    }
+    await printPostCommandNotices(isFirstRun, updateCheck);
   });
 }
 
@@ -148,6 +173,7 @@ export function registerCommands(program: Command) {
   registerResume(program);
   registerRun(program);
   registerStatus(program);
+  registerTelemetry(program);
   registerTraces(program);
   registerUpdate(program);
   registerValidate(program);
@@ -162,6 +188,9 @@ export const main = async (argv: string[]) => {
   // Register global cleanup handlers once at startup
   setupGlobalCleanup();
 
+  // Generate installationId on first run and show telemetry notice
+  const { created: isFirstRun } = await getOrCreateInstallationId();
+
   const program = createProgram();
 
   const args = argv.slice(2);
@@ -172,15 +201,16 @@ export const main = async (argv: string[]) => {
 
   // Show TUI for no arguments, commander handles --help via configureHelp()
   if (args.length === 0) {
-    renderTUI(updateCheck);
+    renderTUI(updateCheck, isFirstRun);
     return;
   }
 
+  if (isFirstRun) {
+    printTelemetryNotice();
+  }
+
   await program.parseAsync(argv);
 
-  // Print notification after command finishes
-  const result = await updateCheck;
-  if (result?.updateAvailable) {
-    printUpdateNotification(result);
-  }
+  // Telemetry notice already printed above; only run update check here.
+  await printPostCommandNotices(false, updateCheck);
 };

src/cli/commands/telemetry/__tests__/telemetry.test.ts

@@ -0,0 +1,89 @@
+import { createTempConfig } from '../../../__tests__/helpers/temp-config';
+import { readGlobalConfig } from '../../../global-config';
+import { handleTelemetryDisable, handleTelemetryEnable, handleTelemetryStatus } from '../actions';
+import { chmod, mkdir, rm, writeFile } from 'fs/promises';
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const tmp = createTempConfig('actions');
+
+describe('telemetry actions', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => tmp.setup());
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  afterAll(() => tmp.cleanup());
+
+  describe('handleTelemetryDisable', () => {
+    it('writes disabled to config and returns true', async () => {
+      const ok = await handleTelemetryDisable(tmp.configDir, tmp.configFile);
+
+      expect(ok).toBe(true);
+      const config = await readGlobalConfig(tmp.configFile);
+      expect(config.telemetry?.enabled).toBe(false);
+    });
+
+    it('returns false when config write fails', async () => {
+      await rm(tmp.testDir, { recursive: true, force: true });
+      await mkdir(tmp.testDir, { recursive: true });
+      await chmod(tmp.testDir, 0o444);
+
+      const ok = await handleTelemetryDisable(tmp.configDir, tmp.configFile);
+
+      expect(ok).toBe(false);
+
+      await chmod(tmp.testDir, 0o755);
+    });
+  });
+
+  describe('handleTelemetryEnable', () => {
+    it('writes enabled to config and returns true', async () => {
+      const ok = await handleTelemetryEnable(tmp.configDir, tmp.configFile);
+
+      expect(ok).toBe(true);
+      const config = await readGlobalConfig(tmp.configFile);
+      expect(config.telemetry?.enabled).toBe(true);
+    });
+  });
+
+  describe('handleTelemetryStatus', () => {
+    it('reports default source when no config exists', async () => {
+      const spy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+
+      await handleTelemetryStatus(tmp.configFile);
+
+      const output = spy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('Enabled');
+      expect(output).toContain('default');
+      spy.mockRestore();
+    });
+
+    it('reports global-config source when config exists', async () => {
+      await writeFile(tmp.configFile, JSON.stringify({ telemetry: { enabled: false } }));
+      const spy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+
+      await handleTelemetryStatus(tmp.configFile);
+
+      const output = spy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('Disabled');
+      expect(output).toContain('global config');
+      spy.mockRestore();
+    });
+
+    it('reports environment source with env var note', async () => {
+      process.env = { ...originalEnv, AGENTCORE_TELEMETRY_DISABLED: 'true' };
+      const spy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+
+      await handleTelemetryStatus(tmp.configFile);
+
+      const output = spy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('Disabled');
+      expect(output).toContain('environment');
+      expect(output).toContain('AGENTCORE_TELEMETRY_DISABLED');
+      spy.mockRestore();
+    });
+  });
+});

src/cli/commands/telemetry/actions.ts

@@ -0,0 +1,39 @@
+import { GLOBAL_CONFIG_DIR, GLOBAL_CONFIG_FILE, updateGlobalConfig } from '../../global-config.js';
+import { resolveTelemetryPreference } from '../../telemetry/resolve.js';
+
+export async function handleTelemetryDisable(
+  configDir = GLOBAL_CONFIG_DIR,
+  configFile = GLOBAL_CONFIG_FILE
+): Promise<boolean> {
+  const ok = await updateGlobalConfig({ telemetry: { enabled: false } }, configDir, configFile);
+  console.log(ok ? 'Telemetry has been disabled.' : `Warning: could not write config to ${configFile}`);
+  return ok;
+}
+
+export async function handleTelemetryEnable(
+  configDir = GLOBAL_CONFIG_DIR,
+  configFile = GLOBAL_CONFIG_FILE
+): Promise<boolean> {
+  const ok = await updateGlobalConfig({ telemetry: { enabled: true } }, configDir, configFile);
+  console.log(ok ? 'Telemetry has been enabled.' : `Warning: could not write config to ${configFile}`);
+  return ok;
+}
+
+export async function handleTelemetryStatus(configFile = GLOBAL_CONFIG_FILE): Promise<void> {
+  const pref = await resolveTelemetryPreference(configFile);
+
+  const status = pref.enabled ? 'Enabled' : 'Disabled';
+  const sourceLabel =
+    pref.source === 'environment'
+      ? 'environment variable'
+      : pref.source === 'global-config'
+        ? `global config (${configFile})`
+        : 'default';
+
+  console.log(`Telemetry: ${status}`);
+  console.log(`Source: ${sourceLabel}`);
+
+  if (pref.envVar) {
+    console.log(`\nNote: ${pref.envVar.name}=${pref.envVar.value} is set in your environment.`);
+  }
+}