@adhdev/daemon-core 0.5.3

package/src/daemon/dev-server.ts

@@ -0,0 +1,2378 @@
+/**
+ * Dev Server — HTTP API for Provider debugging + script development
+ * 
+ * Enabled with `adhdev daemon --dev`
+ * Port: 19280 (fixed)
+ * 
+ * API list:
+ * GET /api/providers — loaded provider list
+ * POST /api/providers/:type/script — specific script execute
+ * POST /api/cdp/evaluate — Execute JS expression
+ * POST /api/cdp/dom/query — Test selector
+ * GET /api/cdp/screenshot — screenshot
+ * POST /api/scripts/run — Execute provider script (name + params)
+ * GET /api/status — All status (CDP connection, provider etc)
+ */
+
+import * as http from 'http';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import type { ProviderLoader } from '../providers/provider-loader.js';
+import type { ChildProcess } from 'child_process';
+import type { DaemonCdpManager } from '../cdp/manager.js';
+import { generateTemplate as genScaffoldTemplate, generateFiles as genScaffoldFiles } from './scaffold-template.js';
+import { VersionArchive, detectAllVersions } from '../providers/version-archive.js';
+import { LOG } from '../logging/logger.js';
+
+export const DEV_SERVER_PORT = 19280;
+
+export class DevServer {
+  private server: http.Server | null = null;
+  private providerLoader: ProviderLoader;
+  private cdpManagers: Map<string, DaemonCdpManager>;
+  private logFn: (msg: string) => void;
+  private sseClients: http.ServerResponse[] = [];
+  private watchScriptPath: string | null = null;
+  private watchScriptName: string | null = null;
+  private watchTimer: NodeJS.Timeout | null = null;
+
+  // Auto-implement state
+  private autoImplProcess: ChildProcess | null = null;
+  private autoImplSSEClients: http.ServerResponse[] = [];
+  private autoImplStatus: { running: boolean; type: string | null; progress: any[] } = { running: false, type: null, progress: [] };
+
+  constructor(options: {
+    providerLoader: ProviderLoader;
+    cdpManagers: Map<string, DaemonCdpManager>;
+    logFn?: (msg: string) => void;
+  }) {
+    this.providerLoader = options.providerLoader;
+    this.cdpManagers = options.cdpManagers;
+    this.logFn = options.logFn || LOG.forComponent('DevServer').asLogFn();
+  }
+
+  private log(msg: string): void {
+    this.logFn(`[DevServer] ${msg}`);
+  }
+
+  // ─── Route Table ─────────────────────────────────────
+  private readonly routes: {
+    method: string;
+    pattern: string | RegExp;
+    handler: (req: http.IncomingMessage, res: http.ServerResponse, params?: string[]) => Promise<void> | void;
+  }[] = [
+    // Static routes
+    { method: 'GET',  pattern: '/api/providers',          handler: (q, s) => this.handleListProviders(q, s) },
+    { method: 'GET',  pattern: '/api/providers/versions',  handler: (q, s) => this.handleDetectVersions(q, s) },
+    { method: 'POST', pattern: '/api/providers/reload',    handler: (q, s) => this.handleReload(q, s) },
+    { method: 'POST', pattern: '/api/cdp/evaluate',        handler: (q, s) => this.handleCdpEvaluate(q, s) },
+    { method: 'POST', pattern: '/api/cdp/dom/query',       handler: (q, s) => this.handleCdpDomQuery(q, s) },
+    { method: 'POST', pattern: '/api/cdp/dom/inspect',     handler: (q, s) => this.handleDomInspect(q, s) },
+    { method: 'POST', pattern: '/api/cdp/dom/children',    handler: (q, s) => this.handleDomChildren(q, s) },
+    { method: 'POST', pattern: '/api/cdp/dom/analyze',     handler: (q, s) => this.handleDomAnalyze(q, s) },
+    { method: 'POST', pattern: '/api/cdp/dom/find-text',   handler: (q, s) => this.handleFindByText(q, s) },
+    { method: 'POST', pattern: '/api/cdp/dom/find-common', handler: (q, s) => this.handleFindCommon(q, s) },
+    { method: 'GET',  pattern: '/api/cdp/screenshot',      handler: (q, s) => this.handleScreenshot(q, s) },
+    { method: 'GET',  pattern: '/api/cdp/targets',         handler: (q, s) => this.handleCdpTargets(q, s) },
+    { method: 'POST', pattern: '/api/scripts/run',         handler: (q, s) => this.handleScriptsRun(q, s) },
+    { method: 'GET',  pattern: '/api/status',              handler: (q, s) => this.handleStatus(q, s) },
+    { method: 'POST', pattern: '/api/watch/start',         handler: (q, s) => this.handleWatchStart(q, s) },
+    { method: 'POST', pattern: '/api/watch/stop',          handler: (q, s) => this.handleWatchStop(q, s) },
+    { method: 'GET',  pattern: '/api/watch/events',        handler: (q, s) => this.handleSSE(q, s) },
+    { method: 'POST', pattern: '/api/scaffold',            handler: (q, s) => this.handleScaffold(q, s) },
+    // Dynamic routes (provider :type param)
+    { method: 'POST', pattern: /^\/api\/providers\/([^/]+)\/script$/,                handler: (q, s, p) => this.handleRunScript(p![0], q, s) },
+    { method: 'GET',  pattern: /^\/api\/providers\/([^/]+)\/files$/,                 handler: (q, s, p) => this.handleListFiles(p![0], q, s) },
+    { method: 'GET',  pattern: /^\/api\/providers\/([^/]+)\/file$/,                  handler: (q, s, p) => this.handleReadFile(p![0], q, s) },
+    { method: 'POST', pattern: /^\/api\/providers\/([^/]+)\/file$/,                  handler: (q, s, p) => this.handleWriteFile(p![0], q, s) },
+    { method: 'GET',  pattern: /^\/api\/providers\/([^/]+)\/source$/,                handler: (q, s, p) => this.handleSource(p![0], q, s) },
+    { method: 'POST', pattern: /^\/api\/providers\/([^/]+)\/save$/,                  handler: (q, s, p) => this.handleSave(p![0], q, s) },
+    { method: 'GET',  pattern: /^\/api\/providers\/([^/]+)\/config$/,                handler: (q, s, p) => this.handleProviderConfig(p![0], q, s) },
+    { method: 'POST', pattern: /^\/api\/providers\/([^/]+)\/dom-context$/,           handler: (q, s, p) => this.handleDomContext(p![0], q, s) },
+    { method: 'POST', pattern: /^\/api\/providers\/([^/]+)\/auto-implement$/,        handler: (q, s, p) => this.handleAutoImplement(p![0], q, s) },
+    { method: 'POST', pattern: /^\/api\/providers\/([^/]+)\/auto-implement\/cancel$/,handler: (q, s, p) => this.handleAutoImplCancel(p![0], q, s) },
+    { method: 'GET',  pattern: /^\/api\/providers\/([^/]+)\/auto-implement\/status$/,handler: (q, s, p) => this.handleAutoImplSSE(p![0], q, s) },
+    { method: 'POST', pattern: /^\/api\/providers\/([^/]+)\/spawn-test$/,            handler: (q, s, p) => this.handleSpawnTest(p![0], q, s) },
+    { method: 'POST', pattern: /^\/api\/providers\/([^/]+)\/validate$/,              handler: (q, s, p) => this.handleValidate(p![0], q, s) },
+    { method: 'POST', pattern: /^\/api\/providers\/([^/]+)\/acp-chat$/,              handler: (q, s, p) => this.handleAcpChat(p![0], q, s) },
+    { method: 'GET',  pattern: /^\/api\/providers\/([^/]+)\/script-hints$/,          handler: (q, s, p) => this.handleScriptHints(p![0], q, s) },
+  ];
+
+  private matchRoute(method: string, pathname: string): { handler: (req: http.IncomingMessage, res: http.ServerResponse, params?: string[]) => Promise<void> | void; params?: string[] } | null {
+    for (const route of this.routes) {
+      if (route.method !== method) continue;
+      if (typeof route.pattern === 'string') {
+        if (pathname === route.pattern) return { handler: route.handler };
+      } else {
+        const m = pathname.match(route.pattern);
+        if (m) return { handler: route.handler, params: m.slice(1) };
+      }
+    }
+    return null;
+  }
+
+  private getEndpointList(): string[] {
+    return this.routes.map(r => {
+      const path = typeof r.pattern === 'string'
+        ? r.pattern
+        : r.pattern.source.replace(/\\\//g, '/').replace(/\(\[.*?\]\+\)/g, ':type').replace(/[\^$]/g, '');
+      return `${r.method.padEnd(5)} ${path}`;
+    });
+  }
+
+  async start(port = DEV_SERVER_PORT): Promise<void> {
+    this.server = http.createServer(async (req, res) => {
+      // CORS
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+      if (req.method === 'OPTIONS') {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+
+      const url = new URL(req.url || '/', `http://localhost:${port}`);
+      const pathname = url.pathname;
+
+      try {
+        // ─── Route Table ───
+        const route = this.matchRoute(req.method || 'GET', pathname);
+        if (route) {
+          await route.handler(req, res, route.params);
+        } else if (pathname.startsWith('/assets/') || pathname === '/favicon.ico') {
+          await this.serveStaticAsset(pathname, res);
+        } else if (pathname === '/' || pathname === '/console' || !pathname.startsWith('/api')) {
+          await this.serveConsole(req, res);
+        } else {
+          this.json(res, 404, { error: 'Not found', endpoints: this.getEndpointList() });
+        }
+      } catch (e: any) {
+        this.log(`Error: ${e.message}`);
+        this.json(res, 500, { error: e.message });
+      }
+    });
+
+    return new Promise((resolve, reject) => {
+      this.server!.listen(port, '127.0.0.1', () => {
+        this.log(`Dev server listening on http://127.0.0.1:${port}`);
+        resolve();
+      });
+      this.server!.on('error', (e: any) => {
+        if (e.code === 'EADDRINUSE') {
+          this.log(`Port ${port} in use, skipping dev server`);
+          resolve(); // non-fatal
+        } else {
+          reject(e);
+        }
+      });
+    });
+  }
+
+  stop(): void {
+    this.server?.close();
+    this.server = null;
+  }
+
+  // ─── Handlers ───
+
+  private async handleListProviders(_req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const providers = this.providerLoader.getAll().map(p => {
+      const base: any = {
+        type: p.type,
+        name: p.name,
+        category: p.category,
+        icon: (p as any).icon || null,
+        displayName: (p as any).displayName || p.name,
+      };
+
+      // IDE/Extension specific
+      if (p.category === 'ide' || p.category === 'extension') {
+        base.scripts = p.scripts ? Object.keys(p.scripts).filter(k => typeof (p.scripts as any)[k] === 'function') : [];
+        base.inputMethod = p.inputMethod || null;
+        base.inputSelector = (p as any).inputSelector || null;
+        base.extensionId = p.extensionId || null;
+        base.cdpPorts = (p as any).cdpPorts || [];
+      }
+
+      // ACP specific
+      if (p.category === 'acp') {
+        base.spawn = (p as any).spawn || null;
+        base.auth = (p as any).auth || null;
+        base.install = (p as any).install || null;
+        base.hasSettings = !!(p as any).settings;
+        base.settingsCount = (p as any).settings ? Object.keys((p as any).settings).length : 0;
+      }
+
+      // CLI specific
+      if (p.category === 'cli') {
+        base.spawn = (p as any).spawn || null;
+        base.install = (p as any).install || null;
+      }
+
+      return base;
+    });
+    this.json(res, 200, { providers, count: providers.length });
+  }
+
+  private async handleProviderConfig(type: string, _req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const provider = this.providerLoader.resolve(type);
+    if (!provider) {
+      this.json(res, 404, { error: `Provider not found: ${type}` });
+      return;
+    }
+    // Return full config (sans functions being serialized, just keys)
+    const config: any = { ...provider };
+    // Convert scripts to list of names
+    if (config.scripts) {
+      config.scriptNames = Object.keys(config.scripts).filter(k => typeof config.scripts[k] === 'function');
+      delete config.scripts;
+    }
+    this.json(res, 200, { type, config });
+  }
+
+  private async handleSpawnTest(type: string, req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const provider = this.providerLoader.resolve(type);
+    if (!provider) {
+      this.json(res, 404, { error: `Provider not found: ${type}` });
+      return;
+    }
+
+    const spawn = (provider as any).spawn;
+    if (!spawn) {
+      this.json(res, 400, { error: `Provider ${type} has no spawn config` });
+      return;
+    }
+
+    const { spawn: spawnFn } = await import('child_process');
+    const start = Date.now();
+    try {
+      const child = spawnFn(spawn.command, [...(spawn.args || [])], {
+        shell: spawn.shell ?? false,
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+
+      let stdout = '';
+      let stderr = '';
+      child.stdout?.on('data', (d: Buffer) => { stdout += d.toString().slice(0, 2000); });
+      child.stderr?.on('data', (d: Buffer) => { stderr += d.toString().slice(0, 2000); });
+
+      // Wait for first output or exit (max 3s)
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(() => { child.kill(); resolve(); }, 3000);
+        child.on('exit', () => { clearTimeout(timer); resolve(); });
+        child.stdout?.once('data', () => { setTimeout(() => { child.kill(); clearTimeout(timer); resolve(); }, 500); });
+      });
+
+      const elapsed = Date.now() - start;
+      this.json(res, 200, {
+        success: true,
+        command: `${spawn.command} ${(spawn.args || []).join(' ')}`,
+        elapsed,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        exitCode: child.exitCode,
+      });
+    } catch (e: any) {
+      const elapsed = Date.now() - start;
+      this.json(res, 200, {
+        success: false,
+        command: `${spawn.command} ${(spawn.args || []).join(' ')}`,
+        elapsed,
+        error: e.message,
+      });
+    }
+  }
+
+  private async handleRunScript(type: string, req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { script: scriptName, params, ideType: scriptIdeType } = body;
+
+    const provider = this.providerLoader.resolve(type);
+    if (!provider) {
+      this.json(res, 404, { error: `Provider '${type}' not found` });
+      return;
+    }
+
+    const fn = (provider.scripts as any)?.[scriptName];
+    if (typeof fn !== 'function') {
+      this.json(res, 400, { error: `Script '${scriptName}' not found in provider '${type}'`, available: provider.scripts ? Object.keys(provider.scripts) : [] });
+      return;
+    }
+
+    const cdp = this.getCdp(scriptIdeType);
+    if (!cdp) {
+      this.json(res, 503, { error: 'No CDP connection available' });
+      return;
+    }
+
+    try {
+      // Pass all params to script (flexible parameter support)
+      // Backward compat: legacy single argument scripts (sendMessage(text)) also work
+      const scriptCode = params ? fn(params) : fn();
+      if (!scriptCode) {
+        this.json(res, 500, { error: 'Script function returned null' });
+        return;
+      }
+
+      // Execute webview script via evaluateInWebviewFrame
+      const isWebviewScript = scriptName.toLowerCase().includes('webview');
+      let raw: any;
+      if (isWebviewScript) {
+        const matchText = provider.webviewMatchText;
+        const matchFn = matchText ? (body: string) => body.includes(matchText) : undefined;
+        raw = await cdp.evaluateInWebviewFrame(scriptCode, matchFn);
+      } else {
+        raw = await cdp.evaluate(scriptCode, 30000);
+      }
+
+      let result = raw;
+      if (typeof raw === 'string') {
+        try { result = JSON.parse(raw); } catch { /* keep */ }
+      }
+      this.json(res, 200, { type, script: scriptName, result });
+    } catch (e: any) {
+      this.json(res, 500, { error: `Script execution failed: ${e.message}` });
+    }
+  }
+
+  private async handleCdpEvaluate(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { expression, timeout, ideType } = body;
+    if (!expression) {
+      this.json(res, 400, { error: 'expression required' });
+      return;
+    }
+
+    const cdp = ideType ? this.cdpManagers.get(ideType) : this.getAnyCdp();
+    if (!cdp?.isConnected) {
+      this.json(res, 503, { error: 'No CDP connection available' });
+      return;
+    }
+
+    try {
+      const raw = await cdp.evaluate(expression, timeout || 30000);
+      let result = raw;
+      if (typeof raw === 'string') {
+        try { result = JSON.parse(raw); } catch { /* keep */ }
+      }
+      this.json(res, 200, { result });
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  private async handleCdpDomQuery(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { selector, limit = 10, ideType } = body;
+    if (!selector) {
+      this.json(res, 400, { error: 'selector required' });
+      return;
+    }
+
+    const cdp = this.getCdp(ideType as string);
+    if (!cdp) {
+      this.json(res, 503, { error: 'No CDP connection available' });
+      return;
+    }
+
+    const expr = `(() => {
+      try {
+        const els = document.querySelectorAll('${selector.replace(/'/g, "\\'")}');
+        const results = [];
+        for (let i = 0; i < Math.min(els.length, ${limit}); i++) {
+          const el = els[i];
+          results.push({
+            index: i,
+            tag: el.tagName?.toLowerCase(),
+            id: el.id || null,
+            class: el.className && typeof el.className === 'string' ? el.className.trim().slice(0, 200) : null,
+            role: el.getAttribute?.('role') || null,
+            text: (el.textContent || '').trim().slice(0, 100),
+            visible: el.offsetParent !== null || el.offsetWidth > 0,
+            rect: (() => { try { const r = el.getBoundingClientRect(); return { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) }; } catch { return null; } })()
+          });
+        }
+        return JSON.stringify({ total: els.length, results });
+      } catch (e) { return JSON.stringify({ error: e.message }); }
+    })()`;
+
+    try {
+      const raw = await cdp.evaluate(expr, 10000);
+      const result = typeof raw === 'string' ? JSON.parse(raw) : raw;
+      this.json(res, 200, result);
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  private async handleScreenshot(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const ideType = url.searchParams.get('ideType') || undefined;
+    const cdp = this.getCdp(ideType);
+    if (!cdp) {
+      this.json(res, 503, { error: 'No CDP connection available' });
+      return;
+    }
+
+    try {
+      // Get viewport metrics before capturing
+      let vpW = 0, vpH = 0;
+      try {
+        const metrics = await cdp.send('Page.getLayoutMetrics', {}, 3000);
+        const vp = metrics?.cssVisualViewport || metrics?.visualViewport;
+        if (vp) {
+          vpW = Math.round(vp.clientWidth || vp.width || 0);
+          vpH = Math.round(vp.clientHeight || vp.height || 0);
+        }
+      } catch { /* ignore */ }
+
+      const buf = await cdp.captureScreenshot();
+      if (buf) {
+        res.writeHead(200, {
+          'Content-Type': 'image/webp',
+          'X-Viewport-Width': String(vpW),
+          'X-Viewport-Height': String(vpH),
+        });
+        res.end(buf);
+      } else {
+        this.json(res, 500, { error: 'Screenshot failed' });
+      }
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  private async handleScriptsRun(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { type, script: scriptName, params } = body;
+    if (!type || !scriptName) {
+      this.json(res, 400, { error: 'type and script required' });
+      return;
+    }
+    // Delegate to handleRunScript
+    await this.handleRunScript(type, req, res);
+  }
+
+  private async handleStatus(_req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const providers = this.providerLoader.getAll().map(p => ({
+      type: p.type, name: p.name, category: p.category,
+    }));
+
+    const cdpStatus: Record<string, { connected: boolean }> = {};
+    for (const [key, cdp] of this.cdpManagers.entries()) {
+      cdpStatus[key] = { connected: cdp.isConnected };
+    }
+
+    this.json(res, 200, {
+      devMode: true,
+      providers,
+      cdp: cdpStatus,
+      uptime: process.uptime(),
+    });
+  }
+
+  private async handleReload(_req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    try {
+      this.providerLoader.reload();
+      const providers = this.providerLoader.getAll().map(p => ({
+        type: p.type, name: p.name, category: p.category,
+      }));
+      this.json(res, 200, { reloaded: true, providers });
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  // ─── DevConsole SPA ───
+
+  private getConsoleDistDir(): string | null {
+    // Try to find web-devconsole/dist (Vite build output)
+    const candidates = [
+      path.resolve(__dirname, '../../web-devconsole/dist'),
+      path.resolve(__dirname, '../../../web-devconsole/dist'),
+      path.join(process.cwd(), 'packages/web-devconsole/dist'),
+    ];
+    for (const dir of candidates) {
+      if (fs.existsSync(path.join(dir, 'index.html'))) return dir;
+    }
+    return null;
+  }
+
+  private async serveConsole(_req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const distDir = this.getConsoleDistDir();
+    if (!distDir) {
+      this.json(res, 500, { error: 'DevConsole not found. Run: npm run build -w packages/web-devconsole' });
+      return;
+    }
+    const htmlPath = path.join(distDir, 'index.html');
+    try {
+      const html = fs.readFileSync(htmlPath, 'utf-8');
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(html);
+    } catch (e: any) {
+      this.json(res, 500, { error: `Cannot read index.html: ${e.message}` });
+    }
+  }
+
+  // ─── Static Assets ───
+
+  private static MIME_MAP: Record<string, string> = {
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+  };
+
+  private async serveStaticAsset(pathname: string, res: http.ServerResponse): Promise<void> {
+    const distDir = this.getConsoleDistDir();
+    if (!distDir) {
+      this.json(res, 404, { error: 'Not found' });
+      return;
+    }
+    // Prevent directory traversal
+    const safePath = path.normalize(pathname).replace(/^\.\.\//, '');
+    const filePath = path.join(distDir, safePath);
+    if (!filePath.startsWith(distDir)) {
+      this.json(res, 403, { error: 'Forbidden' });
+      return;
+    }
+    try {
+      const content = fs.readFileSync(filePath);
+      const ext = path.extname(filePath);
+      const contentType = DevServer.MIME_MAP[ext] || 'application/octet-stream';
+      res.writeHead(200, { 'Content-Type': contentType, 'Cache-Control': 'public, max-age=31536000, immutable' });
+      res.end(content);
+    } catch {
+      this.json(res, 404, { error: 'Not found' });
+    }
+  }
+
+  // ─── Watch Mode (SSE) ───
+
+  private handleSSE(_req: http.IncomingMessage, res: http.ServerResponse): void {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+    res.write('data: {"type":"connected"}\n\n');
+    this.sseClients.push(res);
+    _req.on('close', () => {
+      this.sseClients = this.sseClients.filter(c => c !== res);
+    });
+  }
+
+  private sendSSE(data: any): void {
+    const msg = `data: ${JSON.stringify(data)}\n\n`;
+    for (const client of this.sseClients) {
+      try { client.write(msg); } catch { /* ignore */ }
+    }
+  }
+
+  private async handleWatchStart(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { type, script: scriptName, interval = 2000 } = body;
+    if (!type) {
+      this.json(res, 400, { error: 'type required' });
+      return;
+    }
+
+    this.watchScriptPath = type;
+    this.watchScriptName = scriptName || 'readChat';
+
+    // Stop any existing watch
+    if (this.watchTimer) clearInterval(this.watchTimer);
+
+    this.log(`Watch started: ${type} → ${this.watchScriptName} (every ${interval}ms)`);
+    this.sendSSE({ type: 'watch_started', provider: type, script: this.watchScriptName });
+
+    const runWatch = async () => {
+      if (!this.watchScriptPath) return;
+      const provider = this.providerLoader.resolve(this.watchScriptPath);
+      if (!provider) {
+        this.sendSSE({ type: 'watch_error', error: `Provider '${this.watchScriptPath}' not found` });
+        return;
+      }
+      const fn = (provider.scripts as any)?.[this.watchScriptName!];
+      if (typeof fn !== 'function') {
+        this.sendSSE({ type: 'watch_error', error: `Script '${this.watchScriptName}' not found` });
+        return;
+      }
+      const cdp = this.getAnyCdp();
+      if (!cdp) {
+        this.sendSSE({ type: 'watch_error', error: 'No CDP connection' });
+        return;
+      }
+      try {
+        const script = fn();
+        const start = Date.now();
+        const raw = await cdp.evaluate(script, 15000);
+        const elapsed = Date.now() - start;
+        let result = raw;
+        if (typeof raw === 'string') {
+          try { result = JSON.parse(raw); } catch { /* keep */ }
+        }
+        this.sendSSE({ type: 'watch_result', provider: type, script: this.watchScriptName, result, elapsed });
+      } catch (e: any) {
+        this.sendSSE({ type: 'watch_error', error: e.message });
+      }
+    };
+
+    // Run immediately then on interval
+    runWatch();
+    this.watchTimer = setInterval(runWatch, Math.max(interval, 500));
+
+    this.json(res, 200, { watching: true, type, script: this.watchScriptName, interval });
+  }
+
+  private async handleWatchStop(_req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    if (this.watchTimer) {
+      clearInterval(this.watchTimer);
+      this.watchTimer = null;
+    }
+    this.watchScriptPath = null;
+    this.watchScriptName = null;
+    this.sendSSE({ type: 'watch_stopped' });
+    this.json(res, 200, { watching: false });
+  }
+
+  // ─── Provider File Explorer ───
+
+  /** Find the provider directory on disk */
+  private findProviderDir(type: string): string | null {
+    const provider = this.providerLoader.getMeta(type);
+    if (!provider) return null;
+    const cat = provider.category;
+    const builtinDir = (this.providerLoader as any).builtinDir || path.resolve(__dirname, '../providers/_builtin');
+    const userDir = path.join(os.homedir(), '.adhdev', 'providers');
+
+    // Direct match first
+    const directCandidates = [
+      path.join(userDir, type),
+      path.join(builtinDir, cat, type),
+      path.join(builtinDir, type),
+    ];
+    for (const d of directCandidates) {
+      if (fs.existsSync(path.join(d, 'provider.json'))) return d;
+    }
+
+    // Scan category dir for matching type field
+    const catDir = path.join(builtinDir, cat);
+    if (fs.existsSync(catDir)) {
+      try {
+        for (const entry of fs.readdirSync(catDir, { withFileTypes: true })) {
+          if (!entry.isDirectory()) continue;
+          const jsonPath = path.join(catDir, entry.name, 'provider.json');
+          if (fs.existsSync(jsonPath)) {
+            try {
+              const data = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+              if (data.type === type) return path.join(catDir, entry.name);
+            } catch { /* skip */ }
+          }
+        }
+      } catch { /* skip */ }
+    }
+    return null;
+  }
+
+  /** GET /api/providers/:type/files — list all files in provider directory */
+  private async handleListFiles(type: string, _req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const dir = this.findProviderDir(type);
+    if (!dir) { this.json(res, 404, { error: `Provider directory not found: ${type}` }); return; }
+
+    const files: { path: string; size: number; type: 'file' | 'dir' }[] = [];
+    const scan = (d: string, prefix: string) => {
+      try {
+        for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+          if (entry.name.startsWith('.') || entry.name.endsWith('.bak')) continue;
+          const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+          if (entry.isDirectory()) {
+            files.push({ path: rel, size: 0, type: 'dir' });
+            scan(path.join(d, entry.name), rel);
+          } else {
+            const stat = fs.statSync(path.join(d, entry.name));
+            files.push({ path: rel, size: stat.size, type: 'file' });
+          }
+        }
+      } catch { /* ignore */ }
+    };
+    scan(dir, '');
+    this.json(res, 200, { type, dir, files });
+  }
+
+  /** GET /api/providers/:type/file?path=scripts.js — read a file */
+  private async handleReadFile(type: string, req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const filePath = url.searchParams.get('path');
+    if (!filePath) { this.json(res, 400, { error: 'path query param required' }); return; }
+
+    const dir = this.findProviderDir(type);
+    if (!dir) { this.json(res, 404, { error: `Provider directory not found: ${type}` }); return; }
+
+    // Prevent directory traversal
+    const fullPath = path.resolve(dir, path.normalize(filePath));
+    if (!fullPath.startsWith(dir)) { this.json(res, 403, { error: 'Forbidden' }); return; }
+    if (!fs.existsSync(fullPath) || fs.statSync(fullPath).isDirectory()) {
+      this.json(res, 404, { error: `File not found: ${filePath}` }); return;
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf-8');
+    this.json(res, 200, { type, path: filePath, content, lines: content.split('\n').length });
+  }
+
+  /** POST /api/providers/:type/file — write a file { path, content } */
+  private async handleWriteFile(type: string, req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { path: filePath, content } = body;
+    if (!filePath || typeof content !== 'string') {
+      this.json(res, 400, { error: 'path and content required' }); return;
+    }
+
+    const dir = this.findProviderDir(type);
+    if (!dir) { this.json(res, 404, { error: `Provider directory not found: ${type}` }); return; }
+
+    const fullPath = path.resolve(dir, path.normalize(filePath));
+    if (!fullPath.startsWith(dir)) { this.json(res, 403, { error: 'Forbidden' }); return; }
+
+    try {
+      if (fs.existsSync(fullPath)) fs.copyFileSync(fullPath, fullPath + '.bak');
+      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+      fs.writeFileSync(fullPath, content, 'utf-8');
+      this.log(`File saved: ${fullPath} (${content.length} chars)`);
+      this.providerLoader.reload();
+      this.json(res, 200, { saved: true, path: filePath, chars: content.length });
+    } catch (e: any) {
+      this.json(res, 500, { error: `Save failed: ${e.message}` });
+    }
+  }
+
+  // ─── Legacy Source/Save compat ───
+
+  private async handleSource(type: string, _req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const dir = this.findProviderDir(type);
+    if (!dir) { this.json(res, 404, { error: `Provider not found: ${type}` }); return; }
+    for (const name of ['scripts.js', 'provider.json']) {
+      const p = path.join(dir, name);
+      if (fs.existsSync(p)) {
+        const source = fs.readFileSync(p, 'utf-8');
+        this.json(res, 200, { type, path: p, source, lines: source.split('\n').length });
+        return;
+      }
+    }
+    this.json(res, 404, { error: `Source file not found for '${type}'` });
+  }
+
+  private async handleSave(type: string, req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { source } = body;
+    if (!source || typeof source !== 'string') {
+      this.json(res, 400, { error: 'source (string) required' }); return;
+    }
+    const dir = this.findProviderDir(type);
+    if (!dir) { this.json(res, 404, { error: `Provider not found: ${type}` }); return; }
+    // Save to scripts.js if it exists, otherwise provider.json
+    const target = fs.existsSync(path.join(dir, 'scripts.js')) ? 'scripts.js' : 'provider.json';
+    const targetPath = path.join(dir, target);
+    try {
+      if (fs.existsSync(targetPath)) fs.copyFileSync(targetPath, targetPath + '.bak');
+      fs.writeFileSync(targetPath, source, 'utf-8');
+      this.log(`Saved provider: ${targetPath} (${source.length} chars)`);
+      this.providerLoader.reload();
+      this.json(res, 200, { saved: true, path: targetPath, chars: source.length });
+    } catch (e: any) {
+      this.json(res, 500, { error: `Save failed: ${e.message}` });
+    }
+  }
+
+  private async handleScriptHints(type: string, _req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const dir = this.findProviderDir(type);
+    if (!dir) { this.json(res, 404, { error: `Provider not found: ${type}` }); return; }
+
+    // Find scripts.js in the provider dir (may be versioned)
+    let scriptsPath = '';
+    const directScripts = path.join(dir, 'scripts.js');
+    if (fs.existsSync(directScripts)) {
+      scriptsPath = directScripts;
+    } else {
+      // Check versioned scripts dirs
+      const scriptsDir = path.join(dir, 'scripts');
+      if (fs.existsSync(scriptsDir)) {
+        const versions = fs.readdirSync(scriptsDir).filter(d => {
+          return fs.statSync(path.join(scriptsDir, d)).isDirectory();
+        }).sort().reverse();
+        for (const ver of versions) {
+          const p = path.join(scriptsDir, ver, 'scripts.js');
+          if (fs.existsSync(p)) { scriptsPath = p; break; }
+        }
+      }
+    }
+
+    if (!scriptsPath) {
+      this.json(res, 200, { hints: {} });
+      return;
+    }
+
+    try {
+      const source = fs.readFileSync(scriptsPath, 'utf-8');
+      const hints: Record<string, { template: Record<string, any>; description: string }> = {};
+
+      // Parse exported functions and extract param usage
+      const funcRegex = /module\.exports\.(\w+)\s*=\s*function\s+\w+\s*\(params\)/g;
+      let match;
+      while ((match = funcRegex.exec(source)) !== null) {
+        const name = match[1];
+        // Find the function body (rough: from match to next module.exports or end)
+        const startIdx = match.index;
+        const nextFunc = source.indexOf('module.exports.', startIdx + 1);
+        const funcBody = source.substring(startIdx, nextFunc > 0 ? nextFunc : source.length);
+
+        const paramFields: Record<string, any> = {};
+
+        // Pattern 1: params?.xxx or params.xxx
+        const dotRegex = /params\?\.([a-zA-Z_]+)|params\.([a-zA-Z_]+)/g;
+        let dm;
+        while ((dm = dotRegex.exec(funcBody)) !== null) {
+          const field = dm[1] || dm[2];
+          if (field === 'length') continue;
+          if (!(field in paramFields)) {
+            // Infer type from context
+            if (/index|count|port|timeout/i.test(field)) paramFields[field] = 0;
+            else if (/action|text|title|message|model|mode|button|name|filter/i.test(field)) paramFields[field] = '';
+            else paramFields[field] = '';
+          }
+        }
+
+        // Pattern 2: typeof params === 'string' ? params : params?.xxx
+        const typeofRegex = /typeof params === 'string' \? params : params\?\.([a-zA-Z_]+)/g;
+        let tm;
+        while ((tm = typeofRegex.exec(funcBody)) !== null) {
+          const field = tm[1];
+          if (!(field in paramFields)) paramFields[field] = '';
+        }
+
+        // Pattern 3: typeof params === 'number' ? params : params?.xxx
+        const numRegex = /typeof params === 'number' \? params : params\?\.([a-zA-Z_]+)/g;
+        let nm;
+        while ((nm = numRegex.exec(funcBody)) !== null) {
+          const field = nm[1];
+          if (!(field in paramFields)) paramFields[field] = 0;
+        }
+
+        // Determine description from function name
+        const descriptions: Record<string, string> = {
+          readChat: 'No params required',
+          sendMessage: 'Text to send to the chat',
+          listSessions: 'No params required',
+          switchSession: 'Switch by index or title',
+          newSession: 'No params required',
+          focusEditor: 'No params required',
+          openPanel: 'No params required',
+          resolveAction: 'Approve/reject action buttons',
+          listNotifications: 'Optional message filter',
+          dismissNotification: 'Dismiss by index, message, or button',
+          listModels: 'No params required',
+          setModel: 'Model name to select',
+          listModes: 'No params required',
+          setMode: 'Mode name to select',
+        };
+
+        hints[name] = {
+          template: Object.keys(paramFields).length > 0 ? paramFields : {},
+          description: descriptions[name] || (Object.keys(paramFields).length > 0 ? 'Params: ' + Object.keys(paramFields).join(', ') : 'No params'),
+        };
+      }
+
+      this.json(res, 200, { hints });
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  // ─── Validate provider.json ───
+  private async handleValidate(type: string, req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { content } = body;
+    const errors: string[] = [];
+    const warnings: string[] = [];
+    try {
+      const config = typeof content === 'string' ? JSON.parse(content) : content;
+      // Required fields
+      if (!config.type) errors.push('Missing required field: type');
+      if (!config.name) errors.push('Missing required field: name');
+      if (!config.category) errors.push('Missing required field: category');
+      else if (!['ide', 'extension', 'cli', 'acp'].includes(config.category)) errors.push(`Invalid category: ${config.category}`);
+      // Category-specific
+      if (config.category === 'ide' || config.category === 'extension') {
+        if (!config.cdpPorts || !Array.isArray(config.cdpPorts) || config.cdpPorts.length === 0)
+          warnings.push('IDE/Extension providers should have cdpPorts');
+        if (config.category === 'extension' && !config.extensionId)
+          warnings.push('Extension providers should have extensionId');
+      }
+      if (config.category === 'acp' || config.category === 'cli') {
+        if (!config.spawn) errors.push('ACP/CLI providers must have spawn config');
+        else {
+          if (!config.spawn.command) errors.push('spawn.command is required');
+        }
+      }
+      // Settings validation
+      if (config.settings) {
+        for (const [key, val] of Object.entries(config.settings)) {
+          const s = val as any;
+          if (!s.type) errors.push(`settings.${key}: missing type`);
+          else if (!['boolean', 'number', 'string', 'select'].includes(s.type))
+            errors.push(`settings.${key}: invalid type '${s.type}'`);
+          if (s.default === undefined) warnings.push(`settings.${key}: no default value`);
+          if (s.type === 'number' && s.min !== undefined && s.max !== undefined && s.min > s.max)
+            errors.push(`settings.${key}: min (${s.min}) > max (${s.max})`);
+          if (s.type === 'select' && (!s.options || !Array.isArray(s.options) || s.options.length === 0))
+            errors.push(`settings.${key}: select type requires options[]`);
+        }
+      }
+      // Port conflicts
+      if (config.cdpPorts && Array.isArray(config.cdpPorts)) {
+        const allProviders = this.providerLoader.getAll();
+        for (const port of config.cdpPorts) {
+          const conflict = allProviders.find(p => p.type !== type && (p as any).cdpPorts?.includes(port));
+          if (conflict) warnings.push(`CDP port ${port} conflicts with provider '${conflict.type}'`);
+        }
+      }
+      this.json(res, 200, { valid: errors.length === 0, errors, warnings });
+    } catch (e: any) {
+      this.json(res, 200, { valid: false, errors: [`Invalid JSON: ${e.message}`], warnings: [] });
+    }
+  }
+
+  // ─── ACP Chat Test ───
+  private async handleAcpChat(type: string, req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { message, timeout = 30000 } = body;
+    if (!message) { this.json(res, 400, { error: 'message required' }); return; }
+    const provider = this.providerLoader.getMeta(type);
+    if (!provider) { this.json(res, 404, { error: `Provider not found: ${type}` }); return; }
+    const spawn = (provider as any).spawn;
+    if (!spawn) { this.json(res, 400, { error: `Provider ${type} has no spawn config` }); return; }
+
+    const { spawn: spawnFn } = await import('child_process');
+    const start = Date.now();
+    try {
+      const args = [...(spawn.args || []), message];
+      const child = spawnFn(spawn.command, args, {
+        shell: spawn.shell ?? false,
+        timeout: timeout,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, ...(spawn.env || {}) },
+      });
+
+      let stdout = '';
+      let stderr = '';
+      child.stdout?.on('data', (d: Buffer) => { stdout += d.toString(); });
+      child.stderr?.on('data', (d: Buffer) => { stderr += d.toString(); });
+
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(() => { child.kill(); resolve(); }, timeout);
+        child.on('exit', () => { clearTimeout(timer); resolve(); });
+      });
+
+      const elapsed = Date.now() - start;
+      this.json(res, 200, {
+        success: true,
+        message,
+        response: stdout.trim(),
+        stderr: stderr.trim(),
+        exitCode: child.exitCode,
+        elapsed,
+      });
+    } catch (e: any) {
+      this.json(res, 200, {
+        success: false,
+        message,
+        error: e.message,
+        elapsed: Date.now() - start,
+      });
+    }
+  }
+
+
+  private async handleCdpTargets(_req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const targets: { ide: string; connected: boolean; port: number }[] = [];
+    for (const [ide, cdp] of this.cdpManagers.entries()) {
+      targets.push({ ide, connected: cdp.isConnected, port: cdp.getPort() });
+    }
+    this.json(res, 200, { targets });
+  }
+
+  // ─── Scaffold ───
+
+  private async handleScaffold(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { type, name, category = 'ide', location = 'user',
+      cdpPorts, cli, processName, installPath, binary, extensionId, version } = body;
+    if (!type || !name) {
+      this.json(res, 400, { error: 'type and name required' });
+      return;
+    }
+
+    let targetDir: string;
+    if (location === 'user') {
+      targetDir = path.join(os.homedir(), '.adhdev', 'providers', type);
+    } else {
+      const builtinDir = path.resolve(__dirname, '../providers/_builtin');
+      targetDir = path.join(builtinDir, category, type);
+    }
+
+    const jsonPath = path.join(targetDir, 'provider.json');
+    if (fs.existsSync(jsonPath)) {
+      this.json(res, 409, { error: `Provider already exists at ${targetDir}`, path: targetDir });
+      return;
+    }
+
+    try {
+      const result = genScaffoldFiles(type, name, category, { cdpPorts, cli, processName, installPath, binary, extensionId, version });
+      fs.mkdirSync(targetDir, { recursive: true });
+      fs.writeFileSync(jsonPath, result['provider.json'], 'utf-8');
+      const createdFiles = ['provider.json'];
+
+      // Write per-function script files (new structure)
+      if (result.files) {
+        for (const [relPath, content] of Object.entries(result.files)) {
+          const fullPath = path.join(targetDir, relPath);
+          fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+          fs.writeFileSync(fullPath, content, 'utf-8');
+          createdFiles.push(relPath);
+        }
+      }
+
+      this.log(`Scaffolded provider: ${targetDir} (${createdFiles.length} files)`);
+      this.json(res, 201, { created: true, path: targetDir, files: createdFiles, type, name, category });
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  // ─── Version Detection ───
+
+  private async handleDetectVersions(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    try {
+      const archive = new VersionArchive();
+      const results = await detectAllVersions(this.providerLoader, archive);
+      const installed = results.filter(r => r.installed);
+      const notInstalled = results.filter(r => !r.installed);
+      this.json(res, 200, {
+        total: results.length,
+        installed: installed.length,
+        providers: results,
+        history: archive.getAll(),
+      });
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  // ─── DOM Inspector ───
+
+  private async handleDomInspect(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { x, y, selector, ideType } = body;
+    const cdp = this.getCdp(ideType);
+    if (!cdp) { this.json(res, 503, { error: 'No CDP connection' }); return; }
+
+    const selectorArg = selector ? JSON.stringify(selector) : 'null';
+    const inspectScript = `(() => {
+      function gs(el) {
+        if (!el || el === document.body) return 'body';
+        if (el.id) return '#' + CSS.escape(el.id);
+        let s = el.tagName.toLowerCase();
+        if (el.className && typeof el.className === 'string') {
+          const cls = el.className.trim().split(/\\s+/).filter(c => c && !c.startsWith('_')).slice(0, 3);
+          if (cls.length) s += '.' + cls.map(c => CSS.escape(c)).join('.');
+        }
+        const p = el.parentElement;
+        if (p) {
+          const sibs = [...p.children].filter(c => c.tagName === el.tagName);
+          if (sibs.length > 1) s += ':nth-child(' + ([...p.children].indexOf(el) + 1) + ')';
+        }
+        return s;
+      }
+      function gp(el) {
+        const parts = [];
+        let c = el;
+        while (c && c !== document.documentElement) { parts.unshift(gs(c)); c = c.parentElement; }
+        return parts;
+      }
+      function ni(el) {
+        if (!el) return null;
+        const tag = el.tagName?.toLowerCase() || '#text';
+        const attrs = {};
+        if (el.attributes) for (const a of el.attributes) if (a.name !== 'class' && a.name !== 'style') attrs[a.name] = a.value?.substring(0, 200);
+        const cls = (el.className && typeof el.className === 'string') ? el.className.trim().split(/\\s+/).filter(Boolean).slice(0, 10) : [];
+        const text = el.textContent?.trim().substring(0, 150) || '';
+        const dt = [...(el.childNodes||[])].filter(n=>n.nodeType===3).map(n=>n.textContent.trim()).filter(Boolean).join(' ').substring(0,100);
+        const cc = el.children?.length || 0;
+        const r = el.getBoundingClientRect?.();
+        return { tag, cls, attrs, text, directText: dt, childCount: cc, selector: gs(el), fullSelector: gp(el).join(' > '), rect: r ? {x:Math.round(r.x),y:Math.round(r.y),w:Math.round(r.width),h:Math.round(r.height)} : null };
+      }
+      const sel = ${selectorArg};
+      let el = sel ? document.querySelector(sel) : document.elementFromPoint(${x || 0}, ${y || 0});
+      if (!el) return JSON.stringify({ error: 'No element found' });
+      const info = ni(el);
+      const ancestors = [];
+      let pp = el.parentElement;
+      while (pp && pp !== document.documentElement) {
+        ancestors.push({ tag: pp.tagName.toLowerCase(), selector: gs(pp), cls: (pp.className && typeof pp.className === 'string') ? pp.className.trim().split(/\\s+/).slice(0,3) : [] });
+        pp = pp.parentElement;
+      }
+      const children = [...(el.children||[])].slice(0,50).map(c => ni(c));
+      return JSON.stringify({ element: info, ancestors: ancestors.reverse(), children });
+    })()`;
+
+    try {
+      const raw = await cdp.evaluate(inspectScript, 10000);
+      let result = raw;
+      if (typeof raw === 'string') { try { result = JSON.parse(raw as string); } catch { } }
+      this.json(res, 200, result as Record<string, unknown>);
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  private async handleDomChildren(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { selector, ideType } = body;
+    const cdp = this.getCdp(ideType);
+    if (!cdp) { this.json(res, 503, { error: 'No CDP connection' }); return; }
+    if (!selector) { this.json(res, 400, { error: 'selector required' }); return; }
+
+    const script = `(() => {
+      function gs(el) {
+        if (!el || el === document.body) return 'body';
+        if (el.id) return '#' + CSS.escape(el.id);
+        let s = el.tagName.toLowerCase();
+        if (el.className && typeof el.className === 'string') {
+          const cls = el.className.trim().split(/\\s+/).filter(c => c && !c.startsWith('_')).slice(0, 3);
+          if (cls.length) s += '.' + cls.map(c => CSS.escape(c)).join('.');
+        }
+        const p = el.parentElement;
+        if (p) {
+          const sibs = [...p.children].filter(c => c.tagName === el.tagName);
+          if (sibs.length > 1) s += ':nth-child(' + ([...p.children].indexOf(el) + 1) + ')';
+        }
+        return s;
+      }
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return JSON.stringify({ error: 'Element not found' });
+      const children = [...(el.children||[])].slice(0,100).map(c => {
+        const tag = c.tagName?.toLowerCase();
+        const cls = (c.className && typeof c.className === 'string') ? c.className.trim().split(/\\s+/).filter(Boolean).slice(0,10) : [];
+        const attrs = {};
+        for (const a of c.attributes) if (a.name!=='class'&&a.name!=='style') attrs[a.name] = a.value?.substring(0,200);
+        const text = c.textContent?.trim().substring(0,150)||'';
+        const dt = [...c.childNodes].filter(n=>n.nodeType===3).map(n=>n.textContent.trim()).filter(Boolean).join(' ').substring(0,100);
+        return { tag, cls, attrs, text, directText: dt, childCount: c.children?.length||0, selector: gs(c) };
+      });
+      return JSON.stringify({ selector: ${JSON.stringify(selector)}, childCount: el.children?.length||0, children });
+    })()`;
+
+    try {
+      const raw = await cdp.evaluate(script, 10000);
+      let result = raw;
+      if (typeof raw === 'string') { try { result = JSON.parse(raw as string); } catch { } }
+      this.json(res, 200, result as Record<string, unknown>);
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  private async handleDomAnalyze(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { ideType, selector, x, y } = body;
+    const cdp = this.getCdp(ideType);
+    if (!cdp) { this.json(res, 503, { error: 'No CDP connection' }); return; }
+
+    const selectorArg = selector ? JSON.stringify(selector) : 'null';
+    const analyzeScript = `(() => {
+      function gs(el) {
+        if (!el || el === document.body) return 'body';
+        if (el.id) return '#' + CSS.escape(el.id);
+        let s = el.tagName.toLowerCase();
+        if (el.className && typeof el.className === 'string') {
+          const cls = el.className.trim().split(/\\s+/).filter(c => c && !c.startsWith('_')).slice(0, 3);
+          if (cls.length) s += '.' + cls.map(c => CSS.escape(c)).join('.');
+        }
+        return s;
+      }
+      function fp(el) {
+        const parts = [];
+        let c = el;
+        while (c && c !== document.documentElement) { parts.unshift(gs(c)); c = c.parentElement; }
+        return parts.join(' > ');
+      }
+      function sigOf(el) {
+        return el.tagName + '|' + ((el.className && typeof el.className === 'string') ? el.className.trim().split(/\\s+/).filter(c => c && !c.startsWith('_')).sort().join('.') : '');
+      }
+
+      // Find target element
+      const sel = ${selectorArg};
+      let target = sel ? document.querySelector(sel) : document.elementFromPoint(${x || 0}, ${y || 0});
+      if (!target) return JSON.stringify({ error: 'Element not found' });
+
+      const result = {
+        target: { tag: target.tagName.toLowerCase(), selector: fp(target), text: (target.textContent||'').trim().substring(0, 200) },
+        siblingPattern: null,
+        ancestorAnalysis: [],
+        subtreeTexts: [],
+      };
+
+      // 1. Walk UP parents — at each level, find sibling patterns
+      let el = target;
+      let depth = 0;
+      while (el && el !== document.body && depth < 15) {
+        const parent = el.parentElement;
+        if (!parent) break;
+
+        const mySig = sigOf(el);
+        const siblings = [...parent.children].filter(c => sigOf(c) === mySig);
+        const totalChildren = parent.children.length;
+        const childSel = gs(el).replace(/:nth-child\\(\\d+\\)/, '');
+        const parentSel = fp(parent);
+
+        result.ancestorAnalysis.push({
+          depth,
+          parentTag: parent.tagName.toLowerCase(),
+          parentSelector: parentSel,
+          totalChildren,
+          matchingSiblings: siblings.length,
+          childSelector: childSel,
+          fullSelector: parentSel + ' > ' + childSel,
+        });
+
+        // Best sibling pattern: 3+ matching siblings with text
+        if (!result.siblingPattern && siblings.length >= 3) {
+          const siblingData = siblings.map((s, i) => {
+            const directText = [...s.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent.trim()).filter(Boolean).join(' ').substring(0, 120);
+            const allText = (s.textContent || '').trim().substring(0, 200);
+            const childCount = s.children?.length || 0;
+            const cls = (s.className && typeof s.className === 'string') ? s.className.trim().split(/\\s+/).filter(Boolean) : [];
+            const attrs = {};
+            if (s.attributes) for (const a of s.attributes) {
+              if (a.name !== 'class' && a.name !== 'style' && a.value) attrs[a.name] = a.value.substring(0, 100);
+            }
+            return { index: i, directText, allText, childCount, cls, attrs, tag: s.tagName.toLowerCase() };
+          });
+
+          // Find common attributes across siblings
+          const allAttrs = siblingData.map(s => Object.keys(s.attrs));
+          const commonAttrs = allAttrs[0]?.filter(attr => allAttrs.every(a => a.includes(attr))) || [];
+          // Find varying attributes (data-*, role, etc)
+          const varyingAttrs = {};
+          for (const attr of commonAttrs) {
+            const values = siblingData.map(s => s.attrs[attr]);
+            const unique = [...new Set(values)];
+            if (unique.length > 1) varyingAttrs[attr] = unique.slice(0, 5);
+          }
+
+          result.siblingPattern = {
+            count: siblings.length,
+            selector: parentSel + ' > ' + childSel,
+            parentSelector: parentSel,
+            depthFromTarget: depth,
+            siblings: siblingData.slice(0, 30),
+            commonAttrs,
+            varyingAttrs,
+          };
+        }
+
+        el = parent;
+        depth++;
+      }
+
+      // 2. Collect subtree text nodes from target
+      const walker = document.createTreeWalker(target, NodeFilter.SHOW_TEXT, null);
+      let node;
+      while ((node = walker.nextNode()) && result.subtreeTexts.length < 30) {
+        const text = node.textContent.trim();
+        if (text.length > 2) {
+          const parentTag = node.parentElement?.tagName?.toLowerCase() || '';
+          const parentCls = (node.parentElement?.className && typeof node.parentElement.className === 'string')
+            ? node.parentElement.className.trim().split(/\\s+/).filter(Boolean).slice(0,3).join('.') : '';
+          result.subtreeTexts.push({
+            text: text.substring(0, 150),
+            parentTag,
+            parentCls,
+            parentSelector: gs(node.parentElement),
+          });
+        }
+      }
+
+      return JSON.stringify(result);
+    })()`;
+
+    try {
+      const raw = await cdp.evaluate(analyzeScript, 15000);
+      let result = raw;
+      if (typeof raw === 'string') { try { result = JSON.parse(raw as string); } catch { } }
+      this.json(res, 200, result as Record<string, unknown>);
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  private async handleFindCommon(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { include, exclude, ideType } = body;
+    if (!Array.isArray(include) || include.length === 0) { this.json(res, 400, { error: 'include[] is required' }); return; }
+    const cdp = this.getCdp(ideType);
+    if (!cdp) { this.json(res, 503, { error: 'No CDP connection' }); return; }
+
+    const script = `(() => {
+      const includes = ${JSON.stringify(include)};
+      const excludes = ${JSON.stringify(exclude || [])};
+
+      function gs(el) {
+        if (!el || el === document.body) return 'body';
+        if (el.id) return '#' + CSS.escape(el.id);
+        let s = el.tagName.toLowerCase();
+        if (el.className && typeof el.className === 'string') {
+          const cls = el.className.trim().split(/\\s+/).filter(c => c && !c.startsWith('_')).slice(0, 3);
+          if (cls.length) s += '.' + cls.map(c => CSS.escape(c)).join('.');
+        }
+        return s;
+      }
+      function fp(el) {
+        const parts = [];
+        let c = el;
+        while (c && c !== document.documentElement) { parts.unshift(gs(c)); c = c.parentElement; }
+        return parts.join(' > ');
+      }
+      function sig(el) {
+        return el.tagName + '|' + ((el.className && typeof el.className === 'string') ? el.className.trim() : '');
+      }
+
+      // Step 1: For each include, find all matching leaf elements
+      const includeMatches = includes.map(text => {
+        const lower = text.toLowerCase();
+        const found = [];
+        const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, {
+          acceptNode: n => n.textContent.toLowerCase().includes(lower) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT
+        });
+        let node;
+        while ((node = walker.nextNode()) && found.length < 5) {
+          if (node.parentElement) found.push(node.parentElement);
+        }
+        return found;
+      });
+
+      if (includeMatches.some(m => m.length === 0)) {
+        const missing = includes.filter((_, i) => includeMatches[i].length === 0);
+        return JSON.stringify({ results: [], message: 'Text not found: ' + missing.join(', ') });
+      }
+
+      // Step 2: Find LCA for each combination of include elements
+      // For each pair of include[0] element and include[1] element, find their LCA
+      // Then within the LCA, find the direct-child subtree branch for each
+      const containers = [];
+      const seen = new Set();
+
+      function findLCA(el1, el2) {
+        const ancestors1 = new Set();
+        let c = el1;
+        while (c) { ancestors1.add(c); c = c.parentElement; }
+        c = el2;
+        while (c) { if (ancestors1.has(c)) return c; c = c.parentElement; }
+        return document.body;
+      }
+
+      function findDirectChildContaining(parent, descendant) {
+        let c = descendant;
+        while (c && c.parentElement !== parent) c = c.parentElement;
+        return c;
+      }
+
+      // Try all combinations (first 3 matches per include)
+      for (const el1 of includeMatches[0].slice(0, 3)) {
+        for (let ii = 1; ii < includeMatches.length; ii++) {
+          for (const el2 of includeMatches[ii].slice(0, 3)) {
+            if (el1 === el2) continue;
+            const lca = findLCA(el1, el2);
+            if (!lca || lca === document.body || lca === document.documentElement) continue;
+
+            // Find which direct child of LCA contains each include element
+            const child1 = findDirectChildContaining(lca, el1);
+            const child2 = findDirectChildContaining(lca, el2);
+            if (!child1 || !child2 || child1 === child2) continue;
+
+            const lcaSel = fp(lca);
+            if (seen.has(lcaSel)) continue;
+            seen.add(lcaSel);
+
+            // Check exclude
+            if (excludes.length > 0) {
+              const lcaText = (lca.textContent || '').toLowerCase();
+              if (excludes.some(ex => lcaText.includes(ex.toLowerCase()))) continue;
+            }
+
+            // Are child1 and child2 same tag? (relaxed — ignore classes)
+            const tag1 = child1.tagName;
+            const tag2 = child2.tagName;
+
+            // Bubble up: walk up from LCA, find the best list container
+            // (the one with most repeating same-tag children)
+            let container = lca;
+            let bestContainer = lca;
+            let bestListCount = 0;
+            for (let up = 0; up < 10; up++) {
+              const p = container.parentElement;
+              if (!p || p === document.body || p === document.documentElement) break;
+              // Check how many same-tag siblings 'container' has in parent
+              const myTag = container.tagName;
+              const sibCount = [...p.children].filter(c => c.tagName === myTag).length;
+              if (sibCount > bestListCount) {
+                bestListCount = sibCount;
+                bestContainer = p;
+              }
+              container = p;
+            }
+            container = bestListCount >= 3 ? bestContainer : lca;
+
+            const allChildren = [...container.children];
+            const childTag = tag1 === tag2 ? tag1 : (allChildren.length > 0 ? allChildren[0].tagName : '');
+            const sameTagCount = allChildren.filter(c => c.tagName === childTag).length;
+            const isList = sameTagCount >= 3 && sameTagCount >= allChildren.length * 0.4;
+
+            // Gather all same-tag children as list items
+            const listItems = isList 
+              ? allChildren.filter(c => c.tagName === childTag)
+              : allChildren;
+
+            // Filter rendered items (skip virtual scroll placeholders)
+            const rendered = listItems.filter(c => (c.innerText || '').trim().length > 0);
+            const placeholderCount = listItems.length - rendered.length;
+
+            const containerSel = fp(container);
+            if (seen.has(containerSel)) continue;
+            seen.add(containerSel);
+
+            const r = container.getBoundingClientRect();
+            containers.push({
+              selector: containerSel,
+              tag: container.tagName.toLowerCase(),
+              childCount: allChildren.length,
+              listItemCount: listItems.length,
+              renderedCount: rendered.length,
+              placeholderCount,
+              isList,
+              rect: { w: Math.round(r.width), h: Math.round(r.height) },
+              depth: containerSel.split(' > ').length,
+              items: rendered.slice(0, 30).map((el, i) => {
+                const fullText = (el.innerText || el.textContent || '').trim();
+                // Find snippet around first matched include text
+                let text = fullText.substring(0, 200);
+                const matched = [];
+                for (const inc of includes) {
+                  const idx = fullText.toLowerCase().indexOf(inc.toLowerCase());
+                  if (idx >= 0) {
+                    matched.push(inc);
+                    if (matched.length === 1) {
+                      // Show snippet around first match
+                      const start = Math.max(0, idx - 30);
+                      const end = Math.min(fullText.length, idx + inc.length + 80);
+                      text = (start > 0 ? '...' : '') + fullText.substring(start, end) + (end < fullText.length ? '...' : '');
+                    }
+                  }
+                }
+                return {
+                  index: i,
+                  tag: el.tagName.toLowerCase(),
+                  cls: (el.className && typeof el.className === 'string') ? el.className.trim().split(/\\s+/).slice(0, 2).join(' ') : '',
+                  text,
+                  matchedIncludes: matched,
+                  childCount: el.children.length,
+                  h: Math.round(el.getBoundingClientRect().height),
+                };
+              }),
+            });
+          }
+        }
+      }
+
+      // Sort: list containers first (more items = better), then by depth
+      containers.sort((a, b) => {
+        if (a.isList !== b.isList) return a.isList ? -1 : 1;
+        return b.listItemCount - a.listItemCount || b.depth - a.depth;
+      });
+
+      return JSON.stringify({
+        results: containers.slice(0, 10),
+        includeCount: includes.length,
+        excludeCount: excludes.length,
+      });
+    })()`;
+
+    try {
+      const raw = await cdp.evaluate(script, 10000);
+      let result = raw;
+      if (typeof raw === 'string') { try { result = JSON.parse(raw as string); } catch { } }
+      this.json(res, 200, result as Record<string, unknown>);
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  private async handleFindByText(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { text, ideType, containerSelector } = body;
+    if (!text || typeof text !== 'string') { this.json(res, 400, { error: 'text is required' }); return; }
+    const cdp = this.getCdp(ideType);
+    if (!cdp) { this.json(res, 503, { error: 'No CDP connection' }); return; }
+
+    const containerArg = containerSelector ? JSON.stringify(containerSelector) : 'null';
+    const script = `(() => {
+      function gs(el) {
+        if (!el || el === document.body) return 'body';
+        if (el.id) return '#' + CSS.escape(el.id);
+        let s = el.tagName.toLowerCase();
+        if (el.className && typeof el.className === 'string') {
+          const cls = el.className.trim().split(/\\s+/).filter(c => c && !c.startsWith('_')).slice(0, 3);
+          if (cls.length) s += '.' + cls.map(c => CSS.escape(c)).join('.');
+        }
+        return s;
+      }
+      function fp(el) {
+        const parts = [];
+        let c = el;
+        while (c && c !== document.documentElement) { parts.unshift(gs(c)); c = c.parentElement; }
+        return parts.join(' > ');
+      }
+      function parentSig(el) {
+        // Signature: tag+class chain up 3 levels
+        const parts = [];
+        let c = el;
+        for (let i = 0; i < 3 && c; i++) { parts.push(gs(c)); c = c.parentElement; }
+        return parts.join(' < ');
+      }
+
+      const searchText = ${JSON.stringify(text)}.toLowerCase();
+      const container = ${containerArg} ? document.querySelector(${containerArg}) : document.body;
+      if (!container) return JSON.stringify({ error: 'Container not found' });
+
+      const matches = [];
+      const seen = new Set();
+
+      // Find all text nodes containing the search text
+      const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT, {
+        acceptNode: n => n.textContent.toLowerCase().includes(searchText) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT
+      });
+      let node;
+      while ((node = walker.nextNode()) && matches.length < 50) {
+        // Walk up to find the most specific visible element
+        let el = node.parentElement;
+        if (!el) continue;
+
+        // Skip hidden elements
+        const r = el.getBoundingClientRect();
+        if (r.width === 0 && r.height === 0) continue;
+
+        const selector = fp(el);
+        if (seen.has(selector)) continue;
+        seen.add(selector);
+
+        // Walk up parent chain — record each level's selector + sibling count
+        const ancestors = [];
+        let cur = el;
+        let pLvl = cur.parentElement;
+        for (let lvl = 0; lvl < 10 && pLvl && pLvl !== document.body; lvl++) {
+          const mySig = cur.tagName + '|' + ((cur.className && typeof cur.className === 'string') ? cur.className.trim().split(/\\s+/).sort().join('.') : '');
+          const sibs = [...pLvl.children].filter(c => {
+            const sig = c.tagName + '|' + ((c.className && typeof c.className === 'string') ? c.className.trim().split(/\\s+/).sort().join('.') : '');
+            return sig === mySig;
+          });
+          const childSel = gs(cur).replace(/:nth-child\\(\\d+\\)/, '');
+          ancestors.push({
+            parentSelector: fp(pLvl),
+            childSelector: childSel,
+            fullSelector: fp(pLvl) + ' > ' + childSel,
+            siblingCount: sibs.length,
+            parentTag: pLvl.tagName.toLowerCase(),
+          });
+          cur = pLvl;
+          pLvl = pLvl.parentElement;
+        }
+
+        const directText = (node.textContent || '').trim().substring(0, 200);
+        const allText = (node.parentElement.textContent || '').trim().substring(0, 300);
+        const tag = node.parentElement.tagName.toLowerCase();
+        const cls = (node.parentElement.className && typeof node.parentElement.className === 'string')
+          ? node.parentElement.className.trim().split(/\\s+/).filter(Boolean) : [];
+
+        matches.push({
+          selector,
+          tag,
+          cls,
+          directText,
+          allText,
+          ancestors,
+          rect: { w: Math.round(r.width), h: Math.round(r.height) },
+          depth: selector.split(' > ').length,
+        });
+      }
+
+      // Sort: prefer elements with more siblings in ancestry, then fewer depth
+      matches.sort((a, b) => {
+        const aMax = Math.max(1, ...a.ancestors.map(x => x.siblingCount));
+        const bMax = Math.max(1, ...b.ancestors.map(x => x.siblingCount));
+        return (bMax - aMax) || (a.depth - b.depth);
+      });
+
+      return JSON.stringify({ query: ${JSON.stringify(text)}, matches, total: matches.length });
+    })()`;
+
+    try {
+      const raw = await cdp.evaluate(script, 10000);
+      let result = raw;
+      if (typeof raw === 'string') { try { result = JSON.parse(raw as string); } catch { } }
+      this.json(res, 200, result as Record<string, unknown>);
+    } catch (e: any) {
+      this.json(res, 500, { error: e.message });
+    }
+  }
+
+  // ─── Phase 1: DOM Context API ───
+
+  private async handleDomContext(type: string, req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { ideType } = body;
+    const provider = this.providerLoader.resolve(type);
+    if (!provider) { this.json(res, 404, { error: `Provider not found: ${type}` }); return; }
+
+    const cdp = this.getCdp(ideType || type);
+    if (!cdp) { this.json(res, 503, { error: 'No CDP connection available. Target IDE must be running with CDP enabled.' }); return; }
+
+    try {
+      // 1. Capture screenshot
+      let screenshot: string | null = null;
+      try {
+        const buf = await cdp.captureScreenshot();
+        if (buf) screenshot = buf.toString('base64');
+      } catch { /* screenshot optional */ }
+
+      // 2. Collect DOM snapshot
+      const domScript = `(() => {
+        function gs(el) {
+          if (!el || el === document.body) return 'body';
+          if (el.id) return '#' + CSS.escape(el.id);
+          let s = el.tagName.toLowerCase();
+          if (el.className && typeof el.className === 'string') {
+            const cls = el.className.trim().split(/\\s+/).filter(c => c && !c.startsWith('_')).slice(0, 3);
+            if (cls.length) s += '.' + cls.map(c => CSS.escape(c)).join('.');
+          }
+          return s;
+        }
+        function fp(el) {
+          const parts = [];
+          let c = el;
+          while (c && c !== document.documentElement) { parts.unshift(gs(c)); c = c.parentElement; }
+          return parts.join(' > ');
+        }
+        function rect(el) {
+          try { const r = el.getBoundingClientRect(); return { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) }; }
+          catch { return null; }
+        }
+
+        const result = { contentEditables: [], chatContainers: [], buttons: [], sidebars: [], dropdowns: [], inputs: [] };
+
+        // Content editables + textareas + inputs
+        document.querySelectorAll('[contenteditable], textarea, input[type="text"], input:not([type])').forEach(el => {
+          if (el.offsetWidth === 0 && el.offsetHeight === 0) return;
+          result.contentEditables.push({
+            selector: fp(el),
+            tag: el.tagName.toLowerCase(),
+            contenteditable: el.getAttribute('contenteditable'),
+            role: el.getAttribute('role'),
+            ariaLabel: el.getAttribute('aria-label'),
+            placeholder: el.getAttribute('placeholder'),
+            rect: rect(el),
+            visible: el.offsetParent !== null || el.offsetWidth > 0,
+          });
+        });
+
+        // Chat containers — large divs with scroll
+        document.querySelectorAll('div, section, main').forEach(el => {
+          const style = getComputedStyle(el);
+          const isScrollable = style.overflowY === 'auto' || style.overflowY === 'scroll';
+          const r = el.getBoundingClientRect();
+          if (!isScrollable || r.height < 200 || r.width < 200) return;
+          const childCount = el.children.length;
+          if (childCount < 2) return;
+          result.chatContainers.push({
+            selector: fp(el),
+            childCount,
+            rect: { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) },
+            hasScrollable: true,
+            scrollTop: Math.round(el.scrollTop),
+            scrollHeight: Math.round(el.scrollHeight),
+          });
+        });
+
+        // Buttons
+        document.querySelectorAll('button, [role="button"]').forEach(el => {
+          if (el.offsetWidth === 0 && el.offsetHeight === 0) return;
+          const text = (el.textContent || '').trim().substring(0, 80);
+          if (!text && !el.getAttribute('aria-label')) return;
+          result.buttons.push({
+            text,
+            ariaLabel: el.getAttribute('aria-label'),
+            selector: fp(el),
+            rect: rect(el),
+            disabled: el.disabled || el.getAttribute('aria-disabled') === 'true',
+          });
+        });
+
+        // Sidebars — panels on left/right edges
+        document.querySelectorAll('[class*="sidebar"], [class*="side-bar"], [class*="panel"], [role="complementary"], [role="navigation"], aside').forEach(el => {
+          if (el.offsetWidth === 0 && el.offsetHeight === 0) return;
+          const r = el.getBoundingClientRect();
+          if (r.width < 50 || r.height < 200) return;
+          result.sidebars.push({
+            selector: fp(el),
+            position: r.x < window.innerWidth / 3 ? 'left' : r.x > window.innerWidth * 2 / 3 ? 'right' : 'center',
+            rect: { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) },
+            childCount: el.children.length,
+          });
+        });
+
+        // Dropdowns — select, popover, menu patterns
+        document.querySelectorAll('select, [role="listbox"], [role="menu"], [role="combobox"], [class*="dropdown"], [class*="popover"]').forEach(el => {
+          result.dropdowns.push({
+            selector: fp(el),
+            tag: el.tagName.toLowerCase(),
+            role: el.getAttribute('role'),
+            visible: el.offsetParent !== null || el.offsetWidth > 0,
+            rect: rect(el),
+          });
+        });
+
+        return JSON.stringify(result);
+      })()`;
+
+      const raw = await cdp.evaluate(domScript, 15000);
+      let domSnapshot: any = {};
+      if (typeof raw === 'string') { try { domSnapshot = JSON.parse(raw); } catch { domSnapshot = { raw }; } }
+      else domSnapshot = raw;
+
+      this.json(res, 200, {
+        screenshot: screenshot ? `base64:${screenshot}` : null,
+        domSnapshot,
+        pageTitle: await cdp.evaluate('document.title', 3000).catch(() => ''),
+        pageUrl: await cdp.evaluate('window.location.href', 3000).catch(() => ''),
+        providerType: type,
+        timestamp: new Date().toISOString(),
+      });
+    } catch (e: any) {
+      this.json(res, 500, { error: `DOM context collection failed: ${e.message}` });
+    }
+  }
+
+  // ─── Phase 2: Auto-Implement Backend ───
+
+  private async handleAutoImplement(type: string, req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    const { agent = 'claude-cli', functions, reference = 'antigravity', model } = body;
+    if (!functions || !Array.isArray(functions) || functions.length === 0) {
+      this.json(res, 400, { error: 'functions[] is required (e.g. ["readChat", "sendMessage"])' });
+      return;
+    }
+
+    if (this.autoImplStatus.running) {
+      this.json(res, 409, { error: 'Auto-implement already in progress', type: this.autoImplStatus.type });
+      return;
+    }
+
+    const provider = this.providerLoader.resolve(type);
+    if (!provider) { this.json(res, 404, { error: `Provider not found: ${type}` }); return; }
+
+    const providerDir = this.findProviderDir(type);
+    if (!providerDir) { this.json(res, 404, { error: `Provider directory not found: ${type}` }); return; }
+
+    try {
+      // 1. Collect DOM context
+      this.sendAutoImplSSE({ event: 'progress', data: { function: '_init', status: 'analyzing', message: 'DOM 구조 수집 중...' } });
+
+      let domContext: any = null;
+      const cdp = this.getCdp(type);
+      if (cdp) {
+        try {
+          const domScript = `(() => {
+            function fp(el) {
+              if (!el || el === document.body) return 'body';
+              const parts = [];
+              let c = el;
+              while (c && c !== document.documentElement) {
+                let s = c.tagName.toLowerCase();
+                if (c.id) s = '#' + c.id;
+                else if (c.className && typeof c.className === 'string') {
+                  const cls = c.className.trim().split(/\\s+/).filter(x => x && !x.startsWith('_')).slice(0, 2);
+                  if (cls.length) s += '.' + cls.join('.');
+                }
+                parts.unshift(s);
+                c = c.parentElement;
+              }
+              return parts.join(' > ');
+            }
+            const r = {};
+            // Content editables
+            r.editables = [...document.querySelectorAll('[contenteditable], textarea, input')].filter(e => e.offsetWidth > 0).slice(0, 10).map(e => ({
+              selector: fp(e), tag: e.tagName.toLowerCase(), ce: e.getAttribute('contenteditable'), role: e.getAttribute('role'), ph: e.getAttribute('placeholder')
+            }));
+            // Scroll containers
+            r.scrollContainers = [...document.querySelectorAll('div, section')].filter(e => {
+              const s = getComputedStyle(e); const b = e.getBoundingClientRect();
+              return (s.overflowY === 'auto' || s.overflowY === 'scroll') && b.height > 200 && e.children.length > 2;
+            }).slice(0, 5).map(e => ({ selector: fp(e), children: e.children.length, h: Math.round(e.getBoundingClientRect().height) }));
+            // Buttons
+            r.buttons = [...document.querySelectorAll('button, [role="button"]')].filter(e => e.offsetWidth > 0).slice(0, 20).map(e => ({
+              text: (e.textContent||'').trim().substring(0, 60), selector: fp(e), label: e.getAttribute('aria-label')
+            }));
+            return JSON.stringify(r);
+          })()`;
+          const raw = await cdp.evaluate(domScript, 10000);
+          domContext = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        } catch (e: any) {
+          this.log(`DOM context collection failed (non-fatal): ${e.message}`);
+        }
+      }
+
+      // 2. Load reference scripts
+      this.sendAutoImplSSE({ event: 'progress', data: { function: '_init', status: 'loading_reference', message: `레퍼런스 스크립트 로드 중 (${reference})...` } });
+
+      let referenceScripts: Record<string, string> = {};
+      const builtinDir = (this.providerLoader as any).builtinDir || path.resolve(__dirname, '../providers/_builtin');
+      const refDir = path.join(builtinDir, 'ide', reference);
+      if (fs.existsSync(refDir)) {
+        // Find latest versioned scripts dir
+        const scriptsDir = path.join(refDir, 'scripts');
+        if (fs.existsSync(scriptsDir)) {
+          const versions = fs.readdirSync(scriptsDir).filter((d: string) => {
+            try { return fs.statSync(path.join(scriptsDir, d)).isDirectory(); } catch { return false; }
+          }).sort().reverse();
+          if (versions.length > 0) {
+            const latestDir = path.join(scriptsDir, versions[0]);
+            for (const file of fs.readdirSync(latestDir)) {
+              if (file.endsWith('.js')) {
+                try {
+                  referenceScripts[file] = fs.readFileSync(path.join(latestDir, file), 'utf-8');
+                } catch { /* skip */ }
+              }
+            }
+          }
+        }
+      }
+
+      // 3. Build the prompt
+      const prompt = this.buildAutoImplPrompt(type, provider, providerDir, functions, domContext, referenceScripts);
+
+      // 4. Write prompt to temp file (avoids shell escaping issues with special chars)
+      const tmpDir = path.join(os.tmpdir(), 'adhdev-autoimpl');
+      if (!fs.existsSync(tmpDir)) fs.mkdirSync(tmpDir, { recursive: true });
+      const promptFile = path.join(tmpDir, `prompt-${type}-${Date.now()}.md`);
+      fs.writeFileSync(promptFile, prompt, 'utf-8');
+      this.log(`Auto-implement prompt written to ${promptFile} (${prompt.length} chars)`);
+
+      // 5. Determine agent command from provider spawn config
+      const agentProvider = this.providerLoader.resolve(agent) || this.providerLoader.getMeta(agent);
+      const spawn = (agentProvider as any)?.spawn;
+      if (!spawn?.command) {
+        try { fs.unlinkSync(promptFile); } catch { /* ignore */ }
+        this.json(res, 400, { error: `Agent '${agent}' has no spawn config. Select a CLI provider with a spawn configuration.` });
+        return;
+      }
+
+      const agentCategory = (agentProvider as any)?.category;
+
+      // ─── ACP Agent: use ACP SDK (JSON-RPC protocol) ───
+      if (agentCategory === 'acp') {
+        this.sendAutoImplSSE({ event: 'progress', data: { function: '_init', status: 'spawning', message: `ACP 에이전트 실행 중: ${spawn.command} ${(spawn.args || []).join(' ')}` } });
+        this.autoImplStatus = { running: true, type, progress: [] };
+
+        // Dynamic import ACP SDK
+        const { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION } = await import('@agentclientprotocol/sdk');
+        const { Readable, Writable } = await import('stream');
+        const { spawn: spawnFn } = await import('child_process');
+
+        // Add model override to spawn args if specified
+        const acpArgs = [...(spawn.args || [])];
+        if (model) {
+          acpArgs.push('--model', model);
+          this.log(`Auto-implement ACP using model: ${model}`);
+        }
+
+        const child = spawnFn(spawn.command, acpArgs, {
+          cwd: providerDir,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          shell: spawn.shell ?? false,
+          env: { ...process.env, ...(spawn.env || {}) },
+        });
+        this.autoImplProcess = child;
+
+        // stderr → stream to SSE
+        child.stderr?.on('data', (d: Buffer) => {
+          const chunk = d.toString();
+          this.sendAutoImplSSE({ event: 'output', data: { chunk, stream: 'stderr' } });
+        });
+
+        // Setup ACP connection via SDK
+        const webStdin = Writable.toWeb(child.stdin!) as WritableStream<Uint8Array>;
+        const webStdout = Readable.toWeb(child.stdout!) as ReadableStream<Uint8Array>;
+        const stream = ndJsonStream(webStdin, webStdout);
+
+        const connection = new ClientSideConnection((_agent: any) => ({
+          // Auto-approve all tool calls for auto-implement
+          requestPermission: async (params: any) => {
+            const allowOpt = params.options?.find((o: any) => o.kind === 'allow_once') || params.options?.[0];
+            this.sendAutoImplSSE({ event: 'output', data: { chunk: `[ACP] Auto-approved: ${params.toolCall?.title || 'tool call'}\n`, stream: 'stdout' } });
+            return { outcome: { outcome: 'selected', optionId: allowOpt?.optionId || '' } };
+          },
+          sessionUpdate: async (params: any) => {
+            const update = params?.update;
+            if (!update) return;
+            // Stream meaningful output only (skip thought chunks — they're too verbose)
+            switch (update.sessionUpdate) {
+              case 'agent_message_chunk':
+                if (update.content?.text) {
+                  this.sendAutoImplSSE({ event: 'output', data: { chunk: update.content.text, stream: 'stdout' } });
+                }
+                break;
+              case 'tool_call':
+                this.sendAutoImplSSE({ event: 'output', data: { chunk: `\n🔧 [Tool] ${update.title || 'unknown'}\n`, stream: 'stdout' } });
+                break;
+              case 'tool_call_update':
+                if (update.status === 'completed' || update.status === 'failed') {
+                  const label = update.status === 'completed' ? '✅' : '❌';
+                  const out = update.rawOutput ? (typeof update.rawOutput === 'string' ? update.rawOutput : JSON.stringify(update.rawOutput)) : '';
+                  this.sendAutoImplSSE({ event: 'output', data: { chunk: `${label} Result: ${out.slice(0, 1000)}\n`, stream: 'stdout' } });
+                }
+                break;
+              case 'agent_thought_chunk':
+                // Skip — too verbose for auto-implement UI
+                break;
+              default:
+                break;
+            }
+          },
+          // Not used for auto-implement
+          readTextFile: async () => { throw new Error('not supported'); },
+          writeTextFile: async () => { throw new Error('not supported'); },
+          createTerminal: async () => { throw new Error('not supported'); },
+          terminalOutput: async () => { throw new Error('not supported'); },
+          releaseTerminal: async () => { throw new Error('not supported'); },
+          waitForTerminalExit: async () => { throw new Error('not supported'); },
+          killTerminal: async () => { throw new Error('not supported'); },
+        }), stream);
+
+        child.on('exit', (code) => {
+          this.autoImplProcess = null;
+          this.autoImplStatus.running = false;
+          const success = code === 0;
+          this.sendAutoImplSSE({ event: 'complete', data: { success, exitCode: code, functions, message: success ? '✅ ACP Auto-implement 완료' : `❌ ACP 에이전트 종료 (code: ${code})` } });
+          try { this.providerLoader.reload(); } catch { /* ignore */ }
+          try { fs.unlinkSync(promptFile); } catch { /* ignore */ }
+          this.log(`Auto-implement (ACP) ${success ? 'completed' : 'failed'}: ${type} (exit: ${code})`);
+        });
+
+        // ACP handshake flow (async, runs in background)
+        (async () => {
+          try {
+            this.sendAutoImplSSE({ event: 'progress', data: { function: '_init', status: 'initializing', message: 'ACP initialize...' } });
+            await connection.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} });
+
+            this.sendAutoImplSSE({ event: 'progress', data: { function: '_init', status: 'session', message: 'ACP session 생성 중...' } });
+            const session = await connection.newSession({ cwd: providerDir, mcpServers: [] });
+            const sessionId = session?.sessionId;
+            if (!sessionId) throw new Error('No sessionId returned from session/new');
+
+            this.sendAutoImplSSE({ event: 'progress', data: { function: '_init', status: 'prompting', message: `프롬프트 전송 중 (${prompt.length} chars)...` } });
+            await connection.prompt({
+              sessionId,
+              prompt: [{ type: 'text', text: prompt }],
+            });
+
+            this.sendAutoImplSSE({ event: 'progress', data: { function: '_done', status: 'complete', message: '✅ ACP 프롬프트 처리 완료' } });
+          } catch (e: any) {
+            this.sendAutoImplSSE({ event: 'output', data: { chunk: `[ACP Error] ${e.message}\n`, stream: 'stderr' } });
+            this.log(`Auto-implement ACP error: ${e.message}`);
+            // Process exit will trigger the 'complete' SSE event
+            if (child.exitCode === null) { child.kill('SIGTERM'); }
+          }
+        })();
+
+        this.json(res, 202, {
+          started: true, type, agent: spawn.command, functions, providerDir,
+          message: 'ACP Auto-implement started. Connect to SSE for progress.',
+          sseUrl: `/api/providers/${type}/auto-implement/status`,
+        });
+        return;
+      }
+
+      // ─── CLI Agent: stdin pipe approach ───
+      const command: string = spawn.command;
+      // Strip interactive-only flags for auto-implement (non-interactive mode)
+      const interactiveFlags = ['--yolo', '--interactive', '-i'];
+      const baseArgs: string[] = [...(spawn.args || [])].filter((a: string) => !interactiveFlags.includes(a));
+      let args: string[];
+      let useStdin = true;
+
+      if (command === 'claude') {
+        // Claude Code: --print mode, skip permissions for non-interactive auto-implement
+        args = [...baseArgs, '--print', '--dangerously-skip-permissions', '--add-dir', providerDir];
+        useStdin = true;
+      } else if (command === 'gemini') {
+        // Gemini CLI: -p (non-interactive mode) with stdin piped prompt
+        // -p "" means "non-interactive mode, read prompt from stdin"
+        // -y for yolo (auto-approve all), -s false for no sandbox
+        args = [...baseArgs, '-p', '', '-y', '-s', 'false'];
+        if (model) {
+          args.push('-m', model);
+        }
+        useStdin = true;
+      } else {
+        // Codex CLI, etc: pipe prompt via stdin
+        args = [...baseArgs];
+      }
+
+      // 5.5. Check agent binary exists
+      const { execSync } = await import('child_process');
+      try {
+        execSync(`which ${command}`, { stdio: 'pipe' });
+      } catch {
+        try { fs.unlinkSync(promptFile); } catch { /* ignore */ }
+        this.json(res, 400, { error: `Agent binary '${command}' not found on PATH. Install it first: ${(agentProvider as any)?.install || 'check provider docs'}` });
+        return;
+      }
+
+      // 6. Spawn CLI agent via shell pipe (avoids Node.js stdin deadlock on large prompts)
+      this.sendAutoImplSSE({ event: 'progress', data: { function: '_init', status: 'spawning', message: `에이전트 실행 중: ${command} ${args.join(' ')} (prompt: ${prompt.length} chars)` } });
+
+      this.autoImplStatus = { running: true, type, progress: [] };
+
+      const { spawn: spawnFn } = await import('child_process');
+      // Shell pipe: cat promptFile | command args...
+      // This avoids Node.js stdin buffer deadlock and ensures proper EOF signaling
+      const escapedArgs = args.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(' ');
+      const shellCmd = `cat '${promptFile}' | ${command} ${escapedArgs}`;
+      this.log(`Auto-implement spawn: ${shellCmd}`);
+      const child = spawnFn('sh', ['-c', shellCmd], {
+        cwd: providerDir,
+        shell: false,
+        timeout: 900000, // 15 min timeout
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, ...(spawn.env || {}) },
+      });
+      this.autoImplProcess = child;
+      child.on('error', (err) => {
+        this.log(`Auto-implement spawn error: ${err.message}`);
+        this.sendAutoImplSSE({ event: 'output', data: { chunk: `[Spawn Error] ${err.message}\n`, stream: 'stderr' } });
+      });
+
+      let stdout = '';
+      let stderr = '';
+      child.stdout?.on('data', (d: Buffer) => {
+        const chunk = d.toString();
+        stdout += chunk;
+        this.sendAutoImplSSE({ event: 'output', data: { chunk, stream: 'stdout' } });
+      });
+      child.stderr?.on('data', (d: Buffer) => {
+        const chunk = d.toString();
+        stderr += chunk;
+        this.sendAutoImplSSE({ event: 'output', data: { chunk, stream: 'stderr' } });
+      });
+
+      child.on('exit', (code) => {
+        this.autoImplProcess = null;
+        this.autoImplStatus.running = false;
+        const success = code === 0;
+        this.sendAutoImplSSE({
+          event: 'complete',
+          data: {
+            success,
+            exitCode: code,
+            functions,
+            message: success ? '✅ Auto-implement 완료' : `❌ 에이전트 종료 (code: ${code})`,
+          },
+        });
+        // Reload providers to pick up new scripts
+        try { this.providerLoader.reload(); } catch { /* ignore */ }
+        // Cleanup temp prompt file
+        try { fs.unlinkSync(promptFile); } catch { /* ignore */ }
+        this.log(`Auto-implement ${success ? 'completed' : 'failed'}: ${type} (exit: ${code})`);
+      });
+
+      this.json(res, 202, {
+        started: true,
+        type,
+        agent: command,
+        functions,
+        providerDir,
+        message: 'Auto-implement started. Connect to SSE for progress.',
+        sseUrl: `/api/providers/${type}/auto-implement/status`,
+      });
+    } catch (e: any) {
+      this.autoImplStatus.running = false;
+      this.json(res, 500, { error: `Auto-implement failed: ${e.message}` });
+    }
+  }
+
+  private buildAutoImplPrompt(
+    type: string,
+    provider: any,
+    providerDir: string,
+    functions: string[],
+    domContext: any,
+    referenceScripts: Record<string, string>,
+  ): string {
+    const lines: string[] = [];
+
+    // ── System instructions ──
+    lines.push('You are implementing browser automation scripts for an IDE provider.');
+    lines.push('Be concise. Do NOT explain your reasoning. Just edit files directly.');
+    lines.push('');
+
+    // ── Target ──
+    lines.push(`# Target: ${provider.name || type} (${type})`);
+    lines.push(`Provider directory: \`${providerDir}\``);
+    lines.push('');
+
+    // ── Existing target files (inline, so no reading needed) ──
+    lines.push('## Current Target Files');
+    lines.push('These are the files you need to EDIT. They contain TODO stubs — replace them with working implementations.');
+    lines.push('');
+
+    const scriptsDir = path.join(providerDir, 'scripts');
+    if (fs.existsSync(scriptsDir)) {
+      const versions = fs.readdirSync(scriptsDir).filter((d: string) => {
+        try { return fs.statSync(path.join(scriptsDir, d)).isDirectory(); } catch { return false; }
+      }).sort().reverse();
+      if (versions.length > 0) {
+        const vDir = path.join(scriptsDir, versions[0]);
+        lines.push(`Scripts version directory: \`${vDir}\``);
+        lines.push('');
+        for (const file of fs.readdirSync(vDir)) {
+          if (file.endsWith('.js')) {
+            try {
+              const content = fs.readFileSync(path.join(vDir, file), 'utf-8');
+              lines.push(`### \`${file}\``);
+              lines.push('```javascript');
+              lines.push(content);
+              lines.push('```');
+              lines.push('');
+            } catch { /* skip */ }
+          }
+        }
+      }
+    }
+
+    // ── DOM context ──
+    if (domContext) {
+      lines.push('## Live DOM Analysis (from CDP)');
+      lines.push('Use these selectors in your implementations:');
+      lines.push('```json');
+      lines.push(JSON.stringify(domContext, null, 2));
+      lines.push('```');
+      lines.push('');
+    }
+
+    // ── Reference implementation ──
+    const funcToFile: Record<string, string> = {
+      readChat: 'read_chat.js', sendMessage: 'send_message.js',
+      resolveAction: 'resolve_action.js', listSessions: 'list_sessions.js',
+      listChats: 'list_chats.js', switchSession: 'switch_session.js',
+      newSession: 'new_session.js', focusEditor: 'focus_editor.js',
+      openPanel: 'open_panel.js', listModels: 'list_models.js',
+      listModes: 'list_modes.js', setModel: 'set_model.js', setMode: 'set_mode.js',
+    };
+
+    if (Object.keys(referenceScripts).length > 0) {
+      lines.push('## Reference Implementation (from Antigravity provider)');
+      lines.push('These are WORKING scripts from another IDE. Adapt the PATTERNS (not selectors) for the target IDE.');
+      lines.push('');
+      for (const fn of functions) {
+        const fileName = funcToFile[fn];
+        if (fileName && referenceScripts[fileName]) {
+          lines.push(`### ${fn} → \`${fileName}\``);
+          lines.push('```javascript');
+          lines.push(referenceScripts[fileName]);
+          lines.push('```');
+          lines.push('');
+        }
+      }
+      if (referenceScripts['scripts.js']) {
+        lines.push('### Router → `scripts.js`');
+        lines.push('```javascript');
+        lines.push(referenceScripts['scripts.js']);
+        lines.push('```');
+        lines.push('');
+      }
+    }
+
+    // ── Task ──
+    lines.push('## Task');
+    lines.push(`Edit files in \`${providerDir}\` to implement: **${functions.join(', ')}**`);
+    lines.push('');
+
+    // ── Rules ──
+    lines.push('## Rules');
+    lines.push('1. **Scripts WITHOUT params** → IIFE: `(() => { ... })()`');
+    lines.push('2. **Scripts WITH params** → arrow: `(params) => { ... }` — router calls `(${script})(${JSON.stringify(params)})`');
+    lines.push('3. Use CSS selectors from the DOM analysis above');
+    lines.push('4. Always wrap in try-catch, return `JSON.stringify(result)`');
+    lines.push('5. Do NOT modify `scripts.js` router — only edit individual `*.js` files');
+    lines.push('6. All scripts run in the browser (CDP evaluate) — use DOM APIs only');
+    lines.push('');
+
+    // ── Output contracts ──
+    lines.push('## Required Return Format');
+    lines.push('| Function | Return JSON |');
+    lines.push('|---|---|');
+    lines.push('| readChat | `{ id, status, title, messages: [{role, content, index}], inputContent, activeModal }` |');
+    lines.push('| sendMessage | `{ sent: false, needsTypeAndSend: true, selector }` |');
+    lines.push('| resolveAction | `{ resolved: true/false, clicked? }` |');
+    lines.push('| listSessions | `{ sessions: [{ id, title, active, index }] }` |');
+    lines.push('| switchSession | `{ switched: true/false }` |');
+    lines.push('| newSession | `{ created: true/false }` |');
+    lines.push('| listModels | `{ models: [{ name, id }], current }` |');
+    lines.push('| setModel | `{ success: true/false }` |');
+    lines.push('| listModes | `{ modes: [{ name, id }], current }` |');
+    lines.push('| setMode | `{ success: true/false }` |');
+    lines.push('| focusEditor | `{ focused: true/false }` |');
+    lines.push('| openPanel | `{ opened: true/false }` |');
+    lines.push('');
+
+    lines.push('## Action');
+    lines.push('1. Edit the script files to implement working code');
+    lines.push('2. After editing, TEST each function using the DevConsole API (see below)');
+    lines.push('3. If a test fails, fix the implementation and re-test');
+    lines.push('');
+
+    // ── DevConsole API for verification ──
+    lines.push('## DevConsole API (for testing)');
+    lines.push(`The DevConsole is running at \`http://127.0.0.1:${DEV_SERVER_PORT}\`. Use these HTTP APIs to test your implementations.`);
+    lines.push('');
+    lines.push('### Run a script against the live IDE');
+    lines.push('```bash');
+    lines.push(`curl -X POST http://127.0.0.1:${DEV_SERVER_PORT}/api/providers/${type}/scripts/run \\`);
+    lines.push(`  -H "Content-Type: application/json" \\`);
+    lines.push(`  -d '{"script": "readChat"}'`);
+    lines.push('```');
+    lines.push('Replace `"readChat"` with any function name. For functions with params:');
+    lines.push('```bash');
+    lines.push(`curl -X POST http://127.0.0.1:${DEV_SERVER_PORT}/api/providers/${type}/scripts/run \\`);
+    lines.push(`  -H "Content-Type: application/json" \\`);
+    lines.push(`  -d '{"script": "sendMessage", "params": {"text": "hello"}}'`);
+    lines.push('```');
+    lines.push('');
+    lines.push('### Evaluate raw JS in the IDE (CDP)');
+    lines.push('```bash');
+    lines.push(`curl -X POST http://127.0.0.1:${DEV_SERVER_PORT}/api/cdp/evaluate \\`);
+    lines.push(`  -H "Content-Type: application/json" \\`);
+    lines.push(`  -d '{"expression": "document.title", "ideType": "${type}"}'`);
+    lines.push('```');
+    lines.push('');
+    lines.push('### Reload provider (after editing files)');
+    lines.push('```bash');
+    lines.push(`curl -X POST http://127.0.0.1:${DEV_SERVER_PORT}/api/providers/reload`);
+    lines.push('```');
+    lines.push('**IMPORTANT**: After editing script files, you MUST call reload before running scripts.');
+    lines.push('');
+    lines.push('### Workflow: Edit → Reload → Test → Fix');
+    lines.push('1. Edit the `.js` file');
+    lines.push('2. `curl POST /api/providers/reload`');
+    lines.push(`3. \`curl POST /api/providers/${type}/scripts/run -d '{"script":"readChat"}'\``);
+    lines.push('4. Check the response — if error, fix and repeat from step 1');
+    lines.push('');
+    lines.push('Start NOW. Edit files, then test each one.');
+
+    return lines.join('\n');
+  }
+
+  private handleAutoImplSSE(type: string, req: http.IncomingMessage, res: http.ServerResponse): void {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+    res.write(`data: ${JSON.stringify({ type: 'connected', running: this.autoImplStatus.running, providerType: type })}\n\n`);
+
+    // Replay existing progress
+    for (const p of this.autoImplStatus.progress) {
+      res.write(`event: ${p.event}\ndata: ${JSON.stringify(p.data)}\n\n`);
+    }
+
+    this.autoImplSSEClients.push(res);
+    req.on('close', () => {
+      this.autoImplSSEClients = this.autoImplSSEClients.filter(c => c !== res);
+    });
+  }
+
+  private handleAutoImplCancel(_type: string, _req: http.IncomingMessage, res: http.ServerResponse): void {
+    if (this.autoImplProcess) {
+      this.autoImplProcess.kill('SIGTERM');
+      setTimeout(() => { if (this.autoImplProcess) this.autoImplProcess.kill('SIGKILL'); }, 3000);
+      this.sendAutoImplSSE({ event: 'complete', data: { success: false, exitCode: -1, message: '⛔ 사용자에 의해 중단됨' } });
+      this.autoImplProcess = null;
+      this.autoImplStatus.running = false;
+      this.json(res, 200, { cancelled: true });
+    } else {
+      this.autoImplStatus.running = false;
+      this.json(res, 200, { cancelled: false, message: 'No running process' });
+    }
+  }
+
+  private sendAutoImplSSE(msg: { event: string; data: any }): void {
+    this.autoImplStatus.progress.push(msg);
+    const payload = `event: ${msg.event}\ndata: ${JSON.stringify(msg.data)}\n\n`;
+    for (const client of this.autoImplSSEClients) {
+      try { client.write(payload); } catch { /* ignore */ }
+    }
+  }
+
+  /** Get CDP manager — matching IDE when ideType specified, first connected one otherwise */
+  private getCdp(ideType?: string): DaemonCdpManager | null {
+    if (ideType) {
+      const cdp = this.cdpManagers.get(ideType);
+      if (cdp?.isConnected) return cdp;
+    }
+    for (const cdp of this.cdpManagers.values()) {
+      if (cdp.isConnected) return cdp;
+    }
+    return null;
+  }
+
+  private getAnyCdp(): DaemonCdpManager | null {
+    return this.getCdp();
+  }
+
+  private json(res: http.ServerResponse, status: number, data: any): void {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(data, null, 2));
+  }
+
+  private async readBody(req: http.IncomingMessage): Promise<any> {
+    return new Promise((resolve) => {
+      let body = '';
+      req.on('data', (chunk) => body += chunk);
+      req.on('end', () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch {
+          resolve({});
+        }
+      });
+    });
+  }
+}