@yezack/chrome-devtools-mcp-108 0.0.0-stage → 1.10.2

package/build/src/processors/PerformanceTrace.js

@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DevTools } from '../third_party/index.js';
+import { logger } from '../utils/logger.js';
+import { parseTraceEventsFromBuffer } from './ChunkedTraceParser.js';
+/**
+ * Type guard that verifies if an operation returned a valid TraceResult.
+ *
+ * @param x - The result or error object to inspect.
+ * @returns True if the object is a TraceResult; otherwise false.
+ */
+export function traceResultIsSuccess(x) {
+    return 'parsedTrace' in x;
+}
+/**
+ * Parses raw JSON trace buffer bytes into a DevTools TraceEngine representation.
+ *
+ * Accepts either a JSON array of trace events or an object with a `traceEvents` field.
+ * Events are parsed in chunks directly from the raw byte buffer to avoid V8 string
+ * allocation limits. A new trace engine model is created per call to ensure session
+ * isolation and prevent memory retention.
+ *
+ * @param buffer - Raw binary trace data representing trace events and metadata.
+ * @param metadata - Optional throttling configurations applied during recording; overrides embedded file metadata when defined.
+ * @returns A promise resolving to a {@link TraceResult} with parsed traces and insights, or a {@link TraceParseError} on failure.
+ */
+export async function parseRawTraceBuffer(buffer, metadata) {
+    if (!buffer || buffer.length === 0) {
+        return {
+            error: 'No buffer was provided.',
+        };
+    }
+    try {
+        const { events, metadata: fileMetadata } = parseTraceEventsFromBuffer(buffer);
+        if (events.length === 0) {
+            return {
+                error: 'No trace events were found in the trace buffer.',
+            };
+        }
+        const combinedMetadata = {
+            ...fileMetadata,
+            ...(metadata?.cpuThrottling !== undefined
+                ? { cpuThrottling: metadata.cpuThrottling }
+                : {}),
+            ...(metadata?.networkThrottling !== undefined
+                ? { networkThrottling: metadata.networkThrottling }
+                : {}),
+        };
+        const hasMetadata = Object.keys(combinedMetadata).length > 0;
+        // Instantiate a fresh TraceModel per invocation because Model permanently
+        // retains parsed traces in its internal `#traces` array, which causes an
+        // unbounded memory leak if reused across sessions.
+        const engine = DevTools.TraceEngine.TraceModel.Model.createWithAllHandlers();
+        await engine.parse(events, {
+            metadata: hasMetadata ? combinedMetadata : undefined,
+        });
+        const parsedTrace = engine.parsedTrace();
+        if (!parsedTrace) {
+            return {
+                error: 'No parsed trace was returned from the trace engine.',
+            };
+        }
+        const insights = parsedTrace.insights ?? null;
+        return {
+            parsedTrace,
+            insights,
+        };
+    }
+    catch (e) {
+        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+        logger?.(`Unexpected error parsing trace: ${errorText}`);
+        return {
+            error: errorText,
+        };
+    }
+}
+const extraFormatDescriptions = `Information on performance traces may contain main thread activity represented as call frames and network requests.
+
+${DevTools.PerformanceTraceFormatter.callFrameDataFormatDescription}
+
+${DevTools.PerformanceTraceFormatter.networkDataFormatDescription}`;
+/**
+ * Generates a Markdown summary of main thread activity and network metrics from a parsed trace.
+ *
+ * @param result - The parsed trace result to summarize.
+ * @param deviceScope - Optional CrUX device scope to filter field data.
+ * @returns Formatted Markdown text describing performance findings.
+ */
+export function getTraceSummary(result, deviceScope) {
+    const focus = DevTools.AgentFocus.fromParsedTrace(result.parsedTrace);
+    const formatter = new DevTools.PerformanceTraceFormatter(focus, deviceScope);
+    const summaryText = formatter.formatTraceSummary();
+    return `## Summary of Performance trace findings:
+${summaryText}
+
+## Details on call tree & network request formats:
+${extraFormatDescriptions}`;
+}
+/**
+ * Formats a specific performance insight from a parsed trace for display.
+ *
+ * @param result - The parsed trace result containing computed insight sets.
+ * @param insightSetId - The identifier of the target insight set.
+ * @param insightName - The name of the insight model to extract.
+ * @param deviceScope - Optional CrUX device scope to contextualize metrics.
+ * @returns An object containing the formatted insight output text or an error message.
+ */
+export function getInsightOutput(result, insightSetId, insightName, deviceScope) {
+    if (!result.insights) {
+        return {
+            error: 'No Performance insights are available for this trace.',
+        };
+    }
+    const insightSet = result.insights.get(insightSetId);
+    if (!insightSet) {
+        return {
+            error: 'No Performance Insights for the given insight set id. Only use ids given in the "Available insight sets" list.',
+        };
+    }
+    const matchingInsight = insightName in insightSet.model ? insightSet.model[insightName] : null;
+    if (!matchingInsight) {
+        return {
+            error: `No Insight with the name ${insightName} found. Double check the name you provided is accurate and try again.`,
+        };
+    }
+    const formatter = new DevTools.PerformanceInsightFormatter(DevTools.AgentFocus.fromParsedTrace(result.parsedTrace), matchingInsight, deviceScope);
+    return { output: formatter.formatInsight() };
+}
+//# sourceMappingURL=PerformanceTrace.js.map

