AD-28 Add local telemetry system with output channel and usage data collection

[Finfinder]

Objective

Add a local telemetry system inspired by VS Code's telemetry model (https://code.visualstudio.com/docs/configure/telemetry). The system should collect crash reports, error telemetry, and usage data locally, display telemetry events in the Output panel, and respect user privacy with configurable telemetry levels.

Context

AgentDeck currently has no telemetry whatsoever. When issues occur (crashes, errors, performance problems), there is no diagnostic data to help identify root causes. Additionally, there is no usage data to inform product decisions about which features are most valuable.

VS Code's telemetry model is the natural reference since AgentDeck's UX is inspired by VS Code. However, unlike VS Code (which sends data to Microsoft), AgentDeck should store all telemetry locally only in its existing SQLite store, consistent with the local-first architecture. Remote telemetry can be considered as a future opt-in feature.

Scope

Telemetry Levels

Adopt VS Code's telemetry.telemetryLevel model with four levels:

Level	Crash Reports	Error Telemetry	Usage Data
all	✓	✓	✓
error	✓	✓	-
crash	✓	-	-
off	-	-	-

Default level: all (with clear disclosure in the welcome/onboarding experience).

Event Types and Classification

Three event categories matching VS Code:

1. Crash Reports — unhandled exceptions and process crashes in main/renderer/preload. Collected via crash handlers in main and window.onerror / window.onunhandledrejection in renderer. Includes scrubbed stack traces (no user file paths).

2. Error Telemetry — handled errors that don't crash the app but are unexpected (IPC failures, service initialization errors, file operation failures). Includes error name, message, and scrubbed callstack.

3. Usage Data — feature usage events: panel opened (explorer/search/chat/settings), file opened, chat message sent, model selected, workspace opened, command executed, session duration. No file contents, no code snippets, no personal data.

Event Schema

Each telemetry event stored as:

interface TelemetryEvent {
  id: string;            // UUID v4
  timestamp: string;     // ISO 8601
  type: 'crash' | 'error' | 'usage';
  category: string;      // e.g. 'panel', 'editor', 'chat', 'workspace', 'lifecycle'
  name: string;          // e.g. 'panel.opened', 'file.opened', 'chat.message.sent'
  data: Record<string, string | number | boolean | null>;
  classification: 'SystemMetaData' | 'CallstackOrException' | 'FeatureInsight' | 'PerformanceAndHealth';
}

Storage

• Store telemetry events in the existing SQLite database (packages/services/src/telemetry.ts)
• Table: telemetry_events (id, timestamp, type, category, name, data JSON, classification)
• Configurable retention: default 30 days, auto-purge older events
• Configurable max event count: default 10,000 events, FIFO eviction
• Telemetry data never leaves the local machine in MVP

Telemetry Output Channel

• Add a "Telemetry" output channel to the bottom panel's Output tab
• When enabled via Developer: Show Telemetry command, stream telemetry events to the output channel in real-time
• Events formatted as: [timestamp] [type] category.name: {data}
• Local telemetry.log file in the app's user data directory for offline inspection

Settings Integration

• Add telemetry.telemetryLevel setting (all/error/crash/off) to the Settings Service
• Add a Telemetry category to the Settings panel (from AD-27) with:
  • Telemetry level selector (dropdown)
  • Toggle to enable/disable output channel tracing
  • Button to view telemetry data summary (event count, date range)
  • Button to clear all telemetry data
  • Link to privacy statement

IPC Channels (new)

Add to IPC_CHANNELS in packages/shared/src/ipc.ts:

• telemetryGetLevel = agentdeck:v1:telemetry:get-level
• telemetrySetLevel = agentdeck:v1:telemetry:set-level
• telemetryGetEvents = agentdeck:v1:telemetry:get-events
• telemetryClearEvents = agentdeck:v1:telemetry:clear-events
• telemetryEvent = agentdeck:v1:telemetry:event (push from main to renderer)

Shared Types (new)

Add to packages/shared/src/ipc.ts:

• TelemetryLevel: 'all' | 'error' | 'crash' | 'off'
• TelemetryEventType: 'crash' | 'error' | 'usage'
• TelemetryEvent: the event schema defined above
• TelemetrySettings: { level: TelemetryLevel, outputTracing: boolean }

Main Process Integration

• Add TelemetryService class in packages/services/src/telemetry.ts
• Initialize during desktop service bootstrap (after settings service)
• Hook into crash handlers for crash/error collection
• Provide recordEvent(type, category, name, data, classification) method for usage events from any service
• Respect telemetry level — no-op when set to off

Renderer Integration

• Add telemetry.ts module in packages/workbench/src/ for renderer-side event collection
• Hook into window.onerror and window.onunhandledrejection
• Send usage events to main process via IPC
• Subscribe to telemetryEvent channel for output channel display

Privacy and GDPR

• All telemetry stored locally — no network transmission in MVP
• No file contents, source code, API keys, tokens, or personal data in events
• Stack traces scrubbed of user home directory paths
• User can disable all telemetry via telemetry.telemetryLevel: 'off'
• User can clear all telemetry data at any time
• Privacy notice displayed on first launch (or in Welcome view) explaining what is collected
• SECURITY.md updated to document telemetry practices

Rationale

A local telemetry system is essential for diagnosing issues in a desktop application where users cannot easily report bugs with reproducible steps. The VS Code model is well-understood, privacy-respecting, and provides a proven framework. Keeping all data local aligns with AgentDeck's local-first architecture while still providing diagnostic value. The output channel pattern gives power users visibility into what is collected, building trust.

Benefits

• Diagnose crashes and errors without requiring user bug reports
• Understand feature usage to prioritize development
• Output channel transparency builds user trust
• Local-only storage respects privacy and works offline
• Configurable levels give users control
• Foundation for future: remote opt-in telemetry, performance profiling, A/B experimentation

Definition of Done

• TelemetryService class in packages/services/src/telemetry.ts with SQLite storage
• Telemetry level setting (all/error/crash/off) integrated into Settings Service
• Crash report collection via crash handlers in main process
• Error telemetry collection from service failures across all packages
• Usage event collection for: panel switches, file opens, chat messages, workspace opens, commands
• Telemetry events stored in SQLite with configurable retention (30 days / 10k events default)
• Telemetry output channel in bottom panel Output tab showing real-time events
• telemetry.log file in user data directory
• Telemetry category in Settings panel with level selector, tracing toggle, data summary, and clear button
• New IPC channels registered in preload and main process
• Shared types added to packages/shared/src/ipc.ts
• Stack trace scrubbing removes user file paths
• No file contents, source code, or secrets in any telemetry event
• Telemetry completely disabled (no collection, no storage) when level is off
• Privacy notice in Welcome view or first-launch experience
• SECURITY.md updated with telemetry documentation
• Keyboard-accessible telemetry output channel
• All UI elements meet WCAG 2.1 AA contrast requirements

Milestone

1.0 Stabilize MVP