chore(cli): increase user simulator tick interval to 3s and update design doc

package-lock.json

@@ -80,7 +80,7 @@
         "@lydell/node-pty-win32-arm64": "1.1.0",
         "@lydell/node-pty-win32-x64": "1.1.0",
         "keytar": "^7.9.0",
-        "node-pty": "^1.0.0"
+        "node-pty": "^1.1.0"
       }
     },
     "node_modules/@agentclientprotocol/sdk": {
@@ -4906,53 +4906,6 @@
         "url": "https://opencollective.com/vitest"
       }
     },
-    "node_modules/@vscode/vsce": {
-      "version": "3.6.0",
-      "resolved": "https://registry.npmjs.org/@vscode/vsce/-/vsce-3.6.0.tgz",
-      "integrity": "sha512-u2ZoMfymRNJb14aHNawnXJtXHLXDVKc1oKZaH4VELKT/9iWKRVgtQOdwxCgtwSxJoqYvuK4hGlBWQJ05wxADhg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@azure/identity": "^4.1.0",
-        "@secretlint/node": "^10.1.1",
-        "@secretlint/secretlint-formatter-sarif": "^10.1.1",
-        "@secretlint/secretlint-rule-no-dotenv": "^10.1.1",
-        "@secretlint/secretlint-rule-preset-recommend": "^10.1.1",
-        "@vscode/vsce-sign": "^2.0.0",
-        "azure-devops-node-api": "^12.5.0",
-        "chalk": "^4.1.2",
-        "cheerio": "^1.0.0-rc.9",
-        "cockatiel": "^3.1.2",
-        "commander": "^12.1.0",
-        "form-data": "^4.0.0",
-        "glob": "^11.0.0",
-        "hosted-git-info": "^4.0.2",
-        "jsonc-parser": "^3.2.0",
-        "leven": "^3.1.0",
-        "markdown-it": "^14.1.0",
-        "mime": "^1.3.4",
-        "minimatch": "^3.0.3",
-        "parse-semver": "^1.1.1",
-        "read": "^1.0.7",
-        "secretlint": "^10.1.1",
-        "semver": "^7.5.2",
-        "tmp": "^0.2.3",
-        "typed-rest-client": "^1.8.4",
-        "url-join": "^4.0.1",
-        "xml2js": "^0.5.0",
-        "yauzl": "^2.3.1",
-        "yazl": "^2.2.2"
-      },
-      "bin": {
-        "vsce": "vsce"
-      },
-      "engines": {
-        "node": ">= 20"
-      },
-      "optionalDependencies": {
-        "keytar": "^7.7.0"
-      }
-    },
     "node_modules/@vscode/vsce-sign": {
       "version": "2.0.6",
       "resolved": "https://registry.npmjs.org/@vscode/vsce-sign/-/vsce-sign-2.0.6.tgz",
@@ -5098,52 +5051,6 @@
         "win32"
       ]
     },
-    "node_modules/@vscode/vsce/node_modules/hosted-git-info": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-4.1.0.tgz",
-      "integrity": "sha512-kyCuEOWjJqZuDbRHzL8V93NzQhwIB71oFWSyzVo+KPZI+pnQPPxucdkrOZvkLRnrf5URsQM+IJ09Dw29cRALIA==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "lru-cache": "^6.0.0"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@vscode/vsce/node_modules/lru-cache": {
-      "version": "6.0.0",
-      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz",
-      "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "yallist": "^4.0.0"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@vscode/vsce/node_modules/mime": {
-      "version": "1.6.0",
-      "resolved": "https://registry.npmjs.org/mime/-/mime-1.6.0.tgz",
-      "integrity": "sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==",
-      "dev": true,
-      "license": "MIT",
-      "bin": {
-        "mime": "cli.js"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "node_modules/@vscode/vsce/node_modules/yallist": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
-      "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
-      "dev": true,
-      "license": "ISC"
-    },
     "node_modules/@vue/compiler-core": {
       "version": "3.5.26",
       "resolved": "https://registry.npmjs.org/@vue/compiler-core/-/compiler-core-3.5.26.tgz",
@@ -6655,6 +6562,13 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/config-chain": {
       "version": "1.1.13",
       "resolved": "https://registry.npmjs.org/config-chain/-/config-chain-1.1.13.tgz",
@@ -12193,13 +12107,6 @@
         "node": "^18.17.0 || >=20.5.0"
       }
     },
-    "node_modules/nan": {
-      "version": "2.23.0",
-      "resolved": "https://registry.npmjs.org/nan/-/nan-2.23.0.tgz",
-      "integrity": "sha512-1UxuyYGdoQHcGg87Lkqm3FzefucTa0NAiOcuRsDmysep3c1LVCRK2krrUDafMWtjSG04htvAmvg96+SDknOmgQ==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/nano-spawn": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/nano-spawn/-/nano-spawn-1.0.3.tgz",
@@ -12343,16 +12250,23 @@
       }
     },
     "node_modules/node-pty": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.0.0.tgz",
-      "integrity": "sha512-wtBMWWS7dFZm/VgqElrTvtfMq4GzJ6+edFI0Y0zyzygUSZMgZdraDUMUhCIvkjhJjme15qWmbyJbtAx4ot4uZA==",
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.1.0.tgz",
+      "integrity": "sha512-20JqtutY6JPXTUnL0ij1uad7Qe1baT46lyolh2sSENDd4sTzKZ4nmAFkeAARDKwmlLjPx6XKRlwRUxwjOy+lUg==",
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "nan": "^2.17.0"
+        "node-addon-api": "^7.1.0"
       }
     },
+    "node_modules/node-pty/node_modules/node-addon-api": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+      "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/node-sarif-builder": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/node-sarif-builder/-/node-sarif-builder-3.2.0.tgz",
@@ -17996,6 +17910,23 @@
         "node": ">=20"
       }
     },
