[Telemetry] Implement Phase 2: Watchdog Process

Author: ergunsh

src/telemetry/watchdog/clearcut-sender.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import crypto from 'node:crypto';
+
+import {logger} from '../../logger.js';
+import type {ChromeDevToolsMcpExtension, OsType} from '../types.js';
+
+const SESSION_ROTATION_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+export class ClearcutSender {
+  #appVersion: string;
+  #osType: OsType;
+  #sessionId: string;
+  #sessionCreated: number;
+
+  constructor(appVersion: string, osType: OsType) {
+    this.#appVersion = appVersion;
+    this.#osType = osType;
+    this.#sessionId = crypto.randomUUID();
+    this.#sessionCreated = Date.now();
+  }
+
+  async send(event: ChromeDevToolsMcpExtension): Promise<void> {
+    this.#rotateSessionIfNeeded();
+    const enrichedEvent = this.#enrichEvent(event);
+    this.transport(enrichedEvent);
+  }
+
+  // Public for stubbing in tests
+  transport(event: ChromeDevToolsMcpExtension): void {
+    logger('Telemetry event', JSON.stringify(event, null, 2));
+  }
+
+  async sendShutdownEvent(): Promise<void> {
+    // CRITICAL: Do not include flag_usage
+    const shutdownEvent: ChromeDevToolsMcpExtension = {
+      server_shutdown: {},
+    };
+    await this.send(shutdownEvent);
+  }
+
+  #rotateSessionIfNeeded(): void {
+    if (Date.now() - this.#sessionCreated > SESSION_ROTATION_INTERVAL_MS) {
+      this.#sessionId = crypto.randomUUID();
+      this.#sessionCreated = Date.now();
+    }
+  }
+
+  #enrichEvent(event: ChromeDevToolsMcpExtension): ChromeDevToolsMcpExtension {
+    return {
+      ...event,
+      session_id: this.#sessionId,
+      app_version: this.#appVersion,
+      os_type: this.#osType,
+      // client_info.client_type could be added here if we passed it in constructor or knew it
+      // but strictly following plan, we populate these specific fields.
+    };
+  }
+}

src/telemetry/watchdog/main.ts

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * See IMPLEMENTATION_PLAN.md for details
+ */
+
+import process from 'node:process';
+import readline from 'node:readline';
+
+import yargs from 'yargs';
+import {hideBin} from 'yargs/helpers';
+
+import {logger, saveLogsToFile} from '../../logger.js';
+import {IpcMessageType, OsType} from '../types.js';
+
+import {ClearcutSender} from './clearcut-sender.js';
+
+async function main() {
+  const argv = await yargs(hideBin(process.argv))
+    .option('parent-pid', {
+      type: 'number',
+      demandOption: true,
+      describe: 'PID of the main process to monitor',
+    })
+    .option('app-version', {
+      type: 'string',
+      demandOption: true,
+      describe: 'Application version string',
+    })
+    .option('os-type', {
+      type: 'number',
+      demandOption: true,
+      describe: 'Integer specific to OsType',
+    })
+    .option('log-file', {
+      type: 'string',
+      describe: 'Optional path to log file',
+    })
+    .parse();
+
+  if (argv.logFile) {
+    saveLogsToFile(argv.logFile);
+  }
+
+  logger('Watchdog started', {
+    parentPid: argv.parentPid,
+    version: argv.appVersion,
+    osType: argv.osType,
+  });
+
+  const sender = new ClearcutSender(argv.appVersion, argv.osType as OsType);
+
+  // === Death Detection ===
+  // We rely on Stdin pipe closing to detect parent death.
+  // This works even with `kill -9` on the parent.
+  function onParentDeath(reason: string) {
+    logger(`Parent death detected (${reason}). Sending shutdown event...`);
+    // We can't await here effectively in all cases, but we try our best.
+    sender
+      .sendShutdownEvent()
+      .then(() => {
+        logger('Shutdown event sent. Exiting.');
+        process.exit(0);
+      })
+      .catch((err) => {
+        logger('Failed to send shutdown event', err);
+        process.exit(1);
+      });
+  }
+
+  process.stdin.on('end', () => onParentDeath('stdin end'));
+  process.stdin.on('close', () => onParentDeath('stdin close'));
+
+  // Double check disconnection if spawned with IPC channel (not strictly required by plan but good practice)
+  process.on('disconnect', () => onParentDeath('ipc disconnect'));
+
+  // === IPC Handling ===
+  const rl = readline.createInterface({
+    input: process.stdin,
+    terminal: false,
+  });
+
+  rl.on('line', (line) => {
+    try {
+      if (!line.trim()) return;
+      
+      const msg = JSON.parse(line);
+      if (msg.type === IpcMessageType.DATA && msg.payload) {
+        sender.send(msg.payload).catch((err) => {
+          logger('Error sending event', err);
+        });
+      }
+    } catch (err) {
+      logger('Failed to parse IPC message', err);
+    }
+  });
+}
+
+main().catch((err) => {
+  console.error('Watchdog fatal error:', err);
+  process.exit(1);
+});

