feat: add FilesystemSink for telemetry audit mode

Author: Hweinstock

src/cli/telemetry/__tests__/filesystem-sink.test.ts

@@ -0,0 +1,105 @@
+import { createTempConfig } from '../../__tests__/helpers/temp-config';
+import { resolveAuditFilePath } from '../config';
+import { FilesystemSink } from '../sinks/filesystem-sink';
+import { readFile } from 'fs/promises';
+import { join } from 'node:path';
+import { afterAll, beforeEach, describe, expect, it } from 'vitest';
+
+const tmp = createTempConfig('fs-sink');
+const outputDir = join(tmp.configDir, 'telemetry');
+
+function createSink(opts: { dir?: string; log?: (msg: string) => void } = {}) {
+  const filePath = join(opts.dir ?? outputDir, 'test-session.json');
+  return new FilesystemSink({ filePath, log: opts.log });
+}
+
+describe('FilesystemSink', () => {
+  beforeEach(() => tmp.setup());
+  afterAll(() => tmp.cleanup());
+
+  it('flush writes buffered entries as a JSON array', async () => {
+    const sink = createSink();
+    sink.record(42, { command_group: 'deploy', command: 'deploy', exit_reason: 'success' });
+
+    await sink.flush();
+
+    const written = JSON.parse(await readFile(join(outputDir, 'test-session.json'), 'utf-8'));
+    expect(written).toHaveLength(1);
+    expect(written[0]).toMatchObject({
+      value: 42,
+      attrs: { command_group: 'deploy', command: 'deploy', exit_reason: 'success' },
+    });
+  });
+
+  it('accumulates multiple records into a single file', async () => {
+    const sink = createSink();
+    sink.record(10, { command_group: 'add', command: 'add.agent' });
+    sink.record(20, { command_group: 'add', command: 'add.memory' });
+
+    await sink.flush();
+
+    const written = JSON.parse(await readFile(join(outputDir, 'test-session.json'), 'utf-8'));
+    expect(written).toHaveLength(2);
+    expect(written[0].value).toBe(10);
+    expect(written[1].value).toBe(20);
+  });
+
+  it('creates output directory if it does not exist', async () => {
+    const nested = join(tmp.testDir, 'deep', 'nested', 'telemetry');
+    const filePath = join(nested, 'test.json');
+    const sink = new FilesystemSink({ filePath });
+    sink.record(1, { command_group: 'status', command: 'status' });
+
+    await sink.flush();
+
+    const written = JSON.parse(await readFile(filePath, 'utf-8'));
+    expect(written).toHaveLength(1);
+  });
+
+  it('flush is a no-op when no records exist', async () => {
+    const sink = createSink();
+    await expect(sink.flush()).resolves.toBeUndefined();
+  });
+
+  it('shutdown writes entries and logs audit message', async () => {
+    const logged: string[] = [];
+    const sink = createSink({ log: msg => logged.push(msg) });
+    sink.record(99, { command_group: 'invoke', command: 'invoke' });
+
+    await sink.shutdown();
+
+    const written = JSON.parse(await readFile(join(outputDir, 'test-session.json'), 'utf-8'));
+    expect(written).toHaveLength(1);
+    expect(logged).toHaveLength(1);
+    expect(logged[0]).toContain('[audit mode]');
+    expect(logged[0]).toContain('test-session.json');
+  });
+
+  it('shutdown does not log when no records were written', async () => {
+    const logged: string[] = [];
+    const sink = createSink({ log: msg => logged.push(msg) });
+
+    await sink.shutdown();
+
+    expect(logged).toHaveLength(0);
+  });
+
+  it('subsequent flushes include all records', async () => {
+    const sink = createSink();
+    sink.record(1, { command_group: 'deploy', command: 'deploy' });
+    await sink.flush();
+
+    sink.record(2, { command_group: 'deploy', command: 'deploy' });
+    await sink.flush();
+
+    const written = JSON.parse(await readFile(join(outputDir, 'test-session.json'), 'utf-8'));
+    expect(written).toHaveLength(2);
+  });
+});
+
+describe('resolveAuditFilePath', () => {
+  it('joins outputDir, entrypoint, and sessionId into a JSON file path', () => {
+    const path = resolveAuditFilePath('/home/user/.agentcore/telemetry', 'deploy', 'abc-123');
+    expect(path).toBe('/home/user/.agentcore/telemetry/deploy-abc-123.json');
+  });
+});

src/cli/telemetry/config.ts

@@ -3,6 +3,7 @@ import { getOrCreateInstallationId, readGlobalConfig } from '../global-config.js
 import { type ResourceAttributes, ResourceAttributesSchema } from './schemas/common-attributes.js';
 import { randomUUID } from 'crypto';
 import os from 'os';
+import { join } from 'path';
 
 // ---------------------------------------------------------------------------
 // Telemetry preference (opt-in / opt-out)
@@ -59,3 +60,11 @@ export async function resolveResourceAttributes(mode: 'cli' | 'tui'): Promise<Re
     'node.version': process.version,
   });
 }
+
+// ---------------------------------------------------------------------------
+// Audit file path
+// ---------------------------------------------------------------------------
+
+export function resolveAuditFilePath(outputDir: string, entrypoint: string, sessionId: string): string {
+  return join(outputDir, `${entrypoint}-${sessionId}.json`);
+}

src/cli/telemetry/index.ts

@@ -1,6 +1,7 @@
-export { resolveTelemetryPreference, resolveResourceAttributes } from './config.js';
+export { resolveTelemetryPreference, resolveResourceAttributes, resolveAuditFilePath } from './config.js';
 export type { TelemetryPreference } from './config.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';
+export { FilesystemSink, type FilesystemSinkConfig } from './sinks/filesystem-sink.js';
 export { classifyError, isUserError } from './error-classification.js';

src/cli/telemetry/sinks/filesystem-sink.ts

@@ -0,0 +1,45 @@
+import type { MetricSink } from './metric-sink.js';
+import { mkdir, writeFile } from 'fs/promises';
+import { dirname } from 'path';
+
+export interface FilesystemSinkConfig {
+  filePath: string;
+  log?: (message: string) => void;
+}
+
+interface RecordedEntry {
+  value: number;
+  attrs: Record<string, string | number>;
+}
+
+export class FilesystemSink implements MetricSink {
+  private readonly entries: RecordedEntry[] = [];
+  private readonly filePath: string;
+  private readonly log: (message: string) => void;
+
+  constructor(config: FilesystemSinkConfig) {
+    this.filePath = config.filePath;
+    this.log = config.log ?? (msg => console.error(msg));
+  }
+
+  record(value: number, attrs: Record<string, string | number>): void {
+    this.entries.push({ value, attrs });
+  }
+
+  async flush(): Promise<void> {
+    await this.writeEntries();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.writeEntries();
+    if (this.entries.length > 0) {
+      this.log(`[audit mode] Telemetry written to ${this.filePath}`);
+    }
+  }
+
+  private async writeEntries(): Promise<void> {
+    if (this.entries.length === 0) return;
+    await mkdir(dirname(this.filePath), { recursive: true });
+    await writeFile(this.filePath, JSON.stringify(this.entries, null, 2));
+  }
+}