package/build/src/telemetry/ClearcutLogger.js

@@ -0,0 +1,242 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import process from 'node:process';
+import { DAEMON_CLIENT_NAME } from '../daemon/utils.js';
+import { logger } from '../utils/logger.js';
+import { bucketizeDaysSince, bucketizeLatency, buildContext, sanitizeClientName, sanitizeParams, stripUnderscoreBeforeNumber, } from './transformation.js';
+import { McpClient, WatchdogMessageType, OsType, } from './types.js';
+import { WatchdogClient } from './WatchdogClient.js';
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function detectOsType() {
+    switch (process.platform) {
+        case 'win32':
+            return OsType.OS_TYPE_WINDOWS;
+        case 'darwin':
+            return OsType.OS_TYPE_MACOS;
+        case 'linux':
+            return OsType.OS_TYPE_LINUX;
+        default:
+            return OsType.OS_TYPE_UNSPECIFIED;
+    }
+}
+function isSameDay(d1, d2) {
+    return (d1.getUTCFullYear() === d2.getUTCFullYear() &&
+        d1.getUTCMonth() === d2.getUTCMonth() &&
+        d1.getUTCDate() === d2.getUTCDate());
+}
+function shouldLogDailyActive(state) {
+    if (!state.lastActive) {
+        return true;
+    }
+    return !isSameDay(new Date(state.lastActive), new Date());
+}
+function calculateDaysSince(lastDateString, now = new Date()) {
+    if (!lastDateString) {
+        return -1;
+    }
+    const lastDate = new Date(lastDateString);
+    const diffTime = Math.abs(now.getTime() - lastDate.getTime());
+    return Math.ceil(diffTime / MS_PER_DAY);
+}
+// Not const to allow resetting the instance for testing purposes.
+let _clearcut_logger_instance;
+export class ClearcutLogger {
+    #persistence;
+    #watchdog;
+    #mcpClient;
+    #rawClientName;
+    #state;
+    static initialize(options) {
+        if (_clearcut_logger_instance) {
+            throw new Error('ClearcutLogger is already initialized');
+        }
+        _clearcut_logger_instance = new ClearcutLogger(options);
+        return _clearcut_logger_instance;
+    }
+    static get() {
+        return _clearcut_logger_instance;
+    }
+    static resetForTesting() {
+        _clearcut_logger_instance = undefined;
+    }
+    constructor(options) {
+        this.#persistence = options.persistence;
+        this.#watchdog =
+            options.watchdogClient ??
+                new WatchdogClient({
+                    parentPid: process.pid,
+                    appVersion: options.appVersion,
+                    osType: detectOsType(),
+                    logFile: options.logFile,
+                    clearcutEndpoint: options.clearcutEndpoint,
+                    clearcutForceFlushIntervalMs: options.clearcutForceFlushIntervalMs,
+                    clearcutIncludePidHeader: options.clearcutIncludePidHeader,
+                });
+        this.#mcpClient = McpClient.MCP_CLIENT_UNSPECIFIED;
+        void this.#persistence
+            .loadState()
+            .then(state => {
+            this.#state = state;
+        })
+            .catch(error => {
+            this.#state = undefined;
+            logger?.('Failed to load telemetry state:', error);
+        });
+    }
+    setClientName(clientName) {
+        const lowerName = clientName.toLowerCase();
+        if (lowerName.includes('claude-desktop')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_CLAUDE_DESKTOP;
+        }
+        else if (lowerName.includes('claude')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_CLAUDE_CODE;
+        }
+        else if (lowerName.includes('gemini')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_GEMINI_CLI;
+        }
+        else if (clientName === DAEMON_CLIENT_NAME) {
+            this.#mcpClient = McpClient.MCP_CLIENT_DT_MCP_CLI;
+        }
+        else if (lowerName.includes('openclaw')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_OPENCLAW;
+        }
+        else if (lowerName.includes('opencode')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_OPENCODE;
+        }
+        else if (lowerName.includes('codex')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_CODEX;
+        }
+        else if (lowerName.includes('antigravity')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_ANTIGRAVITY;
+        }
+        else if (lowerName.includes('grok') || lowerName.includes('xai')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_GROK;
+        }
+        else if (lowerName.includes('copilot')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_GITHUB_COPILOT;
+        }
+        else if (lowerName.includes('hermes-agent')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_HERMES;
+        }
+        else {
+            this.#mcpClient = McpClient.MCP_CLIENT_OTHER;
+            this.#rawClientName = sanitizeClientName(clientName);
+        }
+    }
+    #addMcpClient(payload) {
+        const ext = {
+            ...payload,
+            mcp_client: this.#mcpClient,
+        };
+        if (this.#mcpClient === McpClient.MCP_CLIENT_OTHER &&
+            this.#rawClientName !== undefined) {
+            ext.raw_mcp_client_info = {
+                raw_client_name: this.#rawClientName,
+            };
+        }
+        return ext;
+    }
+    async logToolInvocation(args) {
+        void this.#logToolActiveIfNeeded().catch(error => {
+            logger?.('Error in logToolActiveIfNeeded:', error);
+        });
+        const context = buildContext(args.devToolsData, args.pageUrl);
+        const sanitizedToolName = stripUnderscoreBeforeNumber(args.toolName);
+        const tool_invocation = {
+            tool_name: sanitizedToolName,
+            success: args.success,
+            latency_ms: bucketizeLatency(args.latencyMs),
+        };
+        if (Object.keys(context).length > 0) {
+            tool_invocation.context = context;
+        }
+        if (Object.keys(args.params).length > 0) {
+            tool_invocation.tool_params = {
+                [`${sanitizedToolName}_params`]: sanitizeParams(args.params, args.schema),
+            };
+        }
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: this.#addMcpClient({
+                tool_invocation: tool_invocation,
+            }),
+        });
+    }
+    async logServerStart(flagUsage) {
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: this.#addMcpClient({
+                server_start: {
+                    flag_usage: flagUsage,
+                },
+            }),
+        });
+    }
+    async logDailyActiveIfNeeded() {
+        try {
+            this.#state = await this.#persistence.loadState();
+            if (shouldLogDailyActive(this.#state)) {
+                const daysSince = calculateDaysSince(this.#state.lastActive);
+                this.#watchdog.send({
+                    type: WatchdogMessageType.LOG_EVENT,
+                    payload: this.#addMcpClient({
+                        daily_active: {
+                            days_since_last_active: bucketizeDaysSince(daysSince),
+                        },
+                    }),
+                });
+                this.#state.lastActive = new Date().toISOString();
+                await this.#persistence.saveState(this.#state);
+            }
+        }
+        catch (err) {
+            logger?.('Error in logDailyActiveIfNeeded:', err);
+        }
+    }
+    async logServerError(args) {
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: this.#addMcpClient({
+                server_error: {
+                    tool_name: args.toolName
+                        ? stripUnderscoreBeforeNumber(args.toolName)
+                        : '',
+                    error_code: args.errorCode,
+                },
+            }),
+        });
+    }
+    async #logToolActiveIfNeeded() {
+        // Expect state loaded at first tool call, if not, just skip logging.
+        if (!this.#state) {
+            return;
+        }
+        // Don't log tool active if it has already been logged today.
+        const now = new Date();
+        if (this.#state.lastToolCall &&
+            isSameDay(now, new Date(this.#state.lastToolCall))) {
+            return;
+        }
+        // Refresh state in case it now contains more recent value, and test again.
+        const state = await this.#persistence.loadState();
+        this.#state = state;
+        if (state.lastToolCall && isSameDay(now, new Date(state.lastToolCall))) {
+            return;
+        }
+        const daysSinceToolCall = calculateDaysSince(state.lastToolCall, now);
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: this.#addMcpClient({
+                tool_active: {
+                    days_since_last_tool_call: bucketizeDaysSince(daysSinceToolCall),
+                },
+            }),
+        });
+        this.#state.lastToolCall = now.toISOString();
+        await this.#persistence.saveState(this.#state);
+    }
+}
+//# sourceMappingURL=ClearcutLogger.js.map