+    "packages/snake-game": {
+      "name": "@google/gemini-cli-snake-game",
+      "version": "0.1.0",
+      "extraneous": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "lucide-react": "^0.471.0"
+      },
+      "devDependencies": {
+        "@types/react": "^19.2.0",
+        "@types/react-dom": "^19.2.0",
+        "esbuild": "^0.25.0",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.0",
+        "typescript": "^5.7.3"
+      }
+    },
     "packages/test-utils": {
       "name": "@google/gemini-cli-test-utils",
       "version": "0.36.0-nightly.20260317.2f90b4653",
@@ -18030,7 +17961,7 @@
         "@types/vscode": "^1.99.0",
         "@typescript-eslint/eslint-plugin": "^8.31.1",
         "@typescript-eslint/parser": "^8.31.1",
-        "@vscode/vsce": "^3.6.0",
+        "@vscode/vsce": "^3.7.1",
         "esbuild": "^0.25.3",
         "eslint": "^9.25.1",
         "npm-run-all2": "^8.0.2",
@@ -18047,6 +17978,155 @@
       "integrity": "sha512-30sjmas1hQ0gVbX68LAWlm/YYlEqUErunPJJKLpEl+xhK0mKn+jyzlCOpsdTwfkZfPy4U6CDkmygBLC3AB8W9Q==",
       "dev": true,
       "license": "MIT"
+    },
+    "packages/vscode-ide-companion/node_modules/@vscode/vsce": {
+      "version": "3.7.1",
+      "resolved": "https://registry.npmjs.org/@vscode/vsce/-/vsce-3.7.1.tgz",
+      "integrity": "sha512-OTm2XdMt2YkpSn2Nx7z2EJtSuhRHsTPYsSK59hr3v8jRArK+2UEoju4Jumn1CmpgoBLGI6ReHLJ/czYltNUW3g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@azure/identity": "^4.1.0",
+        "@secretlint/node": "^10.1.2",
+        "@secretlint/secretlint-formatter-sarif": "^10.1.2",
+        "@secretlint/secretlint-rule-no-dotenv": "^10.1.2",
+        "@secretlint/secretlint-rule-preset-recommend": "^10.1.2",
+        "@vscode/vsce-sign": "^2.0.0",
+        "azure-devops-node-api": "^12.5.0",
+        "chalk": "^4.1.2",
+        "cheerio": "^1.0.0-rc.9",
+        "cockatiel": "^3.1.2",
+        "commander": "^12.1.0",
+        "form-data": "^4.0.0",
+        "glob": "^11.0.0",
+        "hosted-git-info": "^4.0.2",
+        "jsonc-parser": "^3.2.0",
+        "leven": "^3.1.0",
+        "markdown-it": "^14.1.0",
+        "mime": "^1.3.4",
+        "minimatch": "^3.0.3",
+        "parse-semver": "^1.1.1",
+        "read": "^1.0.7",
+        "secretlint": "^10.1.2",
+        "semver": "^7.5.2",
+        "tmp": "^0.2.3",
+        "typed-rest-client": "^1.8.4",
+        "url-join": "^4.0.1",
+        "xml2js": "^0.5.0",
+        "yauzl": "^2.3.1",
+        "yazl": "^2.2.2"
+      },
+      "bin": {
+        "vsce": "vsce"
+      },
+      "engines": {
+        "node": ">= 20"
+      },
+      "optionalDependencies": {
+        "keytar": "^7.7.0"
+      }
+    },
+    "packages/vscode-ide-companion/node_modules/@vscode/vsce/node_modules/minimatch": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "packages/vscode-ide-companion/node_modules/balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "packages/vscode-ide-companion/node_modules/brace-expansion": {
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "packages/vscode-ide-companion/node_modules/glob": {
+      "version": "11.1.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-11.1.0.tgz",
+      "integrity": "sha512-vuNwKSaKiqm7g0THUBu2x7ckSs3XJLXE+2ssL7/MfTGPLLcrJQ/4Uq1CjPTtO5cCIiRxqvN6Twy1qOwhL0Xjcw==",
+      "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "foreground-child": "^3.3.1",
+        "jackspeak": "^4.1.1",
+        "minimatch": "^10.1.1",
+        "minipass": "^7.1.2",
+        "package-json-from-dist": "^1.0.0",
+        "path-scurry": "^2.0.0"
+      },
+      "bin": {
+        "glob": "dist/esm/bin.mjs"
+      },
+      "engines": {
+        "node": "20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "packages/vscode-ide-companion/node_modules/hosted-git-info": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-4.1.0.tgz",
+      "integrity": "sha512-kyCuEOWjJqZuDbRHzL8V93NzQhwIB71oFWSyzVo+KPZI+pnQPPxucdkrOZvkLRnrf5URsQM+IJ09Dw29cRALIA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "lru-cache": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "packages/vscode-ide-companion/node_modules/lru-cache": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz",
+      "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "packages/vscode-ide-companion/node_modules/mime": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-1.6.0.tgz",
+      "integrity": "sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "mime": "cli.js"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "packages/vscode-ide-companion/node_modules/yallist": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
+      "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
+      "dev": true,
+      "license": "ISC"
     }
   }
 }

package.json

@@ -150,7 +150,7 @@
     "@lydell/node-pty-win32-arm64": "1.1.0",
     "@lydell/node-pty-win32-x64": "1.1.0",
     "keytar": "^7.9.0",
-    "node-pty": "^1.0.0"
+    "node-pty": "^1.1.0"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": [

packages/cli/src/config/config.ts

