pikiclaw 0.2.63 → 0.2.65

package/README.md

@@ -8,6 +8,8 @@
 
 > npx pikiclaw@latest
 
+<img src="docs/promo-install.gif" alt="Quick install" width="700">
+
 <p align="center">
 <a href="https://www.npmjs.com/package/pikiclaw"><img src="https://img.shields.io/npm/v/pikiclaw" alt="npm"></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
@@ -45,7 +47,20 @@ pikiclaw 的目标很直接：
        你的电脑
 ```
 
-它适合的不是“演示一次 AI”，而是你离开电脑以后，Agent 还能继续在本机把事做完。
+它适合的不是”演示一次 AI”，而是你离开电脑以后，Agent 还能继续在本机把事做完。
+
+### 在 Telegram 里长这样
+
+<table>
+<tr>
+<td align=”center”><b>命令与 Agent 切换</b><br><img src=”docs/promo-tg-commands.png” alt=”Commands” width=”320”></td>
+<td align=”center”><b>代码审查</b><br><img src=”docs/promo-tg-task.png” alt=”Code review” width=”320”></td>
+</tr>
+<tr>
+<td align=”center”><b>多轮编码 + 文件回传</b><br><img src=”docs/promo-tg-complex.png” alt=”Complex task” width=”320”></td>
+<td align=”center”><b>状态监控 + 会话管理</b><br><img src=”docs/promo-tg-sessions.png” alt=”Sessions” width=”320”></td>
+</tr>
+</table>
 
 ---
 
@@ -76,6 +91,19 @@ npx pikiclaw@latest
 - 工作目录切换
 - 会话和运行状态查看
 
+<details>
+<summary>Dashboard 截图</summary>
+
+**配置管理** — IM 接入、AI Agent、系统权限
+
+<img src="docs/promo-dashboard-config.png" alt="Config" width="700">
+
+**会话管理** — 按 Agent 分组的会话泳道
+
+<img src="docs/promo-dashboard-sessions.png" alt="Sessions" width="700">
+
+</details>
+
 如果你更喜欢终端向导：
 
 ```bash
@@ -130,7 +158,7 @@ npx pikiclaw@latest --doctor
 
 可选 GUI 能力：
 
-- 浏览器自动化：通过 `@playwright/mcp` 补充接入，默认支持 Chrome extension mode，也可切到 headless / isolated 模式
+- 浏览器自动化：通过 `@playwright/mcp` 管理一个专用的持久化 Chrome profile；第一次使用时在这个自动化浏览器里登录需要的网站，后续任务会复用同一个 profile
 - macOS 桌面自动化：通过 Appium Mac2 提供 `desktop_open_app`、`desktop_snapshot`、`desktop_click`、`desktop_type`、`desktop_screenshot` 等工具
 
 ---
@@ -152,22 +180,25 @@ npx pikiclaw@latest --doctor
 
 普通文本消息会直接转给当前 Agent。
 
+<details>
+<summary>Telegram 命令效果预览</summary>
+
+<img src="docs/promo-tg-commands.png" alt="Commands in Telegram" width="360">
+
+</details>
+
 ---
 
 ## Config And Setup Notes
 
 - 持久化配置在 `~/.pikiclaw/setting.json`
-- Dashboard 是主配置入口，环境变量仍然可用
-- 浏览器 GUI 相关常用变量：
-  - `PIKICLAW_BROWSER_GUI`
-  - `PIKICLAW_BROWSER_USE_EXTENSION`
-  - `PIKICLAW_BROWSER_HEADLESS`
-  - `PIKICLAW_BROWSER_ISOLATED`
-  - `PLAYWRIGHT_MCP_EXTENSION_TOKEN`
+- Dashboard 是主配置入口，其他运行时配置仍然可用
 - 桌面 GUI 相关常用变量：
   - `PIKICLAW_DESKTOP_GUI`
   - `PIKICLAW_DESKTOP_APPIUM_URL`
 