package/build/src/telemetry/WatchdogClient.js

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { logger } from '../utils/logger.js';
+export class WatchdogClient {
+    #childProcess;
+    constructor(config, options) {
+        const watchdogPath = fileURLToPath(new URL('./watchdog/main.js', import.meta.url));
+        const args = [
+            watchdogPath,
+            `--parent-pid=${config.parentPid}`,
+            `--app-version=${config.appVersion}`,
+            `--os-type=${config.osType}`,
+        ];
+        if (config.logFile) {
+            args.push(`--log-file=${config.logFile}`);
+        }
+        if (config.clearcutEndpoint) {
+            args.push(`--clearcut-endpoint=${config.clearcutEndpoint}`);
+        }
+        if (config.clearcutForceFlushIntervalMs) {
+            args.push(`--clearcut-force-flush-interval-ms=${config.clearcutForceFlushIntervalMs}`);
+        }
+        if (config.clearcutIncludePidHeader) {
+            args.push('--clearcut-include-pid-header');
+        }
+        const spawner = options?.spawn ?? spawn;
+        this.#childProcess = spawner(process.execPath, args, {
+            stdio: ['pipe', 'ignore', 'ignore'],
+            detached: true,
+        });
+        this.#childProcess.unref();
+        this.#childProcess.on('error', err => {
+            logger?.('Watchdog process error:', err);
+        });
+        this.#childProcess.on('exit', (code, signal) => {
+            logger?.(`Watchdog exited with code ${code} and signal ${signal}`);
+        });
+    }
+    send(message) {
+        if (this.#childProcess.stdin &&
+            !this.#childProcess.stdin.destroyed &&
+            this.#childProcess.pid) {
+            try {
+                const line = JSON.stringify(message) + '\n';
+                this.#childProcess.stdin.write(line);
+            }
+            catch (err) {
+                logger?.('Failed to write to watchdog stdin', err);
+            }
+        }
+        else {
+            logger?.('Watchdog stdin not available, dropping message');
+        }
+    }
+}
+//# sourceMappingURL=WatchdogClient.js.map