@@ -97,6 +97,7 @@ export interface CliArgs {
   rawOutput: boolean | undefined;
   acceptRawOutputRisk: boolean | undefined;
   isCommand: boolean | undefined;
+  simulateUser: boolean | undefined;
 }
 
 /**
@@ -298,6 +299,11 @@ export async function parseArguments(
         .option('accept-raw-output-risk', {
           type: 'boolean',
           description: 'Suppress the security warning when using --raw-output.',
+        })
+        .option('simulate-user', {
+          type: 'boolean',
+          description:
+            'Run the user simulation agent in the background for evaluation purposes.',
         }),
     )
     // Register MCP subcommands
@@ -799,6 +805,7 @@ export async function loadCliConfig(
     approvalMode,
     disableYoloMode:
       settings.security?.disableYoloMode || settings.admin?.secureModeEnabled,
+    simulateUser: !!argv.simulateUser,
     disableAlwaysAllow:
       settings.security?.disableAlwaysAllow ||
       settings.admin?.secureModeEnabled,

packages/cli/src/gemini.test.tsx

@@ -513,6 +513,7 @@ describe('gemini.tsx main function kitty protocol', () => {
       rawOutput: undefined,
       acceptRawOutputRisk: undefined,
       isCommand: undefined,
+      simulateUser: undefined,
     });
 
     await act(async () => {

packages/cli/src/interactiveCli.tsx

@@ -9,7 +9,15 @@ import { render } from 'ink';
 import { basename } from 'node:path';
 import { AppContainer } from './ui/AppContainer.js';
 import { ConsolePatcher } from './ui/utils/ConsolePatcher.js';
+import { UserSimulator } from './services/UserSimulator.js';
 import { registerCleanup, setupTtyCheck } from './utils/cleanup.js';
+import { PassThrough } from 'node:stream';
+
+interface RenderMetrics {
+  renderTime: number;
+  output: string;
+  staticOutput?: string;
+}
 import {
   type StartupWarning,
   type Config,
@@ -132,6 +140,11 @@ export async function startInteractiveUI(
     await new Promise((resolve) => setTimeout(resolve, 100));
   }
 
+  const simulateUser = config.getSimulateUser();
+  const simulatedStdin = new PassThrough({ encoding: 'utf8' });
+
+  let lastFrame: string | undefined;
+  const staticHistory: string[] = [];
   const instance = render(
     process.env['DEBUG'] ? (
       <React.StrictMode>
@@ -143,12 +156,20 @@ export async function startInteractiveUI(
     {
       stdout: inkStdout,
       stderr: inkStderr,
-      stdin: process.stdin,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-unsafe-assignment
+      stdin: (simulateUser ? simulatedStdin : process.stdin) as any,
       exitOnCtrlC: false,
       isScreenReaderEnabled: config.getScreenReader(),
-      onRender: ({ renderTime }: { renderTime: number }) => {
-        if (renderTime > SLOW_RENDER_MS) {
-          recordSlowRender(config, renderTime);
+      onRender: (metrics: RenderMetrics) => {
+        lastFrame = metrics.output;
+        if (metrics.staticOutput) {
+          staticHistory.push(metrics.staticOutput);
+          if (staticHistory.length > 50) {
+            staticHistory.shift();
+          }
+        }
+        if (metrics.renderTime > SLOW_RENDER_MS) {
+          recordSlowRender(config, metrics.renderTime);
         }
         profiler.reportFrameRendered();
       },
@@ -179,6 +200,21 @@ export async function startInteractiveUI(
       }
     });
 
+  if (simulateUser) {
+    const simulator = new UserSimulator(
+      config,
+      () => {
+        if (lastFrame === undefined) return undefined;
+        // Combine history with latest frame for the simulator
+        const historyText = staticHistory.join('\n');
+        return historyText ? `${historyText}\n${lastFrame}` : lastFrame;
+      },
+      simulatedStdin,
+    );
+    simulator.start();
+    registerCleanup(() => simulator.stop());
+  }
+
   registerCleanup(() => instance.unmount());
 
   registerCleanup(setupTtyCheck());

packages/cli/src/services/UserSimulator.ts

@@ -0,0 +1,213 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Config } from '@google/gemini-cli-core';
+import {
+  debugLogger,
+  LlmRole,
+  PREVIEW_GEMINI_FLASH_MODEL,
+  resolveModel,
+} from '@google/gemini-cli-core';
+import type { Writable } from 'node:stream';
+import * as fs from 'node:fs';
+
+export class UserSimulator {
+  private isRunning = false;
+  private timer: NodeJS.Timeout | null = null;
+  private lastScreenContent = '';
+  private isProcessing = false;
+  private interactionsFile: string | null = null;
+  private actionHistory: string[] = [];
+
+  constructor(
+    private readonly config: Config,
+    private readonly getScreen: () => string | undefined,
+    private readonly stdinBuffer: Writable,
+  ) {}
+
+  start() {
+    if (!this.config.getSimulateUser()) {
+      return;
+    }
+    this.interactionsFile = `interactions_${Date.now()}.txt`;
+    this.isRunning = true;
+    this.timer = setInterval(() => this.tick(), 3000);
+  }
+
+  stop() {
+    this.isRunning = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    debugLogger.log('User simulator stopped');
+  }
+
+  private async tick() {
+    if (!this.isRunning || this.isProcessing) return;
+
+    try {
+      this.isProcessing = true;
+      const screen = this.getScreen();
+      if (!screen) return;
+
+      const strippedScreen = screen
+        .replace(
+          // eslint-disable-next-line no-control-regex
+          /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g,
+          '',
+        )
+        .replace(/\n([ \t]*\n)+/g, '\n\n');
+
+      const normalizedScreen = strippedScreen
+        .replace(/[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]/g, '')
+        .replace(/\[?\s*\b\d+(\.\d+)?s\b\s*\]?/g, '')
+        .trim();
+
+      if (normalizedScreen === this.lastScreenContent) return;
+
+      debugLogger.log(
+        `[SIMULATOR] Screen Content Seen:\n---\n${strippedScreen}\n---`,
+      );
+      if (this.interactionsFile) {
+        fs.appendFileSync(
+          this.interactionsFile,
+          `[LOG] [SIMULATOR] Screen Content Seen:\n---\n${strippedScreen}\n---\n\n`,
+        );
+      }
+
+      const contentGenerator = this.config.getContentGenerator();
+      if (!contentGenerator) return;
+
+      const originalGoal = this.config.getQuestion();
+      const goalInstruction = originalGoal
+        ? `\nThe original goal was: "${originalGoal}"\n`
+        : '';
+
+      const historyInstruction =
+        this.actionHistory.length > 0
+          ? `\nYou have previously taken the following actions (in order):\n${this.actionHistory.map((a, i) => `${i + 1}. ${JSON.stringify(a)}`).join('\n')}\nPay close attention to whether you have already asked for the original goal. If you have already submitted the original goal, DO NOT repeat it verbatim. If the UI shows your typed text but hasn't submitted it yet, just output \\r to press Enter.\n`
+          : '';
+
+      const prompt = `You are evaluating a CLI agent by simulating a user sitting at the terminal.
+Look carefully at the screen and determine the CLI's current state:
+
+STATE 1: The agent is busy (e.g., streaming a response, showing a spinner, running a tool, or displaying a timer like "7s"). It is actively working and NOT waiting for text input.
+- In this case, you MUST output exactly: <WAIT>
+
+STATE 2: The agent is waiting for you to authorize a tool, confirm an action, or answer a specific multi-choice question (e.g., "Action Required", "Allow execution", numbered options).
+- In this case, you MUST output the exact raw characters to select the option and submit it (e.g., 1\\r, 2\\r, y\\r, n\\r, or just \\r if the default option is acceptable). Do NOT output <DONE> or "Thank you". You must unblock the agent and allow it to run the tool.
+
+STATE 3: The agent has finished its current thought process AND is idle, waiting for a NEW general text prompt (usually indicated by a "> Type your message" prompt).
+- First, verify that the ACTUAL task is fully complete based on your original goal. Do not stop at intermediate steps like planning or syntax checking.
+- If the task is indeed fully complete, output "Thank you\\r" to graciously finish the simulation.
+- If you have already said thank you, output exactly: <DONE>
+- If the agent is waiting at a general text prompt but the original task is NOT complete, provide text instructions to continue what is missing. DO NOT repeat the original goal if it has already been provided once. Ask it to continue or provide feedback based on the current state or send <DONE> if you think the task is completed.
+
+STATE 4: Any other situation where the agent is waiting for text input or needs to press Enter.
+- Output the raw characters you would type, followed by \\r. For just an Enter key press, output \\r.
+
+CRITICAL RULES:
+- RULE 1: If there is ANY active spinner (e.g., ⠋, ⠙, ⠹, ⠸, ⠼, ⠴, ⠧) or an elapsed time indicator (e.g., "0s", "7s") anywhere on the screen, the agent is STILL WORKING. You MUST output <WAIT>. Do NOT issue commands, even if a text prompt is visible below it.
+- RULE 2: If there is an "Action Required" or confirmation prompt on the screen, YOU MUST HANDLE IT (State 2). This takes precedence over everything else.
+- RULE 3: Output ONLY the raw characters to send, <WAIT>, or <DONE>.
+- RULE 4: Do NOT output markdown, explanations of your thought process, or quotes.
+${goalInstruction}${historyInstruction}
+
+Here is the current terminal screen output:
+
+<screen>
+${strippedScreen}
+</screen>`;
+
+      if (this.interactionsFile) {
+        fs.appendFileSync(
+          this.interactionsFile,
+          `[LOG] [SIMULATOR] Prompt Used:\n---\n${prompt}\n---\n\n`,
+        );
+      }
+
+      const model = resolveModel(
+        PREVIEW_GEMINI_FLASH_MODEL,
+        false, // useGemini3_1
+        false, // useCustomToolModel
+        this.config.getHasAccessToPreviewModel?.() ?? true,
+        this.config,
+      );
+
+      const response = await contentGenerator.generateContent(
+        {
+          model,
+          contents: [
+            {
+              role: 'user',
+              parts: [{ text: prompt }],
+            },
+          ],
+        },
+        'simulator-prompt',
+        LlmRole.UTILITY_SIMULATOR,
+      );
+
+      const responseText = (response.text || '').replace(
+        /^[`"']+|[`"']+$/g,
+        '',
+      );
+      const trimmedResponse = responseText.trim();
+
+      debugLogger.log(
+        `[SIMULATOR] Raw model response: ${JSON.stringify(response.text)}`,
+      );
+      if (this.interactionsFile) {
+        fs.appendFileSync(
+          this.interactionsFile,
+          `[LOG] [SIMULATOR] Raw model response: ${JSON.stringify(response.text)}\n\n`,
+        );
+      }
+      debugLogger.log(
+        `[SIMULATOR] Processed response: ${JSON.stringify(responseText)}`,
+      );
+
+      if (trimmedResponse === '<DONE>') {
+        const msg = '[SIMULATOR] Terminating simulation: Task is completed.';
+        debugLogger.log(msg);
+        if (this.interactionsFile) {
+          fs.appendFileSync(this.interactionsFile, `[LOG] ${msg}\n\n`);
+        }
+        // eslint-disable-next-line no-console
+        console.log(`\n${msg}`);
+        this.stop();
+        process.exit(0);
+      }
+
+      if (trimmedResponse === '<WAIT>') {
+        debugLogger.log(
+          '[SIMULATOR] Skipping action (model decided to <WAIT>)',
+        );
+        this.lastScreenContent = normalizedScreen;
+        return;
+      }
+
+      if (responseText) {
+        const keys = responseText.replace(/\\n/g, '\r').replace(/\\r/g, '\r');
+        const readableAction = trimmedResponse.replace(/\\r/g, '[ENTER]');
+        this.actionHistory.push(readableAction);
+
+        debugLogger.log(
+          `[SIMULATOR] Sending to stdin: ${JSON.stringify(keys)}`,
+        );
+        this.stdinBuffer.write(keys);
+        this.lastScreenContent = normalizedScreen;
+      } else {
+        debugLogger.log('[SIMULATOR] Skipping (empty response)');
+        this.lastScreenContent = normalizedScreen;
+      }
+    } catch (e: unknown) {
+      debugLogger.error('UserSimulator tick failed', e);
+    } finally {
+      this.isProcessing = false;
+    }
+  }
+}

packages/cli/src/test-utils/mockConfig.ts

@@ -62,6 +62,7 @@ export const createMockConfig = (overrides: Partial<Config> = {}): Config =>
     getGeminiMdFileCount: vi.fn(() => 0),
     getDeferredCommand: vi.fn(() => undefined),
     getFileSystemService: vi.fn(() => ({})),
+    getSimulateUser: vi.fn(() => false),
     clientVersion: '1.0.0',
     getModel: vi.fn().mockReturnValue('gemini-pro'),
     getWorkingDir: vi.fn().mockReturnValue('/mock/cwd'),

packages/core/src/agent/content-utils.test.ts

@@ -0,0 +1,258 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  geminiPartsToContentParts,
+  contentPartsToGeminiParts,
+  toolResultDisplayToContentParts,
+  buildToolResponseData,
+} from './content-utils.js';
+import type { Part } from '@google/genai';
+import type { ContentPart } from './types.js';
+
+describe('geminiPartsToContentParts', () => {
+  it('converts text parts', () => {
+    const parts: Part[] = [{ text: 'hello' }];
+    expect(geminiPartsToContentParts(parts)).toEqual([
+      { type: 'text', text: 'hello' },
+    ]);
+  });
+
+  it('converts thought parts', () => {
+    const parts: Part[] = [
+      { text: 'thinking...', thought: true, thoughtSignature: 'sig123' },
+    ];
+    expect(geminiPartsToContentParts(parts)).toEqual([
+      {
+        type: 'thought',
+        thought: 'thinking...',
+        thoughtSignature: 'sig123',
+      },
+    ]);
+  });
+
+  it('converts thought parts without signature', () => {
+    const parts: Part[] = [{ text: 'thinking...', thought: true }];
+    expect(geminiPartsToContentParts(parts)).toEqual([
+      { type: 'thought', thought: 'thinking...' },
+    ]);
+  });
+
+  it('converts inlineData parts to media', () => {
+    const parts: Part[] = [
+      { inlineData: { data: 'base64data', mimeType: 'image/png' } },
+    ];
+    expect(geminiPartsToContentParts(parts)).toEqual([
+      { type: 'media', data: 'base64data', mimeType: 'image/png' },
+    ]);
+  });
+
+  it('converts fileData parts to media', () => {
+    const parts: Part[] = [
+      {
+        fileData: {
+          fileUri: 'gs://bucket/file.pdf',
+          mimeType: 'application/pdf',
+        },
+      },
+    ];
+    expect(geminiPartsToContentParts(parts)).toEqual([
+      {
+        type: 'media',
+        uri: 'gs://bucket/file.pdf',
+        mimeType: 'application/pdf',
+      },
+    ]);
+  });
+
+  it('skips functionCall parts', () => {
+    const parts: Part[] = [
+      { functionCall: { name: 'myFunc', args: { key: 'value' } } },
+    ];
+    const result = geminiPartsToContentParts(parts);
+    expect(result).toEqual([]);
+  });
+
+  it('skips functionResponse parts', () => {
+    const parts: Part[] = [
+      {
+        functionResponse: {
+          name: 'myFunc',
+          response: { output: 'result' },
+        },
+      },
+    ];
+    const result = geminiPartsToContentParts(parts);
+    expect(result).toEqual([]);
+  });
+
+  it('serializes unknown part types to text with _meta', () => {
+    const parts: Part[] = [{ unknownField: 'data' } as Part];
+    const result = geminiPartsToContentParts(parts);
+    expect(result).toHaveLength(1);
+    expect(result[0]?.type).toBe('text');
+    expect(result[0]?._meta).toEqual({ partType: 'unknown' });
+  });
+
+  it('handles empty array', () => {
+    expect(geminiPartsToContentParts([])).toEqual([]);
+  });
+
+  it('handles mixed parts', () => {
+    const parts: Part[] = [
+      { text: 'hello' },
+      { inlineData: { data: 'img', mimeType: 'image/jpeg' } },
+      { text: 'thought', thought: true },
+    ];
+    const result = geminiPartsToContentParts(parts);
+    expect(result).toHaveLength(3);
+    expect(result[0]?.type).toBe('text');
+    expect(result[1]?.type).toBe('media');
+    expect(result[2]?.type).toBe('thought');
+  });
+});
+
+describe('contentPartsToGeminiParts', () => {
+  it('converts text ContentParts', () => {
+    const content: ContentPart[] = [{ type: 'text', text: 'hello' }];
+    expect(contentPartsToGeminiParts(content)).toEqual([{ text: 'hello' }]);
+  });
+
+  it('converts thought ContentParts', () => {
+    const content: ContentPart[] = [
+      { type: 'thought', thought: 'thinking...', thoughtSignature: 'sig' },
+    ];
+    expect(contentPartsToGeminiParts(content)).toEqual([
+      { text: 'thinking...', thought: true, thoughtSignature: 'sig' },
+    ]);
+  });
+
+  it('converts thought ContentParts without signature', () => {
+    const content: ContentPart[] = [
+      { type: 'thought', thought: 'thinking...' },
+    ];
+    expect(contentPartsToGeminiParts(content)).toEqual([
+      { text: 'thinking...', thought: true },
+    ]);
+  });
+
+  it('converts media ContentParts with data to inlineData', () => {
+    const content: ContentPart[] = [
+      { type: 'media', data: 'base64', mimeType: 'image/png' },
+    ];
+    expect(contentPartsToGeminiParts(content)).toEqual([
+      { inlineData: { data: 'base64', mimeType: 'image/png' } },
+    ]);
+  });
+
+  it('converts media ContentParts with uri to fileData', () => {
+    const content: ContentPart[] = [
+      { type: 'media', uri: 'gs://bucket/file', mimeType: 'application/pdf' },
+    ];
+    expect(contentPartsToGeminiParts(content)).toEqual([
+      {
+        fileData: { fileUri: 'gs://bucket/file', mimeType: 'application/pdf' },
+      },
+    ]);
+  });
+
+  it('converts reference ContentParts to text', () => {
+    const content: ContentPart[] = [{ type: 'reference', text: '@file.ts' }];
+    expect(contentPartsToGeminiParts(content)).toEqual([{ text: '@file.ts' }]);
+  });
+
+  it('handles empty array', () => {
+    expect(contentPartsToGeminiParts([])).toEqual([]);
+  });
+
+  it('skips media parts with no data or uri', () => {
+    const content: ContentPart[] = [{ type: 'media', mimeType: 'image/png' }];
+    expect(contentPartsToGeminiParts(content)).toEqual([]);
+  });
+
+  it('defaults mimeType for media with data but no mimeType', () => {
+    const content: ContentPart[] = [{ type: 'media', data: 'base64data' }];
+    const result = contentPartsToGeminiParts(content);
+    expect(result).toEqual([
+      {
+        inlineData: {
+          data: 'base64data',
+          mimeType: 'application/octet-stream',
+        },
+      },
+    ]);
+  });
+
+  it('serializes unknown ContentPart variants', () => {
+    // Force an unknown variant past the type system
+    const content = [
+      { type: 'custom_widget', payload: 123 },
+    ] as unknown as ContentPart[];
+    const result = contentPartsToGeminiParts(content);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({
+      text: JSON.stringify({ type: 'custom_widget', payload: 123 }),
+    });
+  });
+});
+
+describe('toolResultDisplayToContentParts', () => {
+  it('returns undefined for undefined', () => {
+    expect(toolResultDisplayToContentParts(undefined)).toBeUndefined();
+  });
+
+  it('returns undefined for null', () => {
+    expect(toolResultDisplayToContentParts(null)).toBeUndefined();
+  });
+
+  it('handles string resultDisplay as-is', () => {
+    const result = toolResultDisplayToContentParts('File written');
+    expect(result).toEqual([{ type: 'text', text: 'File written' }]);
+  });
+
+  it('stringifies object resultDisplay', () => {
+    const display = { type: 'FileDiff', oldPath: 'a.ts', newPath: 'b.ts' };
+    const result = toolResultDisplayToContentParts(display);
+    expect(result).toEqual([{ type: 'text', text: JSON.stringify(display) }]);
+  });
+});
+
+describe('buildToolResponseData', () => {
+  it('preserves outputFile and contentLength', () => {
+    const result = buildToolResponseData({
+      outputFile: '/tmp/result.txt',
+      contentLength: 256,
+    });
+    expect(result).toEqual({
+      outputFile: '/tmp/result.txt',
+      contentLength: 256,
+    });
+  });
+
+  it('returns undefined for empty response', () => {
+    const result = buildToolResponseData({});
+    expect(result).toBeUndefined();
+  });
+
+  it('includes errorType when present', () => {
+    const result = buildToolResponseData({
+      errorType: 'permission_denied',
+    });
+    expect(result).toEqual({ errorType: 'permission_denied' });
+  });
+
+  it('merges data with other fields', () => {
+    const result = buildToolResponseData({
+      data: { custom: 'value' },
+      outputFile: '/tmp/file.txt',
+    });
+    expect(result).toEqual({
+      custom: 'value',
+      outputFile: '/tmp/file.txt',
+    });
+  });
+});

packages/core/src/agent/content-utils.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Part } from '@google/genai';
+import type { ContentPart } from './types.js';
+
+/**
+ * Converts Gemini API Part objects to framework-agnostic ContentPart objects.
+ * Handles text, thought, inlineData, fileData parts and serializes unknown
+ * part types to text to avoid silent data loss.
+ */
+export function geminiPartsToContentParts(parts: Part[]): ContentPart[] {
+  const result: ContentPart[] = [];
+  for (const part of parts) {
+    if ('text' in part && part.text !== undefined) {
+      if ('thought' in part && part.thought) {
+        result.push({
+          type: 'thought',
+          thought: part.text,
+          ...(part.thoughtSignature
+            ? { thoughtSignature: part.thoughtSignature }
+            : {}),
+        });
+      } else {
+        result.push({ type: 'text', text: part.text });
+      }
+    } else if ('inlineData' in part && part.inlineData) {
+      result.push({
+        type: 'media',
+        data: part.inlineData.data,
+        mimeType: part.inlineData.mimeType,
+      });
+    } else if ('fileData' in part && part.fileData) {
+      result.push({
+        type: 'media',
+        uri: part.fileData.fileUri,
+        mimeType: part.fileData.mimeType,
+      });
+    } else if ('functionCall' in part && part.functionCall) {
+      continue; // Skip function calls, they are emitted as distinct tool_request events
+    } else if ('functionResponse' in part && part.functionResponse) {
+      continue; // Skip function responses, they are tied to tool_response events
+    } else {
+      // Fallback: serialize any unrecognized part type to text
+      result.push({
+        type: 'text',
+        text: JSON.stringify(part),
+        _meta: { partType: 'unknown' },
+      });
+    }
+  }
+  return result;
+}
+
+/**
+ * Converts framework-agnostic ContentPart objects to Gemini API Part objects.
+ */
+export function contentPartsToGeminiParts(content: ContentPart[]): Part[] {
+  const result: Part[] = [];
+  for (const part of content) {
+    switch (part.type) {
+      case 'text':
+        result.push({ text: part.text });
+        break;
+      case 'thought':
+        result.push({
+          text: part.thought,
+          thought: true,
+          ...(part.thoughtSignature
+            ? { thoughtSignature: part.thoughtSignature }
+            : {}),
+        });
+        break;
+      case 'media':
+        if (part.data) {
+          result.push({
+            inlineData: {
+              data: part.data,
+              mimeType: part.mimeType ?? 'application/octet-stream',
+            },
+          });
+        } else if (part.uri) {
+          result.push({
+            fileData: { fileUri: part.uri, mimeType: part.mimeType },
+          });
+        }
+        break;
+      case 'reference':
+        // References are converted to text for the model
+        result.push({ text: part.text });
+        break;
+      default:
+        // Serialize unknown ContentPart variants instead of dropping them
+        result.push({ text: JSON.stringify(part) });
+        break;
+    }
+  }
+  return result;
+}
+
+/**
+ * Converts a ToolCallResponseInfo.resultDisplay value into ContentPart[].
+ * Handles string, object-valued (FileDiff, SubagentProgress, etc.),
+ * and undefined resultDisplay consistently.
+ */
+export function toolResultDisplayToContentParts(
+  resultDisplay: unknown,
+): ContentPart[] | undefined {
+  if (resultDisplay === undefined || resultDisplay === null) {
+    return undefined;
+  }
+  const text =
+    typeof resultDisplay === 'string'
+      ? resultDisplay
+      : JSON.stringify(resultDisplay);
+  return [{ type: 'text', text }];
+}
+
+/**
+ * Builds the data record for a tool_response AgentEvent, preserving
+ * all available metadata from the ToolCallResponseInfo.
+ */
+export function buildToolResponseData(response: {
+  data?: Record<string, unknown>;
+  errorType?: string;
+  outputFile?: string;
+  contentLength?: number;
+}): Record<string, unknown> | undefined {
+  const parts: Record<string, unknown> = {};
+  if (response.data) Object.assign(parts, response.data);
+  if (response.errorType) parts['errorType'] = response.errorType;
+  if (response.outputFile) parts['outputFile'] = response.outputFile;
+  if (response.contentLength !== undefined)
+    parts['contentLength'] = response.contentLength;
+  return Object.keys(parts).length > 0 ? parts : undefined;
+}