tests/telemetry/watchdog/clearcut-sender.test.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import crypto from 'node:crypto';
+import sinon from 'sinon';
+import {describe, it, afterEach, beforeEach} from 'node:test';
+import assert from 'node:assert';
+import {OsType} from '../../../src/telemetry/types.js';
+import {ClearcutSender} from '../../../src/telemetry/watchdog/clearcut-sender.js';
+
+describe('ClearcutSender', () => {
+  let clock: sinon.SinonFakeTimers;
+  let randomUUIDStub: sinon.SinonStub;
+
+  beforeEach(() => {
+    clock = sinon.useFakeTimers();
+    let uuidCounter = 0;
+    randomUUIDStub = sinon.stub(crypto, 'randomUUID').callsFake(() => {
+      return `uuid-${++uuidCounter}` as any;
+    });
+  });
+
+  afterEach(() => {
+    clock.restore();
+    randomUUIDStub.restore();
+    sinon.restore();
+  });
+
+  it('enriches events with app version, os type, and session id', async () => {
+    const sender = new ClearcutSender('1.0.0', OsType.OS_TYPE_MACOS);
+    const transportStub = sinon.stub(sender, 'transport');
+
+    await sender.send({mcp_client: undefined});
+
+    assert.strictEqual(transportStub.callCount, 1);
+    const event = transportStub.firstCall.args[0];
+    
+    assert.strictEqual(event.session_id, 'uuid-1');
+    assert.strictEqual(event.app_version, '1.0.0');
+    assert.strictEqual(event.os_type, OsType.OS_TYPE_MACOS);
+  });
+
+  it('rotates session ID after 24 hours', async () => {
+    const sender = new ClearcutSender('1.0.0', OsType.OS_TYPE_MACOS);
+    const transportStub = sinon.stub(sender, 'transport');
+
+    // First call -> session uuid-1
+    await sender.send({});
+    assert.strictEqual(transportStub.lastCall.args[0].session_id, 'uuid-1');
+
+    // Advance time by 23 hours -> should NOT rotate
+    clock.tick(23 * 60 * 60 * 1000);
+    await sender.send({});
+    assert.strictEqual(transportStub.lastCall.args[0].session_id, 'uuid-1');
+
+    // Advance time by 2 hours (total 25h) -> SHOULD rotate
+    clock.tick(2 * 60 * 60 * 1000);
+    await sender.send({});
+    assert.strictEqual(transportStub.lastCall.args[0].session_id, 'uuid-2');
+  });
+
+  it('sendShutdownEvent sends a server_shutdown event without flag_usage', async () => {
+    const sender = new ClearcutSender('1.0.0', OsType.OS_TYPE_MACOS);
+    const transportStub = sinon.stub(sender, 'transport');
+
+    await sender.sendShutdownEvent();
+    
+    const event = transportStub.firstCall.args[0];
+    assert.ok(event.server_shutdown);
+    assert.strictEqual(event.server_start, undefined);
+  });
+});