feat(cli): add DevTools integration with gemini-cli-devtools

SandyTao520 · SandyTao520 · commit 3f472b84cfd0 · 2026-02-08T23:31:44.000-08:00
diff --git a/.gemini/settings.json b/.gemini/settings.json
@@ -3,5 +3,8 @@
     "toolOutputMasking": {
       "enabled": true
     }
+  },
+  "general": {
+    "devtools": true
   }
 }
diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md
@@ -106,6 +106,10 @@ their corresponding top-level category object in your `settings.json` file.
   - **Description:** Enable Vim keybindings
   - **Default:** `false`
 
+- **`general.devtools`** (boolean):
+  - **Description:** Enable DevTools inspector on launch.
+  - **Default:** `false`
+
 - **`general.enableAutoUpdate`** (boolean):
   - **Description:** Enable automatic updates.
   - **Default:** `true`
@@ -855,6 +859,11 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `true`
   - **Requires restart:** Yes
 
+- **`experimental.enableEventDrivenScheduler`** (boolean):
+  - **Description:** Enables event-driven scheduler within the CLI session.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
 - **`experimental.extensionReloading`** (boolean):
   - **Description:** Enables extension loading/unloading within the CLI session.
   - **Default:** `false`
diff --git a/esbuild.config.js b/esbuild.config.js
@@ -63,6 +63,7 @@ const external = [
   '@lydell/node-pty-win32-arm64',
   '@lydell/node-pty-win32-x64',
   'keytar',
+  'gemini-cli-devtools',
 ];
 
 const baseConfig = {
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -137,6 +137,7 @@
     "@lydell/node-pty-linux-x64": "1.1.0",
     "@lydell/node-pty-win32-arm64": "1.1.0",
     "@lydell/node-pty-win32-x64": "1.1.0",
+    "gemini-cli-devtools": "^0.2.1",
     "keytar": "^7.9.0",
     "node-pty": "^1.0.0"
   },
diff --git a/packages/cli/src/config/settingsSchema.ts b/packages/cli/src/config/settingsSchema.ts
@@ -179,6 +179,15 @@ const SETTINGS_SCHEMA = {
         description: 'Enable Vim keybindings',
         showInDialog: true,
       },