packages/core/src/config/config.ts

@@ -649,6 +649,7 @@ export interface ConfigParameters {
   billing?: {
     overageStrategy?: OverageStrategy;
   };
+  simulateUser?: boolean;
 }
 
 export class Config implements McpContext, AgentLoopContext {
@@ -866,6 +867,7 @@ export class Config implements McpContext, AgentLoopContext {
   private lastModeSwitchTime: number = performance.now();
   readonly injectionService: InjectionService;
   private approvedPlanPath: string | undefined;
+  private readonly simulateUser: boolean;
 
   constructor(params: ConfigParameters) {
     this._sessionId = params.sessionId;
@@ -1095,6 +1097,7 @@ export class Config implements McpContext, AgentLoopContext {
     this.fileExclusions = new FileExclusions(this);
     this.eventEmitter = params.eventEmitter;
     this.enableConseca = params.enableConseca ?? false;
+    this.simulateUser = params.simulateUser ?? false;
 
     // Initialize Safety Infrastructure
     const contextBuilder = new ContextBuilder(this);
@@ -2509,6 +2512,10 @@ export class Config implements McpContext, AgentLoopContext {
     return this.usageStatisticsEnabled;
   }
 
+  getSimulateUser(): boolean {
+    return this.simulateUser;
+  }
+
   getAcpMode(): boolean {
     return this.acpMode;
   }

packages/core/src/config/defaultModelConfigs.ts

@@ -277,7 +277,7 @@ export const DEFAULT_MODEL_CONFIGS: ModelConfigServiceConfig = {
       family: 'gemini-3',
       isPreview: true,
       isVisible: true,
-      features: { thinking: false, multimodalToolUse: true },
+      features: { thinking: true, multimodalToolUse: true },
     },
     'gemini-2.5-pro': {
       tier: 'pro',

packages/core/src/core/contentGenerator.test.ts

@@ -725,6 +725,26 @@ describe('createContentGeneratorConfig', () => {
     expect(config.apiKey).toBeUndefined();
     expect(config.vertexai).toBeUndefined();
   });
+  it('should configure for GATEWAY using dummy placeholder if GEMINI_API_KEY is set', async () => {
+    vi.stubEnv('GEMINI_API_KEY', 'env-gemini-key');
+    const config = await createContentGeneratorConfig(
+      mockConfig,
+      AuthType.GATEWAY,
+    );
+    expect(config.apiKey).toBe('gateway-placeholder-key');
+    expect(config.vertexai).toBe(false);
+  });
+
+  it('should configure for GATEWAY using dummy placeholder if GEMINI_API_KEY is not set', async () => {
+    vi.stubEnv('GEMINI_API_KEY', '');
+    vi.mocked(loadApiKey).mockResolvedValue(null);
+    const config = await createContentGeneratorConfig(
+      mockConfig,
+      AuthType.GATEWAY,
+    );
+    expect(config.apiKey).toBe('gateway-placeholder-key');
+    expect(config.vertexai).toBe(false);
+  });
 });
 
 describe('validateBaseUrl', () => {

packages/core/src/core/contentGenerator.ts

@@ -150,6 +150,13 @@ export async function createContentGeneratorConfig(
     return contentGeneratorConfig;
   }
 
+  if (authType === AuthType.GATEWAY) {
+    contentGeneratorConfig.apiKey = apiKey || 'gateway-placeholder-key';
+    contentGeneratorConfig.vertexai = false;
+
+    return contentGeneratorConfig;
+  }
+
   return contentGeneratorConfig;
 }
 

packages/core/src/telemetry/llmRole.ts

@@ -16,4 +16,5 @@ export enum LlmRole {
   UTILITY_EDIT_CORRECTOR = 'utility_edit_corrector',
   UTILITY_AUTOCOMPLETE = 'utility_autocomplete',
   UTILITY_FAST_ACK_HELPER = 'utility_fast_ack_helper',
+  UTILITY_SIMULATOR = 'utility_simulator',
 }

packages/dd.md

@@ -0,0 +1,72 @@
+# User Simulation Feature - Design Document
+
+*Branch: `user-simulation`*
+
+## 1. Overview
+The User Simulation feature enables an autonomous LLM-driven agent to act as a realistic user in interactive terminal sessions. It aims to support integration testing, evaluation, and background evaluation of system capabilities by effectively observing the terminal interface and supplying contextual standard input (stdin). 
+
+This is accomplished by adding a `--simulate-user` option to the CLI, intercepting terminal updates via a simulated stdout reader, computing appropriate responses via an LLM, and piping these directly into a `PassThrough` stream masquerading as `process.stdin`.
+
+## 2. Core Architecture
+
+### 2.1 Configurations and Triggers
+**Affected Files:**
+- `packages/cli/src/config/config.ts`
+- `packages/core/src/config/config.ts`
+- `packages/cli/src/interactiveCli.tsx`
+
+**Implementation:**
+The feature is controlled via the explicit CLI argument `--simulate-user`. When supplied, the argument flows through the `Config` interface (`config.getSimulateUser()`), modifying how the interactive CLI bootstraps.
+- Instead of attaching the raw `process.stdin` directly to the `ink` render environment, the UI engine binds to a Node.js `PassThrough` stream if simulation is enabled.
+- The Interactive CLI session begins by initiating the `UserSimulator`, providing it access to the `Config`, the `simulatedStdin` buffer, and an observable snapshot of the `lastFrame` (the current state of the UI render).
+
+### 2.2 The `UserSimulator` Service
+**Affected Files:**
+- `packages/cli/src/services/UserSimulator.ts`
+
+**Implementation:**
+The `UserSimulator` class governs the core observation and input loops. It handles interactions asynchronously outside of the primary command execution flow.
+
+#### Loop Execution
+The simulator runs via a repeating timer (3-second intervals `setInterval`), checking `tick()`. It ensures only one evaluation happens sequentially using a mutex lock (`this.isProcessing`).
+
+#### Screen Processing and Environment Context
+The engine receives the rendered terminal snapshot (`lastFrame`) and applies sanitizations:
+- Removes ANSI terminal colors and cursor properties using regex filtering.
+- Strips variable UI animation symbols (Spinners like ⠋, ⠙) and time indicators (e.g., `[ 7s ]`).
+These visual stability checks allow the simulator to detect meaningful frame changes instead of being repeatedly triggered by minor clock updates.
+
+#### Simulation Brain & LLM Integration
+The simulator utilizes `PREVIEW_GEMINI_FLASH_MODEL`, leveraging the newly configured `thinking: true` capacity (`packages/core/src/config/defaultModelConfigs.ts`) for better reasoning, operating under the distinct telemetry role `LlmRole.UTILITY_SIMULATOR`.
+
+The LLM is provided an extensive context schema encapsulating:
+- **Terminal output:** Current stripped terminal representation.
+- **Original task objective:** The intention of the CLI session.
+- **Action Memory:** A tracked sequence (`actionHistory`) of previously executed actions to avoid getting stuck in inquiry loops.
+
+#### State Machine Interpretation
+The model translates the screen context into specific behavioral states:
+- **STATE 1 (WAIT):** Triggered if any indication of internal "thinking" or processing exists (active spinners/timers). Returns `<WAIT>`.
+- **STATE 2 (ACTION/AUTHORIZATION):** Prompt requests an approval (e.g., "Allow execution"). Supplies strict raw choice input.
+- **STATE 3 (DONE):** Fully idle string detection paired with task completion fulfillment. Gracefully types `Thank you\r` and eventually exits indicating `<DONE>`.
+- **STATE 4 (INPUT):** Idle state where continuation text instruction is needed, supplying direct commands injected to stdin.
+
+#### Safeguards and Debugging
+- **Anti-Stall Mechanism:** The simulator tracks repetitive actions. If the LLM repeats the exact same non-empty interaction `MAX_REPEATS` (3) times, it terminates the process abruptly to prevent infinite loops.
+- **Interaction Transcripts:** Binds an audit log, dumping each parsed `[SIMULATOR] Screen Content Seen` block, the constructed `Prompt Used`, and `Raw model response` to discrete contextual `interactions_<timestamp>.txt` files, making it traceable.
+
+### 2.3 Required Ecosystem Changes
+- `packages/core/src/telemetry/llmRole.ts`: A new internal trace role `UTILITY_SIMULATOR` has been appended to separate evaluation events from main-thread generations.
+- `packages/core/src/config/defaultModelConfigs.ts`: Added dynamic thought logic parameter (`thinking: true`) for `gemini-3-flash-preview` to enhance the simulation depth reasoning.
+- Unit Testing Mocks: Updated dummy interface `mockConfig.ts` to ensure compatibility by safely mocking `getSimulateUser`.
+
+## 3. Workflow Summary
+1. The user launches `gemini --simulate-user`.
+2. Interactive UI bindings swap `process.stdin` for a readable `PassThrough` stream.
+3. Every 3 seconds, `UserSimulator.tick()` accesses the newest render frame. 
+4. The frame is stripped of unstable metrics/spinners. If the clean frame is unchanged since the last tick, it waits.
+5. If changed, the simulator invokes Gemini Flash Preview (Thinking).
+6. Gemini observes the state—emitting `<WAIT>` if busy, action keys for selections, `<DONE>` if completed, or commands to be resolved.
+7. Return text is piped cleanly back to `simulatedStdin`—advancing the ink render state.
+
+*This design effectively encapsulates the user interface flow without imposing side-effects on standard operations.*

packages/vscode-ide-companion/package.json

@@ -129,7 +129,7 @@
     "@types/vscode": "^1.99.0",
     "@typescript-eslint/eslint-plugin": "^8.31.1",
     "@typescript-eslint/parser": "^8.31.1",
-    "@vscode/vsce": "^3.6.0",
+    "@vscode/vsce": "^3.7.1",
     "esbuild": "^0.25.3",
     "eslint": "^9.25.1",
     "npm-run-all2": "^8.0.2",