Add initial plan and update types

Author: ergunsh

IMPLEMENTATION_PLAN.md

@@ -0,0 +1,118 @@
+# Specification: Watchdog Process Architecture
+
+This document specifies the architecture for isolating telemetry into a separate "Sidecar" process (Watchdog) to ensure reliable event transmission during identifying host handling (e.g. `kill -9`).
+
+## Architecture
+
+The system consists of two processes:
+1.  **Main Process (Client)**: The DevTools MCP server. Spawns the Watchdog and sends raw telemetry events via IPC (Stdin).
+2.  **Watchdog Process (Server)**: A simplified Node.js process. Manages Session IDs, enriches events, and handles the reliable transmission of `server_shutdown` upon detecting Main Process death.
+
+## Phase 1: Shared Core & Types (src/telemetry/types.ts)
+
+Define the IPC protocol between Master and Watchdog.
+
+*   **Modify** `src/telemetry/types.ts`:
+    *   `IpcMessageType` enum: `DATA = 'data'`.
+    *   `TelemetryEvent` interface: `{ type: IpcMessageType, payload: ChromeDevToolsMcpExtension }`.
+    *   Ensure `ChromeDevToolsMcpExtension` (Protobuf mapping) is exported.
+    *   Add `ServerShutdown` interface: `export interface ServerShutdown {}`.
+    *   Update `ChromeDevToolsMcpExtension` to include `server_shutdown?: ServerShutdown`.
+
+## Phase 2: Watchdog Process (The Sidecar)
+
+Location: `src/telemetry/watchdog/`
+
+### 2.1 Watchdog Sender (`src/telemetry/watchdog/clearcut-sender.ts`)
+
+A stateful class responsible for session management and transport.
+
+**State:**
+*   `#appVersion`: string
+*   `#osType`: OsType
+*   `#sessionId`: string (Hex string)
+*   `#sessionCreated`: number (Timestamp)
+
+**Behavior:**
+*   **Initialization**:
+    *   Generate initial `#sessionId` using `crypto.randomUUID()`.
+    *   Set `#sessionCreated = Date.now()`.
+*   **`send(event: ChromeDevToolsMcpExtension)`**:
+    1.  **Session Rotation**:
+        *   Check `Date.now() - #sessionCreated > 24 * 60 * 60 * 1000` (24 hours).
+        *   If expired: Generate new `#sessionId` (UUID), reset `#sessionCreated`.
+    2.  **Enrichment**: deeply clone `event`. Populate:
+        *   `client_info.client_type`
+        *   `session_id` (from state)
+        *   `app_version` (from state)
+        *   `os_type` (from state)
+    3.  **Transport**:
+        *   Log the JSON stringified event using the `logger` from `../../logger.js`.
+*   **`sendShutdownEvent()`**:
+    *   Construct `server_shutdown` event.
+    *   **CRITICAL**: Do *not* include `flag_usage` (Main process might not have sent it if crashed).
+    *   Calls `this.send(shutdownEvent)`.
+
+### 2.2 Watchdog Entry Point (`src/telemetry/watchdog/main.ts`)
+
+The executable script.
+
+**Inputs (CLI Args):**
+*   `--parent-pid`: PID of the Main Process to monitor.
+*   `--app-version`: String.
+*   `--os-type`: Integer (OsType).
+*   `--log-file`: Absolute path for debugging logs (optional).
+
+**Logic Flow:**
+1.  **Bootstrap**:
+    *   **Arg Parsing**: Use `yargs` to parse command line arguments widely.
+    *   Setup internal logging (to file if `--log-file` provided, otherwise silent/stderr).
+    *   Instantiate `ClearcutSender`.
+2.  **IPC Handling (Stdin)**:
+    *   `process.stdin.resume()` and set encoding `utf8`.
+    *   Stream parser (using `readline` or buffer splitting) for newline-delimited JSON.
+    *   On valid message: `sender.send(payload)`.
+3.  **Death Detection**:
+    *   **Mechanism**: Listen for `process.stdin.on('end')` and `('close')`.
+    *   **Trigger**: On either event:
+        1.  Log "Parent death detected".
+        2.  `await sender.sendShutdownEvent()`.
+        3.  `process.exit(0)`.
+4.  **Disconnect**: Handle `process.on('disconnect')` similarly to death.
+
+## Phase 3: Main Process Client (`src/telemetry/watchdog-client.ts`)
+
+Abstracts the sidecar management.
+
+**Class: `WatchdogClient`**
+*   **Constructor**:
+    *   `parentPid`, `appVersion`, `osType`, `logFile`.
+*   **Spawning Logic**:
+    *   **Path Resolution**: Use `import.meta.url` to resolve the absolute path to `watchdog/main.js`.
+        ```javascript
+        const watchdogPath = fileURLToPath(new URL('./watchdog/main.js', import.meta.url));
+        ```
+    *   **Spawn**: `child_process.spawn(process.execPath, [watchdogPath, ...dependencies])`.
+    *   **Stdio Config**: `['pipe', 'ignore', 'ignore']` (Strictly ignore output, rely on `--log-file`).
+    *   **Lifecycle**: `unref()` the child so it doesn't block Main Process exit.
+*   **`send(message: TelemetryEvent)`**:
+    *   JSON-stringify `event`.
+    *   Append `\n`.
+    *   Write to `child.stdin`.
+    *   Handle errors (EPIPE) gracefully (log warning, do not crash).
+
+## Phase 4: Integration & Testing
+
+### 4.1 Refactor `ClearcutLogger`
+*   Remove direct `ClearcutSender` usage.
+*   Instantiate `WatchdogClient` in constructor.
+*   Proxy methods (`logToolInvocation`, etc.) to `client.send()`.
+
+### 4.2 Verification Plan
+1.  **Unit Tests**:
+    *   `clearcut-sender.test.ts`: Verify enrichment and session rotation logic mocking Date.
+2.  **Integration Tests (`spawn-kill-verify`)**:
+    *   Script: Spawn Main Process (mock).
+    *   Main Process spawns Watchdog.
+    *   Main Process kills itself (`kill -9`).
+    *   **Assert**: Watchdog writes `server_shutdown` to log/transport before exiting.

src/telemetry/types.ts

@@ -13,8 +13,11 @@ export interface ChromeDevToolsMcpExtension {
   tool_invocation?: ToolInvocation;
   server_start?: ServerStart;
   daily_active?: DailyActive;
+  server_shutdown?: ServerShutdown;
 }
 
+export interface ServerShutdown {}
+
 export interface ToolInvocation {
   tool_name: string;
   success: boolean;
@@ -44,6 +47,16 @@ export interface LogRequest {
   }>;
 }
 
+// IPC Types
+export enum IpcMessageType {
+  DATA = 'data',
+}
+
+export interface TelemetryEvent {
+  type: IpcMessageType.DATA;
+  payload: ChromeDevToolsMcpExtension;
+}
+
 // Enums
 export enum OsType {
   OS_TYPE_UNSPECIFIED = 0,