package/build/src/telemetry/errors.js

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * IMPORTANT:
+ *   1. this module must only contain ErrorCode.
+ *   2. do not refactor ErrorCode to elsewhere.
+ *   3. prefix new enum values with "ERROR_CODE_". This makes it easier to
+ *      programmtically parse this file.
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode[ErrorCode["ERROR_CODE_UNSPECIFIED"] = 0] = "ERROR_CODE_UNSPECIFIED";
+    ErrorCode[ErrorCode["ERROR_CODE_PERSISTENCE_FILE_READ_FAILED"] = 1] = "ERROR_CODE_PERSISTENCE_FILE_READ_FAILED";
+    ErrorCode[ErrorCode["ERROR_CODE_PERSISTENCE_FILE_SAVE_FAILED"] = 2] = "ERROR_CODE_PERSISTENCE_FILE_SAVE_FAILED";
+})(ErrorCode || (ErrorCode = {}));
+//# sourceMappingURL=errors.js.map

package/build/src/telemetry/flagUtils.js

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DevTools } from '../third_party/index.js';
+import { stripUnderscoreBeforeNumber } from './transformation.js';
+const { StringUtilities } = DevTools.Platform;
+/**
+ * For enums, log the value as uppercase.
+ * We're going to have an enum for such flags with choices represented
+ * as an `enum` where the keys of the enum will map to the uppercase `choice`.
+ */
+function formatEnumChoice(snakeCaseName, choice) {
+    return stripUnderscoreBeforeNumber(`${snakeCaseName}_${choice}`).toUpperCase();
+}
+/**
+ * Computes telemetry flag usage from parsed arguments and CLI options.
+ *
+ * Iterates over the defined CLI options to construct a payload:
+ * - Flag names are converted to snake_case (e.g. `browserUrl` -> `browser_url`).
+ * - A flag is logged as `{flag_name}_present` if:
+ *    - It has no default value, OR
+ *    - The provided value differs from the default value.
+ * - Boolean flags are logged with their literal value.
+ * - String flags with defined `choices` (Enums) are logged as their uppercase value.
+ *
+ * IMPORTANT: keep getPossibleFlagMetrics() in sync with this function.
+ */
+export function computeFlagUsage(args, options) {
+    const usage = {};
+    for (const [flagName, config] of Object.entries(options)) {
+        const value = args[flagName];
+        const snakeCaseName = stripUnderscoreBeforeNumber(StringUtilities.toSnakeCase(flagName));
+        // If there isn't a default value provided for the flag,
+        // we're going to log whether it's present on the args user
+        // provided or not. If there is a default value, we only log presence
+        // if the value differs from the default, implying explicit user intent.
+        if (!('default' in config) || value !== config.default) {
+            usage[`${snakeCaseName}_present`] = value !== undefined && value !== null;
+        }
+        if (config.type === 'boolean' && typeof value === 'boolean') {
+            // For boolean options, we're going to log the value directly.
+            usage[snakeCaseName] = value;
+        }
+        else if (config.type === 'string' &&
+            typeof value === 'string' &&
+            'choices' in config &&
+            config.choices) {
+            usage[snakeCaseName] = formatEnumChoice(snakeCaseName, value);
+        }
+    }
+    return usage;
+}
+/**
+ * Computes the list of possible flag metrics based on the CLI options.
+ *
+ * IMPORTANT: keep this function in sync with computeFlagUsage().
+ */
+export function getPossibleFlagMetrics(options) {
+    const metrics = [];
+    for (const [flagName, config] of Object.entries(options)) {
+        const snakeCaseName = stripUnderscoreBeforeNumber(StringUtilities.toSnakeCase(flagName));
+        // _present is always a possible metric
+        metrics.push({
+            name: `${snakeCaseName}_present`,
+            flagType: 'boolean',
+        });
+        if (config.type === 'boolean') {
+            metrics.push({
+                name: snakeCaseName,
+                flagType: 'boolean',
+            });
+        }
+        else if (config.type === 'string' &&
+            'choices' in config &&
+            config.choices) {
+            metrics.push({
+                name: snakeCaseName,
+                flagType: 'enum',
+                choices: [
+                    `${snakeCaseName.toUpperCase()}_UNSPECIFIED`,
+                    ...config.choices.map(choice => formatEnumChoice(snakeCaseName, choice)),
+                ],
+            });
+        }
+    }
+    return metrics;
+}
+//# sourceMappingURL=flagUtils.js.map

