feat: instrument help.modes with telemetry, add audit integ test

Author: Hweinstock

integ-tests/help.test.ts

@@ -1,5 +1,10 @@
+import { spawnAndCollect } from '../src/test-utils/cli-runner.js';
 import { runCLI } from '../src/test-utils/index.js';
-import { describe, expect, it } from 'vitest';
+import { readdirSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 const COMMANDS = [
   'create',
@@ -38,3 +43,57 @@ describe('CLI help', () => {
     }
   });
 });
+
+describe('help modes telemetry', () => {
+  let testConfigDir: string;
+  const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.mjs');
+
+  beforeAll(async () => {
+    testConfigDir = join(tmpdir(), `agentcore-help-telemetry-${Date.now()}`);
+    await mkdir(testConfigDir, { recursive: true });
+  });
+  afterAll(() => rm(testConfigDir, { recursive: true, force: true }));
+
+  function run(args: string[]) {
+    return spawnAndCollect('node', [cliPath, ...args], tmpdir(), {
+      AGENTCORE_SKIP_INSTALL: '1',
+      AGENTCORE_CONFIG_DIR: testConfigDir,
+    });
+  }
+
+  it('writes JSONL audit file when audit is enabled', async () => {
+    await writeFile(join(testConfigDir, 'config.json'), JSON.stringify({ telemetry: { audit: true } }));
+
+    const result = await run(['help', 'modes']);
+    expect(result.exitCode).toBe(0);
+
+    const telemetryDir = join(testConfigDir, 'telemetry');
+    const files = readdirSync(telemetryDir).filter(f => f.startsWith('help-'));
+    expect(files).toHaveLength(1);
+
+    const content = await readFile(join(telemetryDir, files[0]!), 'utf-8');
+    const entry = JSON.parse(content.trim());
+    expect(entry.attrs).toMatchObject({
+      command_group: 'help',
+      command: 'help.modes',
+      exit_reason: 'success',
+    });
+    expect(entry.value).toBeGreaterThanOrEqual(0);
+  });
+
+  it('does not write audit file when audit is disabled', async () => {
+    await writeFile(join(testConfigDir, 'config.json'), JSON.stringify({ telemetry: { audit: false } }));
+    const telemetryDir = join(testConfigDir, 'telemetry');
+    await rm(telemetryDir, { recursive: true, force: true });
+
+    const result = await run(['help', 'modes']);
+    expect(result.exitCode).toBe(0);
+
+    try {
+      const files = readdirSync(telemetryDir);
+      expect(files).toHaveLength(0);
+    } catch {
+      // telemetry dir doesn't exist — correct
+    }
+  });
+});

src/cli/commands/help/command.tsx

@@ -1,3 +1,4 @@
+import { bootstrapTelemetry } from '../../telemetry/bootstrap.js';
 import type { Command } from '@commander-js/extra-typings';
 
 const MODES_HELP = `
@@ -49,7 +50,12 @@ export const registerHelp = (program: Command) => {
   helpCmd
     .command('modes')
     .description('Explain interactive vs non-interactive modes')
-    .action(() => {
-      console.log(MODES_HELP);
+    .action(async () => {
+      const client = await bootstrapTelemetry('help');
+      await client.withCommandRun('help.modes', () => {
+        console.log(MODES_HELP);
+        return {};
+      });
+      await client.shutdown();
     });
 };

src/cli/telemetry/bootstrap.ts

@@ -0,0 +1,21 @@
+import { GLOBAL_CONFIG_DIR, readGlobalConfig } from '../global-config.js';
+import { TelemetryClient } from './client.js';
+import { resolveAuditFilePath, resolveResourceAttributes } from './config.js';
+import { FilesystemSink } from './sinks/filesystem-sink.js';
+import { InMemorySink } from './sinks/in-memory-sink.js';
+import { join } from 'path';
+
+export async function bootstrapTelemetry(entrypoint: string, mode: 'cli' | 'tui' = 'cli'): Promise<TelemetryClient> {
+  const [resource, config] = await Promise.all([resolveResourceAttributes(mode), readGlobalConfig()]);
+
+  if (config.telemetry?.audit) {
+    const filePath = resolveAuditFilePath(
+      join(GLOBAL_CONFIG_DIR, 'telemetry'),
+      entrypoint,
+      resource['agentcore-cli.session_id']
+    );
+    return new TelemetryClient(new FilesystemSink({ filePath }));
+  }
+
+  return new TelemetryClient(new InMemorySink());
+}

src/cli/telemetry/index.ts

@@ -1,5 +1,6 @@
 export { resolveTelemetryPreference, resolveResourceAttributes, resolveAuditFilePath } from './config.js';
 export type { TelemetryPreference } from './config.js';
+export { bootstrapTelemetry } from './bootstrap.js';
 export { TelemetryClient, CANCELLED } from './client.js';
 export { type MetricSink, CompositeSink } from './sinks/metric-sink.js';
 export { OtelMetricSink, type OtelMetricSinkConfig } from './sinks/otel-metric-sink.js';