+浏览器自动化由 dashboard 和本地运行时共同管理，会自动创建并复用专用的 Chrome profile 目录。你只需要在这个专用浏览器里登录需要自动化的网站账号一次。
+
 如果要启用 macOS 桌面自动化，需要先准备 Appium Mac2：
 
 ```bash

package/dist/bot.js

@@ -10,6 +10,7 @@ import { execSync, spawn } from 'node:child_process';
 import { getActiveUserConfig, onUserConfigChange, resolveUserWorkdir, setUserWorkdir } from './user-config.js';
 import { doStream, getSessions, getSessionTail, getUsage, initializeProjectSkills, listAgents, listModels, listSkills, stageSessionFiles, isPendingSessionId, normalizeClaudeModelId, } from './code-agent.js';
 import { getDriver, hasDriver, allDriverIds } from './agent-driver.js';
+import { resolveGuiIntegrationConfig } from './mcp-bridge.js';
 import { terminateProcessTree } from './process-control.js';
 import { VERSION } from './version.js';
 import { buildHumanLoopResponse, createEmptyHumanLoopAnswer, currentHumanLoopQuestion, isHumanLoopAwaitingText, setHumanLoopOption, setHumanLoopText, skipHumanLoopQuestion, } from './human-loop.js';
@@ -221,6 +222,23 @@ function buildMcpDeliveryPrompt() {
         'This is an IM conversation, so pay attention to the IM tools.',
     ].join('\n');
 }
+function buildBrowserAutomationPrompt(browserEnabled) {
+    if (!browserEnabled) {
+        return [
+            '[Browser Automation]',
+            'Managed browser automation is disabled by default for this session.',
+            process.platform === 'darwin'
+                ? 'On macOS, operate your main browser directly with native commands such as open, osascript, and screencapture when needed.'
+                : 'Use native OS or browser commands directly when browser automation is not enabled.',
+        ].join('\n');
+    }
+    return [
+        '[Browser Automation]',
+        'A Playwright MCP browser server is already configured to use the local Chrome channel with a persistent profile.',
+        'Do not call browser_install unless a browser tool explicitly reports that Chrome or the browser is missing.',
+        'If you need a new tab, use browser_tabs with action="new".',
+    ].join('\n');
+}
 function configModelValue(config, agent) {
     switch (agent) {
         case 'claude': return normalizeClaudeModelId(config.claudeModel || process.env.CLAUDE_MODEL || 'claude-opus-4-6');
@@ -1072,11 +1090,15 @@ export class Bot {
         const resolvedModel = cs.modelId || this.modelForAgent(cs.agent);
         const agentConfig = this.agentConfigs[cs.agent] || {};
         const extraArgs = agentConfig.extraArgs || [];
+        const browserEnabled = resolveGuiIntegrationConfig(getActiveUserConfig()).browserEnabled;
         this.log(`[runStream] agent=${cs.agent} session=${cs.sessionId || '(new)'} workdir=${this.workdir} timeout=${this.runTimeout}s attachments=${attachments.length}`);
         this.log(`[runStream] ${cs.agent} config: model=${resolvedModel} extraArgs=[${extraArgs.join(' ')}]`);
         const isFirstTurnOfSession = !cs.sessionId || isPendingSessionId(cs.sessionId);
+        const mcpSystemPrompt = mcpSendFile
+            ? appendExtraPrompt(buildMcpDeliveryPrompt(), buildBrowserAutomationPrompt(browserEnabled))
+            : '';
         const effectiveSystemPrompt = isFirstTurnOfSession
-            ? (mcpSendFile ? appendExtraPrompt(systemPrompt, buildMcpDeliveryPrompt()) : systemPrompt)
+            ? appendExtraPrompt(systemPrompt, mcpSystemPrompt)
             : undefined;
         const opts = {
             agent: cs.agent, prompt, workdir: this.workdir, timeout: this.runTimeout,

package/dist/browser-profile.js

@@ -0,0 +1,458 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { spawn, spawnSync } from 'node:child_process';
+import { MANAGED_BROWSER_PROFILE_SUBPATH, PLAYWRIGHT_MCP_PACKAGE_NAME, PLAYWRIGHT_MCP_PACKAGE_SPEC, PLAYWRIGHT_MCP_BROWSER_ARGS, } from './constants.js';
+const MANAGED_BROWSER_SETUP_STATE_FILENAME = 'managed-browser-setup.json';
+const MANAGED_BROWSER_SHUTDOWN_TIMEOUT_MS = 5_000;
+const MANAGED_BROWSER_SHUTDOWN_POLL_MS = 100;
+const MANAGED_BROWSER_DEBUG_PORT = 39222;
+const require = createRequire(import.meta.url);
+function normalizeBrowserCdpEndpoint(endpoint) {
+    const value = String(endpoint || '').trim();
+    if (!value)
+        return '';
+    return value.replace(/\/+$/, '');
+}
+async function resolveBrowserCdpEndpoint(endpoint) {
+    const normalizedEndpoint = normalizeBrowserCdpEndpoint(endpoint);
+    if (!normalizedEndpoint)
+        return null;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 1_500);
+    try {
+        const response = await fetch(`${normalizedEndpoint}/json/version`, { signal: controller.signal });
+        if (!response.ok)
+            return null;
+        const payload = await response.json().catch(() => null);
+        return typeof payload?.webSocketDebuggerUrl === 'string' ? normalizedEndpoint : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function resolveOnPath(command) {
+    const checker = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        const result = spawnSync(checker, [command], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return null;
+        const lines = String(result.stdout || '').split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+        return lines[0] || null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveCommonChromePaths() {
+    if (process.platform === 'darwin') {
+        return [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            path.join(os.homedir(), 'Applications', 'Google Chrome.app', 'Contents', 'MacOS', 'Google Chrome'),
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+            path.join(os.homedir(), 'Applications', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'),
+        ];
+    }
+    if (process.platform === 'win32') {
+        const programFiles = process.env.ProgramFiles || '';
+        const programFilesX86 = process.env['ProgramFiles(x86)'] || '';
+        const localAppData = process.env.LOCALAPPDATA || '';
+        return [
+            programFiles ? path.join(programFiles, 'Google', 'Chrome', 'Application', 'chrome.exe') : '',
+            programFilesX86 ? path.join(programFilesX86, 'Google', 'Chrome', 'Application', 'chrome.exe') : '',
+            localAppData ? path.join(localAppData, 'Google', 'Chrome', 'Application', 'chrome.exe') : '',
+        ].filter(Boolean);
+    }
+    return [];
+}
+function resolveMacBrowserAppName(chromeExecutable) {
+    if (process.platform !== 'darwin')
+        return null;
+    if (chromeExecutable.includes('/Chromium.app/'))
+        return 'Chromium';
+    if (chromeExecutable.includes('/Google Chrome.app/'))
+        return 'Google Chrome';
+    return null;
+}
+function normalizeManagedBrowserWindow(chromeExecutable) {
+    if (process.platform !== 'darwin')
+        return;
+    const appName = resolveMacBrowserAppName(chromeExecutable);
+    if (!appName)
+        return;
+    const script = [
+        'set screenBounds to {0, 0, 1440, 900}',
+        'try',
+        '  tell application "Finder" to set screenBounds to bounds of window of desktop',
+        'end try',
+        `tell application "${appName}"`,
+        '  activate',
+        '  delay 0.4',
+        '  try',
+        '    set zoomed of front window to true',
+        '  end try',
+        '  try',
+        '    set bounds of front window to screenBounds',
+        '  end try',
+        'end tell',
+    ].join('\n');
+    setTimeout(() => {
+        try {
+            const proc = spawn('osascript', ['-e', script], {
+                detached: true,
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+            proc.unref();
+        }
+        catch { }
+    }, 700);
+}
+export function getManagedBrowserProfileDir() {
+    return path.join(os.homedir(), MANAGED_BROWSER_PROFILE_SUBPATH);
+}
+export function ensureManagedBrowserProfileDir() {
+    const profileDir = getManagedBrowserProfileDir();
+    fs.mkdirSync(profileDir, { recursive: true });
+    return profileDir;
+}
+export function getManagedBrowserMcpArgs(profileDir = getManagedBrowserProfileDir(), options = {}) {
+    if (options.cdpEndpoint) {
+        return ['--cdp-endpoint', options.cdpEndpoint];
+    }
+    return [
+        ...PLAYWRIGHT_MCP_BROWSER_ARGS,
+        ...(options.headless ? ['--headless'] : []),
+        '--user-data-dir',
+        profileDir,
+    ];
+}
+export function resolveManagedBrowserMcpCliPath() {
+    try {
+        const packageJsonPath = require.resolve(`${PLAYWRIGHT_MCP_PACKAGE_NAME}/package.json`);
+        const cliPath = path.join(path.dirname(packageJsonPath), 'cli.js');
+        return fs.existsSync(cliPath) ? cliPath : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveManagedBrowserMcpCommand(profileDir = getManagedBrowserProfileDir(), options = {}) {
+    const cliPath = resolveManagedBrowserMcpCliPath();
+    const runtimeArgs = getManagedBrowserMcpArgs(profileDir, options);
+    if (cliPath) {
+        return {
+            command: process.execPath,
+            args: [cliPath, ...runtimeArgs],
+            source: 'local',
+        };
+    }
+    return {
+        command: 'npx',
+        args: ['-y', PLAYWRIGHT_MCP_PACKAGE_SPEC, ...runtimeArgs],
+        source: 'npx',
+    };
+}
+export function getManagedBrowserLaunchArgs(profileDir = getManagedBrowserProfileDir()) {
+    const windowArgs = process.platform === 'darwin'
+        ? ['--start-maximized', '--start-fullscreen', '--window-position=0,0']
+        : ['--start-maximized'];
+    return [
+        `--user-data-dir=${profileDir}`,
+        `--remote-debugging-port=${MANAGED_BROWSER_DEBUG_PORT}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--new-window',
+        ...windowArgs,
+        'about:blank',
+    ];
+}
+export function findChromeExecutable() {
+    for (const candidate of resolveCommonChromePaths()) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    const commands = process.platform === 'win32'
+        ? ['chrome', 'google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser']
+        : ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome'];
+    for (const command of commands) {
+        const resolved = resolveOnPath(command);
+        if (resolved)
+            return resolved;
+    }
+    return null;
+}
+function getManagedBrowserSetupStatePath(profileDir = getManagedBrowserProfileDir()) {
+    return path.join(path.dirname(profileDir), MANAGED_BROWSER_SETUP_STATE_FILENAME);
+}
+function readManagedBrowserSetupState(profileDir = getManagedBrowserProfileDir()) {
+    try {
+        const raw = fs.readFileSync(getManagedBrowserSetupStatePath(profileDir), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed.pid !== 'number' || parsed.pid <= 0)
+            return null;
+        if (typeof parsed.profileDir !== 'string' || !parsed.profileDir.trim())
+            return null;
+        if (typeof parsed.chromeExecutable !== 'string' || !parsed.chromeExecutable.trim())
+            return null;
+        return {
+            pid: parsed.pid,
+            profileDir: parsed.profileDir,
+            chromeExecutable: parsed.chromeExecutable,
+            debugPort: typeof parsed.debugPort === 'number' && parsed.debugPort > 0 ? parsed.debugPort : MANAGED_BROWSER_DEBUG_PORT,
+            launchedAt: typeof parsed.launchedAt === 'string' ? parsed.launchedAt : new Date().toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeManagedBrowserSetupState(state) {
+    const statePath = getManagedBrowserSetupStatePath(state.profileDir);
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, JSON.stringify(state), 'utf8');
+}
+function clearManagedBrowserSetupState(profileDir = getManagedBrowserProfileDir()) {
+    try {
+        fs.rmSync(getManagedBrowserSetupStatePath(profileDir), { force: true });
+    }
+    catch { }
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readProcessCommand(pid) {
+    try {
+        if (process.platform === 'win32') {
+            const result = spawnSync('powershell', ['-NoProfile', '-Command', `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CommandLine`], { encoding: 'utf8' });
+            if (result.status !== 0)
+                return '';
+            return String(result.stdout || '').trim();
+        }
+        const result = spawnSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return '';
+        return String(result.stdout || '').trim();
+    }
+    catch {
+        return '';
+    }
+}
+function commandUsesManagedProfile(command, profileDir) {
+    const normalizedCommand = command.trim();
+    return normalizedCommand.includes(`--user-data-dir=${profileDir}`)
+        || normalizedCommand.includes(`--user-data-dir ${profileDir}`);
+}
+function isManagedBrowserRootProcess(command, profileDir) {
+    if (!commandUsesManagedProfile(command, profileDir))
+        return false;
+    return !command.includes(' --type=');
+}
+function findManagedBrowserRootPids(profileDir = getManagedBrowserProfileDir()) {
+    if (process.platform === 'win32') {
+        const tracked = readManagedBrowserSetupState(profileDir);
+        if (!tracked || !isPidAlive(tracked.pid))
+            return [];
+        return commandUsesManagedProfile(readProcessCommand(tracked.pid), profileDir) ? [tracked.pid] : [];
+    }
+    try {
+        const result = spawnSync('ps', ['-ax', '-o', 'pid=,command='], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return [];
+        const lines = String(result.stdout || '').split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+        const pids = new Set();
+        for (const line of lines) {
+            const match = line.match(/^(\d+)\s+(.*)$/);
+            if (!match)
+                continue;
+            const pid = Number(match[1]);
+            const command = match[2] || '';
+            if (!Number.isFinite(pid) || pid <= 0)
+                continue;
+            if (!isManagedBrowserRootProcess(command, profileDir))
+                continue;
+            pids.add(pid);
+        }
+        return [...pids];
+    }
+    catch {
+        return [];
+    }
+}
+function resolveManagedBrowserRunningState(profileDir = getManagedBrowserProfileDir()) {
+    const tracked = readManagedBrowserSetupState(profileDir);
+    if (tracked) {
+        const command = readProcessCommand(tracked.pid);
+        if (isPidAlive(tracked.pid) && commandUsesManagedProfile(command, profileDir)) {
+            return { running: true, pid: tracked.pid };
+        }
+        clearManagedBrowserSetupState(profileDir);
+    }
+    const rootPids = findManagedBrowserRootPids(profileDir);
+    if (!rootPids.length)
+        return { running: false, pid: null };
+    return { running: true, pid: rootPids[0] ?? null };
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+async function waitForPidExit(pid, timeoutMs = MANAGED_BROWSER_SHUTDOWN_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isPidAlive(pid))
+            return true;
+        await sleep(MANAGED_BROWSER_SHUTDOWN_POLL_MS);
+    }
+    return !isPidAlive(pid);
+}
+async function terminatePid(pid) {
+    if (!isPidAlive(pid))
+        return true;
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return !isPidAlive(pid);
+    }
+    if (await waitForPidExit(pid))
+        return true;
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch { }
+    return waitForPidExit(pid, 1_000);
+}
+function getManagedBrowserDebugEndpoint(port) {
+    return `http://127.0.0.1:${port}`;
+}
+async function resolveManagedBrowserCdpEndpoint(port) {
+    return resolveBrowserCdpEndpoint(getManagedBrowserDebugEndpoint(port));
+}
+async function waitForManagedBrowserCdpEndpoint(port, timeoutMs = 6_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const endpoint = await resolveManagedBrowserCdpEndpoint(port);
+        if (endpoint)
+            return endpoint;
+        await sleep(200);
+    }
+    return resolveManagedBrowserCdpEndpoint(port);
+}
+async function closeManagedBrowserProcesses(profileDir) {
+    const tracked = readManagedBrowserSetupState(profileDir);
+    const candidates = new Set(findManagedBrowserRootPids(profileDir));
+    if (tracked?.pid)
+        candidates.add(tracked.pid);
+    const closedPids = [];
+    for (const pid of candidates) {
+        if (await terminatePid(pid))
+            closedPids.push(pid);
+    }
+    const remaining = findManagedBrowserRootPids(profileDir);
+    if (remaining.length) {
+        throw new Error(`Managed browser profile is still in use by pid ${remaining.join(', ')}. Close the setup browser before retrying.`);
+    }
+    clearManagedBrowserSetupState(profileDir);
+    return closedPids;
+}
+export async function prepareManagedBrowserForAutomation(profileDir = getManagedBrowserProfileDir(), options = {}) {
+    const tracked = readManagedBrowserSetupState(profileDir);
+    const runningState = resolveManagedBrowserRunningState(profileDir);
+    if (runningState.running) {
+        const cdpEndpoint = await resolveManagedBrowserCdpEndpoint(tracked?.debugPort || MANAGED_BROWSER_DEBUG_PORT);
+        if (cdpEndpoint) {
+            return {
+                profileDir,
+                closedPids: [],
+                cdpEndpoint,
+                connectionMode: 'attach',
+            };
+        }
+    }
+    const closedPids = await closeManagedBrowserProcesses(profileDir);
+    if (!options.headless) {
+        launchManagedBrowserSetup();
+        const cdpEndpoint = await waitForManagedBrowserCdpEndpoint(MANAGED_BROWSER_DEBUG_PORT);
+        if (cdpEndpoint) {
+            return {
+                profileDir,
+                closedPids,
+                cdpEndpoint,
+                connectionMode: 'attach',
+            };
+        }
+    }
+    return {
+        profileDir,
+        closedPids,
+        cdpEndpoint: null,
+        connectionMode: 'launch',
+    };
+}
+export function getManagedBrowserStatus() {
+    const profileDir = getManagedBrowserProfileDir();
+    const profileCreated = fs.existsSync(profileDir);
+    const chromeExecutable = findChromeExecutable();
+    const chromeInstalled = !!chromeExecutable;
+    const runningState = resolveManagedBrowserRunningState(profileDir);
+    return {
+        status: chromeInstalled
+            ? profileCreated
+                ? 'ready'
+                : 'needs_setup'
+            : 'chrome_missing',
+        profileDir,
+        profileCreated,
+        chromeInstalled,
+        running: runningState.running,
+        pid: runningState.pid,
+        detail: chromeInstalled
+            ? runningState.running
+                ? 'Managed browser is open for sign-in. pikiclaw will close it automatically before browser automation starts.'
+                : profileCreated
+                    ? 'Managed browser profile is ready. Launch it to confirm login state. If it is still open later, pikiclaw will close it automatically before browser automation starts.'
+                    : 'Chrome is installed. Launch the managed browser once and sign in to the sites you need. If it is still open later, pikiclaw will close it automatically before browser automation starts.'
+            : 'Chrome is not available on this machine. Install Google Chrome or Chromium to use browser automation.',
+        chromeExecutable,
+        launchCommand: chromeExecutable ? [chromeExecutable, ...getManagedBrowserLaunchArgs(profileDir)] : [],
+    };
+}
+export function launchManagedBrowserSetup() {
+    const profileDir = ensureManagedBrowserProfileDir();
+    const chromeExecutable = findChromeExecutable();
+    if (!chromeExecutable) {
+        throw new Error('Chrome is not available on this machine');
+    }
+    const existing = resolveManagedBrowserRunningState(profileDir);
+    if (existing.running) {
+        normalizeManagedBrowserWindow(chromeExecutable);
+        return { ...getManagedBrowserStatus(), pid: existing.pid };
+    }
+    const child = spawn(chromeExecutable, getManagedBrowserLaunchArgs(profileDir), {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    child.unref();
+    normalizeManagedBrowserWindow(chromeExecutable);
+    if (child.pid) {
+        writeManagedBrowserSetupState({
+            pid: child.pid,
+            profileDir,
+            chromeExecutable,
+            debugPort: MANAGED_BROWSER_DEBUG_PORT,
+            launchedAt: new Date().toISOString(),
+        });
+    }
+    return { ...getManagedBrowserStatus(), pid: child.pid ?? null };
+}

package/dist/cli.js

@@ -198,6 +198,10 @@ async function handleMcpServeMode() {
         await import('./mcp-session-server.js');
         return true;
     }
+    if (process.argv.includes('--playwright-mcp-proxy')) {
+        await import('./mcp-playwright-proxy.js');
+        return true;
+    }
     return false;
 }
 /** Print help text and exit. */

package/dist/constants.js

@@ -4,6 +4,7 @@
  * Grouped by domain / module so each subsystem can import only the
  * bucket it needs.
  */
+import path from 'node:path';
 // ---------------------------------------------------------------------------
 // MCP bridge
 // ---------------------------------------------------------------------------
@@ -45,11 +46,21 @@ export const DASHBOARD_TIMEOUTS = {
     appiumReachable: 3_000,
     /** Delay between Appium server startup polls. */
     appiumStartPoll: 1_000,
-    /** Timeout for the Playwright MCP extension validation spawn. */
-    extensionValidationSpawn: 12_000,
-    /** Grace period to let Playwright MCP server prove it stays alive. */
-    extensionValidationAlive: 5_000,
 };
+// ---------------------------------------------------------------------------
+// Browser automation
+// ---------------------------------------------------------------------------
+/**
+ * Stable relative path for the managed Chrome profile under the home directory.
+ * Keep this outside config-specific directories so `npm run dev` and the main
+ * runtime share the same browser login state.
+ */
+export const MANAGED_BROWSER_PROFILE_SUBPATH = path.join('.pikiclaw', 'browser', 'chrome-profile');
+/** Base Playwright MCP args for the managed browser integration. */
+export const PLAYWRIGHT_MCP_PACKAGE_NAME = '@playwright/mcp';
+export const PLAYWRIGHT_MCP_PACKAGE_VERSION = '0.0.68';
+export const PLAYWRIGHT_MCP_PACKAGE_SPEC = `${PLAYWRIGHT_MCP_PACKAGE_NAME}@${PLAYWRIGHT_MCP_PACKAGE_VERSION}`;
+export const PLAYWRIGHT_MCP_BROWSER_ARGS = ['--browser', 'chrome'];
 /** Dashboard session pagination limits. */
 export const DASHBOARD_PAGINATION = {
     defaultPageSize: 6,