package/build/src/telemetry/metricsRegistry.js

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { transformArgName, transformArgType, getZodType, getEnumValues, PARAM_BLOCKLIST, stripUnderscoreBeforeNumber, } from './transformation.js';
+/**
+ * Validates that all values in an enum are of the homogeneous primitive type.
+ * Returns the primitive type string. Throws an error if heterogeneous.
+ */
+export function validateEnumHomogeneity(values) {
+    const firstType = typeof values[0];
+    for (const val of values) {
+        if (typeof val !== firstType) {
+            throw new Error('Heterogeneous enum types found');
+        }
+    }
+    return firstType;
+}
+export function applyToExistingMetrics(existing, update) {
+    const updated = applyToExisting(existing, update);
+    const existingByName = new Map(existing.map(tool => [tool.name, tool]));
+    const updatedByName = new Map(update.map(tool => [tool.name, tool]));
+    return updated.map(tool => {
+        const existingTool = existingByName.get(tool.name);
+        const updatedTool = updatedByName.get(tool.name);
+        // If the tool still exists in the update, we will update the args.
+        if (existingTool && updatedTool) {
+            const updatedArgs = applyToExisting(existingTool.args, updatedTool.args);
+            return { ...tool, args: updatedArgs };
+        }
+        return tool;
+    });
+}
+export function applyToExisting(existing, update) {
+    const existingNames = new Set(existing.map(item => item.name));
+    const updatedNames = new Set(update.map(item => item.name));
+    const result = [];
+    // Keep the original ordering.
+    for (const entry of existing) {
+        const toAdd = { ...entry };
+        if (!updatedNames.has(entry.name)) {
+            toAdd.isDeprecated = true;
+        }
+        else {
+            delete toAdd.isDeprecated;
+        }
+        result.push(toAdd);
+    }
+    // New entries must be added to the very back of the list.
+    for (const entry of update) {
+        if (!existingNames.has(entry.name)) {
+            result.push({ ...entry });
+        }
+    }
+    return result;
+}
+/**
+ * Generates tool metrics from tool definitions.
+ */
+export function generateToolMetrics(tools) {
+    return tools.map(tool => {
+        const args = [];
+        for (const [name, schema] of Object.entries(tool.schema)) {
+            if (PARAM_BLOCKLIST.has(name)) {
+                continue;
+            }
+            const zodType = getZodType(schema);
+            const transformedName = transformArgName(zodType, name);
+            let argType = transformArgType(zodType);
+            if (argType === 'enum') {
+                argType = validateEnumHomogeneity(getEnumValues(schema));
+            }
+            args.push({
+                name: transformedName,
+                argType,
+            });
+        }
+        return {
+            name: stripUnderscoreBeforeNumber(tool.name),
+            args,
+        };
+    });
+}
+//# sourceMappingURL=metricsRegistry.js.map