+      devtools: {
+        type: 'boolean',
+        label: 'DevTools',
+        category: 'General',
+        requiresRestart: false,
+        default: false,
+        description: 'Enable DevTools inspector on launch.',
+        showInDialog: false,
+      },
       enableAutoUpdate: {
         type: 'boolean',
         label: 'Enable Auto Update',
@@ -1514,6 +1523,15 @@ const SETTINGS_SCHEMA = {
         description: 'Enable requesting and fetching of extension settings.',
         showInDialog: false,
       },
+      enableEventDrivenScheduler: {
+        type: 'boolean',
+        label: 'Event Driven Scheduler',
+        category: 'Experimental',
+        requiresRestart: true,
+        default: true,
+        description: 'Enables event-driven scheduler within the CLI session.',
+        showInDialog: false,
+      },
       extensionReloading: {
         type: 'boolean',
         label: 'Extension Reloading',
diff --git a/packages/cli/src/gemini.tsx b/packages/cli/src/gemini.tsx
@@ -351,11 +351,12 @@ export async function main() {
   }
 
   const isDebugMode = cliConfig.isDebugMode(argv);
+  const earlyConsoleLogs: Array<{ type: string; content: string }> = [];
   const consolePatcher = new ConsolePatcher({
     stderr: true,
     debugMode: isDebugMode,
     onNewMessage: (msg) => {
-      coreEvents.emitConsoleLog(msg.type, msg.content);
+      earlyConsoleLogs.push({ type: msg.type, content: msg.content });
     },
   });
   consolePatcher.patch();
@@ -518,11 +519,19 @@ export async function main() {
 
     adminControlsListner.setConfig(config);
 
-    if (config.isInteractive() && config.getDebugMode()) {
+    if (config.isInteractive() && settings.merged.general.devtools) {
       const { registerActivityLogger } = await import(
-        './utils/activityLogger.js'
+        './utils/devtoolsService.js'
       );
-      registerActivityLogger(config);
+      await registerActivityLogger(config);
+      // Replay early console logs directly to ActivityLogger (bypasses
+      // coreEvents so they only appear in DevTools, not the TUI debug console).
+      const { ActivityLogger } = await import('./utils/activityLogger.js');
+      const capture = ActivityLogger.getInstance();
+      for (const log of earlyConsoleLogs) {
+        capture.logConsole(log);
+      }
+      earlyConsoleLogs.length = 0;
     }
 
     // Register config for telemetry shutdown
diff --git a/packages/cli/src/nonInteractiveCli.test.ts b/packages/cli/src/nonInteractiveCli.test.ts
@@ -39,7 +39,7 @@ import type { LoadedSettings } from './config/settings.js';
 vi.mock('./ui/hooks/atCommandProcessor.js');
 
 const mockRegisterActivityLogger = vi.hoisted(() => vi.fn());
-vi.mock('./utils/activityLogger.js', () => ({
+vi.mock('./utils/devtoolsService.js', () => ({
   registerActivityLogger: mockRegisterActivityLogger,
 }));
 
diff --git a/packages/cli/src/nonInteractiveCli.ts b/packages/cli/src/nonInteractiveCli.ts
@@ -73,9 +73,9 @@ export async function runNonInteractive({
 
     if (process.env['GEMINI_CLI_ACTIVITY_LOG_TARGET']) {
       const { registerActivityLogger } = await import(
-        './utils/activityLogger.js'
+        './utils/devtoolsService.js'
       );
-      registerActivityLogger(config);
+      await registerActivityLogger(config);
     }
 
     const { stdout: workingStdout } = createWorkingStdio();
diff --git a/packages/cli/src/ui/utils/ConsolePatcher.ts b/packages/cli/src/ui/utils/ConsolePatcher.ts
@@ -49,18 +49,16 @@ export class ConsolePatcher {
   private patchConsoleMethod =
     (type: 'log' | 'warn' | 'error' | 'debug' | 'info') =>
     (...args: unknown[]) => {
+      if (type === 'debug' && !this.params.debugMode) return;
+
       if (this.params.stderr) {
-        if (type !== 'debug' || this.params.debugMode) {
-          this.originalConsoleError(this.formatArgs(args));
-        }
-      } else {
-        if (type !== 'debug' || this.params.debugMode) {
-          this.params.onNewMessage?.({
-            type,
-            content: this.formatArgs(args),
-            count: 1,
-          });
-        }
+        this.originalConsoleError(this.formatArgs(args));
       }
+
+      this.params.onNewMessage?.({
+        type,
+        content: this.formatArgs(args),
+        count: 1,
+      });
     };
 }
diff --git a/packages/cli/src/utils/activityLogger.ts b/packages/cli/src/utils/activityLogger.ts
@@ -21,29 +21,6 @@ import WebSocket from 'ws';
 const ACTIVITY_ID_HEADER = 'x-activity-request-id';
 const MAX_BUFFER_SIZE = 100;
 
-/**
- * Parse a host:port string into its components.
- * Uses the URL constructor for robust handling of IPv4, IPv6, and hostnames.
- * Returns null for file paths or values without a valid port.
- */
-function parseHostPort(value: string): { host: string; port: number } | null {
-  if (value.startsWith('/') || value.startsWith('.')) return null;
-
-  try {
-    const url = new URL(`ws://${value}`);
-    if (!url.port) return null;
-
-    const port = parseInt(url.port, 10);
-    if (url.hostname && !isNaN(port) && port > 0 && port <= 65535) {
-      return { host: url.hostname, port };
-    }
-  } catch {
-    // Not a valid host:port
-  }
-
-  return null;
-}
-
 export interface NetworkLog {
   id: string;
   timestamp: number;
@@ -494,19 +471,23 @@ function setupNetworkLogging(
   host: string,
   port: number,
   config: Config,
+  onReconnectFailed?: () => void,
 ) {
   const buffer: Array<Record<string, unknown>> = [];
   let ws: WebSocket | null = null;
   let reconnectTimer: NodeJS.Timeout | null = null;
   let sessionId: string | null = null;
   let pingInterval: NodeJS.Timeout | null = null;
+  let reconnectAttempts = 0;
+  const MAX_RECONNECT_ATTEMPTS = 2;
 
   const connect = () => {
     try {
       ws = new WebSocket(`ws://${host}:${port}/ws`);
 
       ws.on('open', () => {
         debugLogger.debug(`WebSocket connected to ${host}:${port}`);
+        reconnectAttempts = 0;
         // Register with CLI's session ID
         sendMessage({
           type: 'register',
@@ -620,11 +601,20 @@ function setupNetworkLogging(
   const scheduleReconnect = () => {
     if (reconnectTimer) return;
 
+    reconnectAttempts++;
+    if (reconnectAttempts > MAX_RECONNECT_ATTEMPTS && onReconnectFailed) {
+      debugLogger.debug(
+        `WebSocket reconnect failed after ${MAX_RECONNECT_ATTEMPTS} attempts, promoting to server...`,
+      );
+      onReconnectFailed();
+      return;
+    }
+
     reconnectTimer = setTimeout(() => {
       reconnectTimer = null;
       debugLogger.debug('Reconnecting WebSocket...');
       connect();
-    }, 5000);
+    }, 1000);
   };
 
   // Initial connection
@@ -645,41 +635,65 @@ function setupNetworkLogging(
   });
 }
 
+let bridgeAttached = false;
+
 /**
- * Registers the activity logger if debug mode and interactive session are enabled.
- * Captures network and console logs to a session-specific JSONL file or sends to network.
- *
- * Environment variable GEMINI_CLI_ACTIVITY_LOG_TARGET controls the output:
- * - host:port format (e.g., "localhost:25417") → network mode (auto-enabled)
- * - file path (e.g., "/tmp/logs.jsonl") → file mode (immediate)
- * - not set → uses default file location in project temp logs dir
- *
- * @param config The CLI configuration
+ * Bridge coreEvents to the ActivityLogger singleton (guarded — only once).
  */
-export function registerActivityLogger(config: Config) {
-  const target = process.env['GEMINI_CLI_ACTIVITY_LOG_TARGET'];
-  const hostPort = target ? parseHostPort(target) : null;
-
-  // Network mode doesn't need storage; file mode does
-  if (!hostPort && !config.storage) {
-    return;
-  }
+function bridgeCoreEvents(capture: ActivityLogger) {
+  if (bridgeAttached) return;
+  bridgeAttached = true;
+  coreEvents.on(CoreEvent.ConsoleLog, (payload) => {
+    capture.logConsole(payload);
+  });
+}
 
+/**
+ * Initialize the activity logger with a specific transport mode.
+ *
+ * @param config  CLI configuration
+ * @param options Transport configuration: network (WebSocket) or file (JSONL)
+ */
+export function initActivityLogger(
+  config: Config,
+  options:
+    | {
+        mode: 'network';
+        host: string;
+        port: number;
+        onReconnectFailed?: () => void;
+      }
+    | { mode: 'file'; filePath?: string },
+): void {
   const capture = ActivityLogger.getInstance();
   capture.enable();
 
-  if (hostPort) {
-    // Network mode: send logs via WebSocket
-    setupNetworkLogging(capture, hostPort.host, hostPort.port, config);
-    // Auto-enable network logging when target is explicitly configured
+  if (options.mode === 'network') {
+    setupNetworkLogging(
+      capture,
+      options.host,
+      options.port,
+      config,
+      options.onReconnectFailed,
+    );
     capture.enableNetworkLogging();
   } else {
-    // File mode: write to JSONL file
-    setupFileLogging(capture, config, target);
+    setupFileLogging(capture, config, options.filePath);
   }
 
-  // Bridge CoreEvents to local capture
-  coreEvents.on(CoreEvent.ConsoleLog, (payload) => {
-    capture.logConsole(payload);
-  });
+  bridgeCoreEvents(capture);
+}
+
+/**
+ * Add a network (WebSocket) transport to the existing ActivityLogger singleton.
+ * Used for promotion re-entry without re-bridging coreEvents.
+ */
+export function addNetworkTransport(
+  config: Config,
+  host: string,
+  port: number,
+  onReconnectFailed?: () => void,
+): void {
+  const capture = ActivityLogger.getInstance();
+  setupNetworkLogging(capture, host, port, config, onReconnectFailed);
 }
diff --git a/packages/cli/src/utils/devtoolsService.ts b/packages/cli/src/utils/devtoolsService.ts
diff --git a/schemas/settings.schema.json b/schemas/settings.schema.json

Original file line number	Diff line number	Diff line change
`@@ -3,5 +3,8 @@`
`3`	`3`	`"toolOutputMasking": {`
`4`	`4`	`"enabled": true`
`5`	`5`	`}`
	`6`	`+ },`
	`7`	`+ "general": {`
	`8`	`+ "devtools": true`
`6`	`9`	`}`
`7`	`10`	`}`