kernelbot 1.0.20 → 1.0.22

package/kernelbot/hello-world.md

@@ -0,0 +1,21 @@
+# Hello World! 🌍
+
+This is a **test file** created to verify that everything is working properly.
+
+## About This File
+
+This file demonstrates:
+- *Basic markdown formatting*
+- **Bold text**
+- Simple lists
+
+## Features Tested
+
+- ✅ File creation
+- ✅ Markdown formatting  
+- ✅ Emoji support 🚀
+- ✅ Basic structure
+
+---
+
+*Created as a test for the KernelBot project!* 🤖

package/kernelbot/newnew-1.md

@@ -0,0 +1,11 @@
+# Hello World 👋
+
+Welcome to **newnew-1**! This is a simple hello world file.
+
+## Quick Example
+
+```python
+print("Hello, World!")
+```
+
+> Keep it simple. Keep it fun.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kernelbot",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "KernelBot — AI engineering agent with full OS control",
   "type": "module",
   "author": "Abdullah Al-Taheri <abdullah@altaheri.me>",
@@ -34,9 +34,11 @@
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "dotenv": "^16.4.7",
+    "gradient-string": "^3.0.0",
     "js-yaml": "^4.1.0",
     "node-telegram-bot-api": "^0.66.0",
     "ora": "^8.1.1",
+    "puppeteer": "^24.37.3",
     "simple-git": "^3.31.1",
     "uuid": "^11.1.0",
     "winston": "^3.17.0"

package/src/agent.js

@@ -13,10 +13,11 @@ export class Agent {
     this._pending = new Map(); // chatId -> pending state
   }
 
-  async processMessage(chatId, userMessage, user, onUpdate) {
+  async processMessage(chatId, userMessage, user, onUpdate, sendPhoto) {
     const logger = getLogger();
 
     this._onUpdate = onUpdate || null;
+    this._sendPhoto = sendPhoto || null;
 
     // Handle pending responses (confirmation or credential)
     const pending = this._pending.get(chatId);
@@ -66,6 +67,11 @@ export class Agent {
       docker_compose: 'action',
       curl_url: 'url',
       check_port: 'port',
+      screenshot_website: 'url',
+      send_image: 'file_path',
+      browse_website: 'url',
+      extract_content: 'url',
+      interact_with_page: 'url',
     }[name];
     const val = key && input[key] ? String(input[key]).slice(0, 120) : JSON.stringify(input).slice(0, 120);
     return `${name}: ${val}`;
@@ -100,6 +106,7 @@ export class Agent {
       config: this.config,
       user,
       onUpdate: this._onUpdate,
+      sendPhoto: this._sendPhoto,
     });
 
     pending.toolResults.push({
@@ -117,7 +124,7 @@ export class Agent {
 
     if (lower === 'yes' || lower === 'y' || lower === 'confirm') {
       logger.info(`User confirmed dangerous tool: ${pending.block.name}`);
-      const result = await executeTool(pending.block.name, pending.block.input, { ...pending.context, onUpdate: this._onUpdate });
+      const result = await executeTool(pending.block.name, pending.block.input, { ...pending.context, onUpdate: this._onUpdate, sendPhoto: this._sendPhoto });
 
       pending.toolResults.push({
         type: 'tool_result',
@@ -144,7 +151,7 @@ export class Agent {
       const pauseMsg = await this._checkPause(chatId, block, user, pending.toolResults, pending.remainingBlocks.filter((b) => b !== block), pending.messages);
       if (pauseMsg) return pauseMsg;
 
-      const r = await executeTool(block.name, block.input, { config: this.config, user, onUpdate: this._onUpdate });
+      const r = await executeTool(block.name, block.input, { config: this.config, user, onUpdate: this._onUpdate, sendPhoto: this._sendPhoto });
       pending.toolResults.push({
         type: 'tool_result',
         tool_use_id: block.id,
@@ -256,6 +263,7 @@ export class Agent {
             config: this.config,
             user,
             onUpdate: this._onUpdate,
+            sendPhoto: this._sendPhoto,
           });
 
           toolResults.push({

package/src/bot.js

@@ -1,4 +1,5 @@
 import TelegramBot from 'node-telegram-bot-api';
+import { createReadStream } from 'fs';
 import { isAllowedUser, getUnauthorizedMessage } from './security/auth.js';
 import { getLogger } from './utils/logger.js';
 
@@ -47,7 +48,7 @@ export function startBot(config, agent, conversationManager) {
       return;
     }
 
-    const text = msg.text.trim();
+    let text = msg.text.trim();
 
     // Handle commands
     if (text === '/clean' || text === '/clear' || text === '/reset') {
@@ -69,6 +70,9 @@ export function startBot(config, agent, conversationManager) {
         '',
         '/clean — Clear conversation and start fresh',
         '/history — Show message count in memory',
+        '/browse <url> — Browse a website and get a summary',
+        '/screenshot <url> — Take a screenshot of a website',
+        '/extract <url> <selector> — Extract content using CSS selector',
         '/help — Show this help message',
         '',
         'Or just send any message to chat with the agent.',
@@ -76,6 +80,32 @@ export function startBot(config, agent, conversationManager) {
       return;
     }
 
+    // Web browsing shortcut commands — rewrite as natural language for the agent
+    if (text.startsWith('/browse ')) {
+      const browseUrl = text.slice('/browse '.length).trim();
+      if (!browseUrl) {
+        await bot.sendMessage(chatId, 'Usage: /browse <url>');
+        return;
+      }
+      text = `Browse this website and give me a summary: ${browseUrl}`;
+    } else if (text.startsWith('/screenshot ')) {
+      const screenshotUrl = text.slice('/screenshot '.length).trim();
+      if (!screenshotUrl) {
+        await bot.sendMessage(chatId, 'Usage: /screenshot <url>');
+        return;
+      }
+      text = `Take a screenshot of this website: ${screenshotUrl}`;
+    } else if (text.startsWith('/extract ')) {
+      const extractParts = text.slice('/extract '.length).trim().split(/\s+/);
+      if (extractParts.length < 2) {
+        await bot.sendMessage(chatId, 'Usage: /extract <url> <css-selector>');
+        return;
+      }
+      const extractUrl = extractParts[0];
+      const extractSelector = extractParts.slice(1).join(' ');
+      text = `Extract content from ${extractUrl} using the CSS selector: ${extractSelector}`;
+    }
+
     logger.info(`Message from ${username} (${userId}): ${text.slice(0, 100)}`);
 
     // Show typing and keep refreshing it
@@ -85,13 +115,57 @@ export function startBot(config, agent, conversationManager) {
     bot.sendChatAction(chatId, 'typing').catch(() => {});
 
     try {
-      const onUpdate = async (update) => {
+      const onUpdate = async (update, opts = {}) => {
+        // Edit an existing message instead of sending a new one
+        if (opts.editMessageId) {
+          try {
+            const edited = await bot.editMessageText(update, {
+              chat_id: chatId,
+              message_id: opts.editMessageId,
+              parse_mode: 'Markdown',
+            });
+            return edited.message_id;
+          } catch {
+            try {
+              const edited = await bot.editMessageText(update, {
+                chat_id: chatId,
+                message_id: opts.editMessageId,
+              });
+              return edited.message_id;
+            } catch {
+              return opts.editMessageId;
+            }
+          }
+        }
+
+        // Send new message(s)
         const parts = splitMessage(update);
+        let lastMsgId = null;
         for (const part of parts) {
           try {
-            await bot.sendMessage(chatId, part, { parse_mode: 'Markdown' });
+            const sent = await bot.sendMessage(chatId, part, { parse_mode: 'Markdown' });
+            lastMsgId = sent.message_id;
           } catch {
-            await bot.sendMessage(chatId, part);
+            const sent = await bot.sendMessage(chatId, part);
+            lastMsgId = sent.message_id;
+          }
+        }
+        return lastMsgId;
+      };
+
+      const sendPhoto = async (filePath, caption) => {
+        try {
+          await bot.sendPhoto(chatId, createReadStream(filePath), {
+            caption: caption || '',
+            parse_mode: 'Markdown',
+          });
+        } catch {
+          try {
+            await bot.sendPhoto(chatId, createReadStream(filePath), {
+              caption: caption || '',
+            });
+          } catch (err) {
+            logger.error(`Failed to send photo: ${err.message}`);
           }
         }
       };
@@ -99,7 +173,7 @@ export function startBot(config, agent, conversationManager) {
       const reply = await agent.processMessage(chatId, text, {
         id: userId,
         username,
-      }, onUpdate);
+      }, onUpdate, sendPhoto);
 
       clearInterval(typingInterval);
 

package/src/coder.js

@@ -84,7 +84,7 @@ function processEvent(line, onOutput, logger) {
     // Not JSON — send raw text if it looks meaningful
     if (line.trim() && line.length > 3 && onOutput) {
       logger.info(`Claude Code (raw): ${line.slice(0, 200)}`);
-      onOutput(`📟 ${line.trim()}`).catch(() => {});
+      onOutput(`▹ ${line.trim()}`).catch(() => {});
     }
     return null;
   }
@@ -103,7 +103,7 @@ function processEvent(line, onOutput, logger) {
     const tool = extractToolUse(event);
     if (tool) {
       logger.info(`Claude Code tool: ${tool.name}: ${tool.summary}`);
-      if (onOutput) onOutput(`🔨 \`${tool.name}: ${tool.summary}\``).catch(() => {});
+      if (onOutput) onOutput(`▸ ${tool.name}: ${tool.summary}`).catch(() => {});
     }
     return event;
   }
@@ -113,7 +113,7 @@ function processEvent(line, onOutput, logger) {
     const tool = extractToolUse(event);
     if (tool) {
       logger.info(`Claude Code tool: ${tool.name}: ${tool.summary}`);
-      if (onOutput) onOutput(`🔨 \`${tool.name}: ${tool.summary}\``).catch(() => {});
+      if (onOutput) onOutput(`▸ ${tool.name}: ${tool.summary}`).catch(() => {});
     }
     return event;
   }
@@ -124,7 +124,7 @@ function processEvent(line, onOutput, logger) {
     const duration = event.duration_ms ? ` in ${(event.duration_ms / 1000).toFixed(1)}s` : '';
     const cost = event.cost_usd ? ` ($${event.cost_usd.toFixed(3)})` : '';
     logger.info(`Claude Code finished: ${status}${duration}${cost}`);
-    if (onOutput) onOutput(`✅ Claude Code finished (${status}${duration}${cost})`).catch(() => {});
+    if (onOutput) onOutput(`▪ done (${status}${duration}${cost})`).catch(() => {});
     return event;
   }
 
@@ -160,7 +160,61 @@ export class ClaudeCodeSpawner {
     const cmd = `claude ${args.map((a) => a.includes(' ') ? `"${a}"` : a).join(' ')}`;
     logger.info(`Spawning: ${cmd.slice(0, 300)}`);
     logger.info(`CWD: ${workingDirectory}`);
-    if (onOutput) onOutput(`⏳ Starting Claude Code...\n\`${cmd.slice(0, 200)}\``).catch(() => {});
+
+    // --- Smart output: consolidate tool activity into one editable message ---
+    let statusMsgId = null;
+    let activityLines = [];
+    let flushTimer = null;
+    const MAX_VISIBLE = 15;
+
+    const buildStatusText = (finalState = null) => {
+      const visible = activityLines.slice(-MAX_VISIBLE);
+      const countInfo = activityLines.length > MAX_VISIBLE
+        ? `\n_... ${activityLines.length} operations total_\n`
+        : '';
+      if (finalState === 'done') {
+        return `░▒▓ *Claude Code Done* — ${activityLines.length} ops\n${countInfo}\n${visible.join('\n')}`;
+      }
+      if (finalState === 'error') {
+        return `░▒▓ *Claude Code Failed* — ${activityLines.length} ops\n${countInfo}\n${visible.join('\n')}`;
+      }
+      return `░▒▓ *Claude Code Working...*\n${countInfo}\n${visible.join('\n')}`;
+    };
+
+    const flushStatus = async () => {
+      flushTimer = null;
+      if (!onOutput || activityLines.length === 0) return;
+      try {
+        if (statusMsgId) {
+          await onOutput(buildStatusText(), { editMessageId: statusMsgId });
+        } else {
+          statusMsgId = await onOutput(buildStatusText());
+        }
+      } catch {}
+    };
+
+    const addActivity = (line) => {
+      activityLines.push(line);
+      if (!statusMsgId && !flushTimer) {
+        // First activity — create the status message immediately
+        flushStatus();
+      } else if (!flushTimer) {
+        // Throttle subsequent edits to avoid Telegram rate limits
+        flushTimer = setTimeout(flushStatus, 1000);
+      }
+    };
+
+    const smartOutput = onOutput ? async (text) => {
+      // Tool calls, raw output, warnings, starting → accumulate in status message
+      if (text.startsWith('▸') || text.startsWith('▹') || text.startsWith('▪')) {
+        addActivity(text);
+        return;
+      }
+      // Everything else (💬 text, errors, timeout) → new message
+      await onOutput(text);
+    } : null;
+
+    if (smartOutput) smartOutput(`▸ Starting Claude Code...`).catch(() => {});
 
     return new Promise((resolve, reject) => {
       const child = spawn('claude', args, {
@@ -193,7 +247,7 @@ export class ClaudeCodeSpawner {
             }
           } catch {}
 
-          processEvent(trimmed, onOutput, logger);
+          processEvent(trimmed, smartOutput, logger);
         }
       });
 
@@ -201,19 +255,18 @@ export class ClaudeCodeSpawner {
         const chunk = data.toString().trim();
         stderr += chunk + '\n';
         logger.warn(`Claude Code stderr: ${chunk.slice(0, 300)}`);
-        // Forward ALL stderr to Telegram immediately
-        if (onOutput && chunk) {
-          onOutput(`⚠️ Claude Code: ${chunk.slice(0, 400)}`).catch(() => {});
+        if (smartOutput && chunk) {
+          smartOutput(`▹ ${chunk.slice(0, 300)}`).catch(() => {});
         }
       });
 
       const timer = setTimeout(() => {
         child.kill('SIGTERM');
-        if (onOutput) onOutput(`⏰ Claude Code timed out after ${this.timeout / 1000}s`).catch(() => {});
+        if (smartOutput) smartOutput(`▸ Claude Code timed out after ${this.timeout / 1000}s`).catch(() => {});
         reject(new Error(`Claude Code timed out after ${this.timeout / 1000}s`));
       }, this.timeout);
 
-      child.on('close', (code) => {
+      child.on('close', async (code) => {
         clearTimeout(timer);
 
         if (buffer.trim()) {
@@ -224,7 +277,22 @@ export class ClaudeCodeSpawner {
               resultText = event.result || resultText;
             }
           } catch {}
-          processEvent(buffer.trim(), onOutput, logger);
+          processEvent(buffer.trim(), smartOutput, logger);
+        }
+
+        // Flush any pending status edits
+        if (flushTimer) {
+          clearTimeout(flushTimer);
+          flushTimer = null;
+        }
+        await flushStatus();
+
+        // Final status message update — show done/failed state
+        if (statusMsgId && onOutput) {
+          const finalState = code === 0 ? 'done' : 'error';
+          try {
+            await onOutput(buildStatusText(finalState), { editMessageId: statusMsgId });
+          } catch {}
         }
 
         logger.info(`Claude Code exited with code ${code} | stdout: ${fullOutput.length} chars | stderr: ${stderr.length} chars`);
@@ -232,7 +300,6 @@ export class ClaudeCodeSpawner {
         if (code !== 0) {
           const errMsg = stderr.trim() || fullOutput.trim() || `exited with code ${code}`;
           logger.error(`Claude Code failed: ${errMsg.slice(0, 500)}`);
-          if (onOutput) onOutput(`❌ Claude Code failed (exit ${code}):\n\`\`\`\n${errMsg.slice(0, 400)}\n\`\`\``).catch(() => {});
           reject(new Error(`Claude Code exited with code ${code}: ${errMsg.slice(0, 500)}`));
         } else {
           resolve({

package/src/prompts/system.js

@@ -17,8 +17,19 @@ IMPORTANT: You MUST NOT write code yourself using read_file/write_file. ALWAYS d
 4. Use GitHub tools to create the PR
 5. Report back with the PR link
 
+## Web Browsing Tasks (researching, scraping, reading documentation, taking screenshots)
+- Use browse_website to read and summarize web pages
+- Use screenshot_website to capture visual snapshots of pages — the screenshot is automatically sent to the chat
+- Use extract_content to pull specific data from pages using CSS selectors
+- Use interact_with_page for pages that need clicking, typing, or scrolling to reveal content
+- Use send_image to send any image file directly to the Telegram chat (screenshots, generated images, etc.)
+- When a user sends /browse <url>, use browse_website on that URL
+- When a user sends /screenshot <url>, use screenshot_website on that URL
+- When a user sends /extract <url> <selector>, use extract_content with that URL and selector
+
 You are the orchestrator. Claude Code is the coder. Never use read_file + write_file to modify source code — that's Claude Code's job. You handle git, GitHub, and infrastructure. Claude Code handles all code changes.
 
+
 ## Non-Coding Tasks (monitoring, deploying, restarting services, checking status)
 - Use OS, Docker, process, network, and monitoring tools directly
 - No need to spawn Claude Code for these

package/src/security/confirm.js

@@ -6,6 +6,7 @@ const DANGEROUS_PATTERNS = [
   { tool: 'github_create_repo', pattern: null, label: 'create a GitHub repository' },
   { tool: 'docker_compose', param: 'action', value: 'down', label: 'take down containers' },
   { tool: 'git_push', param: 'force', value: true, label: 'force push' },
+  { tool: 'interact_with_page', pattern: null, label: 'interact with a webpage (click, type, execute scripts)' },
 ];
 
 export function requiresConfirmation(toolName, params, config) {

package/src/tools/browser.js

@@ -0,0 +1,680 @@
+import puppeteer from 'puppeteer';
+import { writeFile, mkdir, access } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const NAVIGATION_TIMEOUT = 30000;
+const MAX_CONTENT_LENGTH = 15000;
+const MAX_SCREENSHOT_WIDTH = 1920;
+const MAX_SCREENSHOT_HEIGHT = 1080;
+const SCREENSHOTS_DIR = join(homedir(), '.kernelbot', 'screenshots');
+
+// Blocklist to prevent abuse — internal/private network ranges and sensitive targets
+const BLOCKED_URL_PATTERNS = [
+  /^https?:\/\/localhost/i,
+  /^https?:\/\/127\./,
+  /^https?:\/\/0\./,
+  /^https?:\/\/10\./,
+  /^https?:\/\/172\.(1[6-9]|2\d|3[01])\./,
+  /^https?:\/\/192\.168\./,
+  /^https?:\/\/\[::1\]/,
+  /^https?:\/\/169\.254\./,
+  /^file:/i,
+  /^ftp:/i,
+  /^data:/i,
+];
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function validateUrl(url) {
+  if (!url || typeof url !== 'string') {
+    return { valid: false, error: 'URL is required' };
+  }
+
+  // Block non-http protocols before auto-prepending https
+  for (const pattern of BLOCKED_URL_PATTERNS) {
+    if (pattern.test(url)) {
+      return { valid: false, error: 'Access to internal/private network addresses or non-HTTP protocols is blocked' };
+    }
+  }
+
+  // Add https:// if no protocol specified
+  if (!/^https?:\/\//i.test(url)) {
+    url = 'https://' + url;
+  }
+
+  try {
+    new URL(url);
+  } catch {
+    return { valid: false, error: 'Invalid URL format' };
+  }
+
+  // Check again after normalization (e.g., localhost without protocol)
+  for (const pattern of BLOCKED_URL_PATTERNS) {
+    if (pattern.test(url)) {
+      return { valid: false, error: 'Access to internal/private network addresses is blocked' };
+    }
+  }
+
+  return { valid: true, url };
+}
+
+function truncate(text, maxLength = MAX_CONTENT_LENGTH) {
+  if (!text || text.length <= maxLength) return text;
+  return text.slice(0, maxLength) + `\n\n... [truncated, ${text.length - maxLength} chars omitted]`;
+}
+
+async function ensureScreenshotsDir() {
+  await mkdir(SCREENSHOTS_DIR, { recursive: true });
+}
+
+async function withBrowser(fn) {
+  let browser;
+  try {
+    browser = await puppeteer.launch({
+      headless: true,
+      args: [
+        '--no-sandbox',
+        '--disable-setuid-sandbox',
+        '--disable-dev-shm-usage',
+        '--disable-gpu',
+        '--disable-extensions',
+        '--disable-background-networking',
+        '--disable-default-apps',
+        '--disable-sync',
+        '--no-first-run',
+      ],
+    });
+    return await fn(browser);
+  } finally {
+    if (browser) {
+      await browser.close().catch(() => {});
+    }
+  }
+}
+
+async function navigateTo(page, url, waitUntil = 'networkidle2') {
+  await page.setUserAgent(
+    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+  );
+  await page.setViewport({ width: MAX_SCREENSHOT_WIDTH, height: MAX_SCREENSHOT_HEIGHT });
+  await page.goto(url, {
+    waitUntil,
+    timeout: NAVIGATION_TIMEOUT,
+  });
+}
+
+// ── Tool Definitions ─────────────────────────────────────────────────────────
+
+export const definitions = [
+  {
+    name: 'browse_website',
+    description:
+      'Navigate to a website URL and extract its content including title, headings, text, links, and metadata. Returns a structured summary of the page. Handles JavaScript-rendered pages.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'The URL to browse (e.g., "https://example.com" or "example.com")',
+        },
+        wait_for_selector: {
+          type: 'string',
+          description: 'Optional CSS selector to wait for before extracting content (useful for JS-heavy pages)',
+        },
+        include_links: {
+          type: 'boolean',
+          description: 'Include links found on the page (default: false)',
+        },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'screenshot_website',
+    description:
+      'Take a screenshot of a website and save it to disk. Returns the file path to the screenshot image. Supports full-page and viewport-only screenshots.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'The URL to screenshot',
+        },
+        full_page: {
+          type: 'boolean',
+          description: 'Capture the full scrollable page instead of just the viewport (default: false)',
+        },
+        selector: {
+          type: 'string',
+          description: 'Optional CSS selector to screenshot a specific element instead of the full page',
+        },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'extract_content',
+    description:
+      'Extract specific content from a webpage using CSS selectors. Returns the text or HTML content of matched elements. Useful for scraping structured data.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'The URL to extract content from',
+        },
+        selector: {
+          type: 'string',
+          description: 'CSS selector to match elements (e.g., "h1", ".article-body", "#main-content")',
+        },
+        attribute: {
+          type: 'string',
+          description: 'Extract a specific attribute instead of text content (e.g., "href", "src")',
+        },
+        include_html: {
+          type: 'boolean',
+          description: 'Include raw HTML of matched elements (default: false, returns text only)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of elements to return (default: 20)',
+        },
+      },
+      required: ['url', 'selector'],
+    },
+  },
+  {
+    name: 'send_image',
+    description:
+      'Send an image or screenshot file directly to the Telegram chat. Use this to share screenshots, generated images, or any image file with the user.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        file_path: {
+          type: 'string',
+          description: 'Absolute path to the image file to send (e.g., "/home/user/.kernelbot/screenshots/example.png")',
+        },
+        caption: {
+          type: 'string',
+          description: 'Optional caption to include with the image',
+        },
+      },
+      required: ['file_path'],
+    },
+  },
+  {
+    name: 'interact_with_page',
+    description:
+      'Interact with a webpage by clicking elements, typing into inputs, scrolling, or executing JavaScript. Returns the page state after interaction.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'The URL to interact with',
+        },
+        actions: {
+          type: 'array',
+          description:
+            'List of actions to perform in sequence. Each action is an object with a "type" field.',
+          items: {
+            type: 'object',
+            properties: {
+              type: {
+                type: 'string',
+                enum: ['click', 'type', 'scroll', 'wait', 'evaluate'],
+                description: 'Action type',
+              },
+              selector: {
+                type: 'string',
+                description: 'CSS selector for the target element (for click and type actions)',
+              },
+              text: {
+                type: 'string',
+                description: 'Text to type (for type action)',
+              },
+              direction: {
+                type: 'string',
+                enum: ['down', 'up'],
+                description: 'Scroll direction (for scroll action, default: down)',
+              },
+              pixels: {
+                type: 'number',
+                description: 'Number of pixels to scroll (default: 500)',
+              },
+              milliseconds: {
+                type: 'number',
+                description: 'Time to wait in ms (for wait action, default: 1000)',
+              },
+              script: {
+                type: 'string',
+                description: 'JavaScript to execute in the page context (for evaluate action). Must be a single expression or IIFE.',
+              },
+            },
+            required: ['type'],
+          },
+        },
+        extract_after: {
+          type: 'boolean',
+          description: 'Extract page content after performing actions (default: true)',
+        },
+      },
+      required: ['url', 'actions'],
+    },
+  },
+];
+
+// ── Handlers ─────────────────────────────────────────────────────────────────
+
+async function handleBrowse(params) {
+  const validation = validateUrl(params.url);
+  if (!validation.valid) return { error: validation.error };
+
+  const url = validation.url;
+
+  return withBrowser(async (browser) => {
+    const page = await browser.newPage();
+
+    try {
+      await navigateTo(page, url);
+    } catch (err) {
+      if (err.message.includes('net::ERR_NAME_NOT_RESOLVED')) {
+        return { error: `Could not resolve hostname for: ${url}` };
+      }
+      if (err.message.includes('Timeout')) {
+        return { error: `Page load timed out after ${NAVIGATION_TIMEOUT / 1000}s: ${url}` };
+      }
+      return { error: `Navigation failed: ${err.message}` };
+    }
+
+    // Wait for optional selector
+    if (params.wait_for_selector) {
+      try {
+        await page.waitForSelector(params.wait_for_selector, { timeout: 10000 });
+      } catch {
+        // Continue even if selector not found
+      }
+    }
+
+    const content = await page.evaluate((includeLinks) => {
+      const title = document.title || '';
+      const metaDesc = document.querySelector('meta[name="description"]')?.content || '';
+      const canonicalUrl = document.querySelector('link[rel="canonical"]')?.href || window.location.href;
+
+      // Extract headings
+      const headings = [];
+      for (const tag of ['h1', 'h2', 'h3']) {
+        document.querySelectorAll(tag).forEach((el) => {
+          const text = el.textContent.trim();
+          if (text) headings.push({ level: tag, text });
+        });
+      }
+
+      // Extract main text content
+      // Prefer common article/content containers
+      const contentSelectors = [
+        'article', 'main', '[role="main"]',
+        '.content', '.article', '.post',
+        '#content', '#main', '#article',
+      ];
+
+      let mainText = '';
+      for (const sel of contentSelectors) {
+        const el = document.querySelector(sel);
+        if (el) {
+          mainText = el.innerText.trim();
+          break;
+        }
+      }
+
+      // Fall back to body text if no content container found
+      if (!mainText) {
+        // Remove script, style, nav, footer, header noise
+        const clone = document.body.cloneNode(true);
+        for (const el of clone.querySelectorAll('script, style, nav, footer, header, aside, [role="navigation"]')) {
+          el.remove();
+        }
+        mainText = clone.innerText.trim();
+      }
+
+      // Extract links if requested
+      let links = [];
+      if (includeLinks) {
+        document.querySelectorAll('a[href]').forEach((a) => {
+          const text = a.textContent.trim();
+          const href = a.href;
+          if (text && href && !href.startsWith('javascript:')) {
+            links.push({ text: text.slice(0, 100), href });
+          }
+        });
+        links = links.slice(0, 50);
+      }
+
+      return { title, metaDesc, canonicalUrl, headings, mainText, links };
+    }, params.include_links || false);
+
+    return {
+      success: true,
+      url: page.url(),
+      title: content.title,
+      meta_description: content.metaDesc,
+      canonical_url: content.canonicalUrl,
+      headings: content.headings.slice(0, 30),
+      content: truncate(content.mainText),
+      links: content.links || [],
+    };
+  });
+}
+
+async function handleScreenshot(params, context) {
+  const validation = validateUrl(params.url);
+  if (!validation.valid) return { error: validation.error };
+
+  const url = validation.url;
+  await ensureScreenshotsDir();
+
+  return withBrowser(async (browser) => {
+    const page = await browser.newPage();
+
+    try {
+      await navigateTo(page, url);
+    } catch (err) {
+      if (err.message.includes('net::ERR_NAME_NOT_RESOLVED')) {
+        return { error: `Could not resolve hostname for: ${url}` };
+      }
+      if (err.message.includes('Timeout')) {
+        return { error: `Page load timed out after ${NAVIGATION_TIMEOUT / 1000}s: ${url}` };
+      }
+      return { error: `Navigation failed: ${err.message}` };
+    }
+
+    const timestamp = Date.now();
+    const safeName = new URL(url).hostname.replace(/[^a-z0-9.-]/gi, '_');
+    const filename = `${safeName}_${timestamp}.png`;
+    const filepath = join(SCREENSHOTS_DIR, filename);
+
+    const screenshotOptions = {
+      path: filepath,
+      type: 'png',
+    };
+
+    if (params.selector) {
+      try {
+        const element = await page.$(params.selector);
+        if (!element) {
+          return { error: `Element not found for selector: ${params.selector}` };
+        }
+        await element.screenshot(screenshotOptions);
+      } catch (err) {
+        return { error: `Failed to screenshot element: ${err.message}` };
+      }
+    } else {
+      screenshotOptions.fullPage = params.full_page || false;
+      await page.screenshot(screenshotOptions);
+    }
+
+    const title = await page.title();
+
+    // Send the screenshot directly to Telegram chat
+    if (context?.sendPhoto) {
+      try {
+        await context.sendPhoto(filepath, `📸 ${title || url}`);
+      } catch {
+        // Photo sending is best-effort; don't fail the tool
+      }
+    }
+
+    return {
+      success: true,
+      url: page.url(),
+      title,
+      screenshot_path: filepath,
+      filename,
+      sent_to_chat: !!context?.sendPhoto,
+    };
+  });
+}
+
+async function handleExtract(params) {
+  const validation = validateUrl(params.url);
+  if (!validation.valid) return { error: validation.error };
+
+  const url = validation.url;
+  const limit = Math.min(params.limit || 20, 100);
+
+  return withBrowser(async (browser) => {
+    const page = await browser.newPage();
+
+    try {
+      await navigateTo(page, url);
+    } catch (err) {
+      if (err.message.includes('net::ERR_NAME_NOT_RESOLVED')) {
+        return { error: `Could not resolve hostname for: ${url}` };
+      }
+      if (err.message.includes('Timeout')) {
+        return { error: `Page load timed out after ${NAVIGATION_TIMEOUT / 1000}s: ${url}` };
+      }
+      return { error: `Navigation failed: ${err.message}` };
+    }
+
+    const results = await page.evaluate(
+      (selector, attribute, includeHtml, maxItems) => {
+        const elements = document.querySelectorAll(selector);
+        if (elements.length === 0) return { found: 0, items: [] };
+
+        const items = [];
+        for (let i = 0; i < Math.min(elements.length, maxItems); i++) {
+          const el = elements[i];
+          const item = {};
+
+          if (attribute) {
+            item.value = el.getAttribute(attribute) || null;
+          } else {
+            item.text = el.innerText?.trim() || el.textContent?.trim() || '';
+          }
+
+          if (includeHtml) {
+            item.html = el.outerHTML;
+          }
+
+          item.tag = el.tagName.toLowerCase();
+          items.push(item);
+        }
+
+        return { found: elements.length, items };
+      },
+      params.selector,
+      params.attribute || null,
+      params.include_html || false,
+      limit
+    );
+
+    if (results.found === 0) {
+      return {
+        success: true,
+        url: page.url(),
+        selector: params.selector,
+        found: 0,
+        items: [],
+        message: `No elements found matching selector: ${params.selector}`,
+      };
+    }
+
+    // Truncate individual items to prevent massive responses
+    for (const item of results.items) {
+      if (item.text) item.text = truncate(item.text, 2000);
+      if (item.html) item.html = truncate(item.html, 3000);
+    }
+
+    return {
+      success: true,
+      url: page.url(),
+      selector: params.selector,
+      found: results.found,
+      returned: results.items.length,
+      items: results.items,
+    };
+  });
+}
+
+async function handleInteract(params) {
+  const validation = validateUrl(params.url);
+  if (!validation.valid) return { error: validation.error };
+
+  const url = validation.url;
+
+  if (!params.actions || params.actions.length === 0) {
+    return { error: 'At least one action is required' };
+  }
+
+  if (params.actions.length > 10) {
+    return { error: 'Maximum 10 actions per request' };
+  }
+
+  // Block dangerous evaluate scripts
+  for (const action of params.actions) {
+    if (action.type === 'evaluate' && action.script) {
+      const blocked = /fetch\s*\(|XMLHttpRequest|window\.location\s*=|document\.cookie|localStorage|sessionStorage/i;
+      if (blocked.test(action.script)) {
+        return { error: 'Script contains blocked patterns (network requests, cookie access, storage access, or redirects)' };
+      }
+    }
+  }
+
+  return withBrowser(async (browser) => {
+    const page = await browser.newPage();
+
+    try {
+      await navigateTo(page, url);
+    } catch (err) {
+      if (err.message.includes('net::ERR_NAME_NOT_RESOLVED')) {
+        return { error: `Could not resolve hostname for: ${url}` };
+      }
+      if (err.message.includes('Timeout')) {
+        return { error: `Page load timed out after ${NAVIGATION_TIMEOUT / 1000}s: ${url}` };
+      }
+      return { error: `Navigation failed: ${err.message}` };
+    }
+
+    const actionResults = [];
+
+    for (const action of params.actions) {
+      try {
+        switch (action.type) {
+          case 'click': {
+            if (!action.selector) {
+              actionResults.push({ action: 'click', error: 'selector is required' });
+              break;
+            }
+            await page.waitForSelector(action.selector, { timeout: 5000 });
+            await page.click(action.selector);
+            // Brief wait for any navigation or rendering
+            await new Promise((r) => setTimeout(r, 500));
+            actionResults.push({ action: 'click', selector: action.selector, success: true });
+            break;
+          }
+
+          case 'type': {
+            if (!action.selector || !action.text) {
+              actionResults.push({ action: 'type', error: 'selector and text are required' });
+              break;
+            }
+            await page.waitForSelector(action.selector, { timeout: 5000 });
+            await page.type(action.selector, action.text);
+            actionResults.push({ action: 'type', selector: action.selector, success: true });
+            break;
+          }
+
+          case 'scroll': {
+            const direction = action.direction || 'down';
+            const pixels = Math.min(action.pixels || 500, 5000);
+            const scrollAmount = direction === 'up' ? -pixels : pixels;
+            await page.evaluate((amount) => window.scrollBy(0, amount), scrollAmount);
+            actionResults.push({ action: 'scroll', direction, pixels, success: true });
+            break;
+          }
+
+          case 'wait': {
+            const ms = Math.min(action.milliseconds || 1000, 10000);
+            await new Promise((r) => setTimeout(r, ms));
+            actionResults.push({ action: 'wait', milliseconds: ms, success: true });
+            break;
+          }
+
+          case 'evaluate': {
+            if (!action.script) {
+              actionResults.push({ action: 'evaluate', error: 'script is required' });
+              break;
+            }
+            const result = await page.evaluate(action.script);
+            actionResults.push({ action: 'evaluate', success: true, result: String(result).slice(0, 2000) });
+            break;
+          }
+
+          default:
+            actionResults.push({ action: action.type, error: `Unknown action type: ${action.type}` });
+        }
+      } catch (err) {
+        actionResults.push({ action: action.type, error: err.message });
+      }
+    }
+
+    const response = {
+      success: true,
+      url: page.url(),
+      title: await page.title(),
+      actions: actionResults,
+    };
+
+    // Extract content after interactions unless disabled
+    if (params.extract_after !== false) {
+      const text = await page.evaluate(() => {
+        const clone = document.body.cloneNode(true);
+        for (const el of clone.querySelectorAll('script, style, nav, footer, header')) {
+          el.remove();
+        }
+        return clone.innerText.trim();
+      });
+      response.content = truncate(text);
+    }
+
+    return response;
+  });
+}
+
+async function handleSendImage(params, context) {
+  if (!params.file_path) {
+    return { error: 'file_path is required' };
+  }
+
+  // Verify the file exists
+  try {
+    await access(params.file_path);
+  } catch {
+    return { error: `File not found: ${params.file_path}` };
+  }
+
+  if (!context?.sendPhoto) {
+    return { error: 'Image sending is not available in this context (no active Telegram chat)' };
+  }
+
+  try {
+    await context.sendPhoto(params.file_path, params.caption || '');
+    return { success: true, file_path: params.file_path, sent: true };
+  } catch (err) {
+    return { error: `Failed to send image: ${err.message}` };
+  }
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export const handlers = {
+  browse_website: handleBrowse,
+  screenshot_website: handleScreenshot,
+  extract_content: handleExtract,
+  interact_with_page: handleInteract,
+  send_image: handleSendImage,
+};

package/src/tools/index.js

@@ -6,6 +6,7 @@ import { definitions as networkDefinitions, handlers as networkHandlers } from '
 import { definitions as gitDefinitions, handlers as gitHandlers } from './git.js';
 import { definitions as githubDefinitions, handlers as githubHandlers } from './github.js';
 import { definitions as codingDefinitions, handlers as codingHandlers } from './coding.js';
+import { definitions as browserDefinitions, handlers as browserHandlers } from './browser.js';
 import { logToolCall } from '../security/audit.js';
 import { requiresConfirmation } from '../security/confirm.js';
 
@@ -18,6 +19,7 @@ export const toolDefinitions = [
   ...gitDefinitions,
   ...githubDefinitions,
   ...codingDefinitions,
+  ...browserDefinitions,
 ];
 
 const handlerMap = {
@@ -29,6 +31,7 @@ const handlerMap = {
   ...gitHandlers,
   ...githubHandlers,
   ...codingHandlers,
+  ...browserHandlers,
 };
 
 export function checkConfirmation(name, params, config) {

package/src/utils/display.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import ora from 'ora';
 import boxen from 'boxen';
+import gradient from 'gradient-string';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -25,8 +26,19 @@ const LOGO = `
  ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝╚═════╝  ╚═════╝    ╚═╝
 `;
 
+// Create a vibrant rainbow gradient
+const rainbowGradient = gradient([
+  '#FF0080', // Hot Pink
+  '#FF8C00', // Dark Orange
+  '#FFD700', // Gold
+  '#00FF00', // Lime Green
+  '#00CED1', // Dark Turquoise
+  '#1E90FF', // Dodger Blue
+  '#9370DB'  // Medium Purple
+]);
+
 export function showLogo() {
-  console.log(chalk.cyan(LOGO));
+  console.log(rainbowGradient.multiline(LOGO));
   console.log(chalk.dim(`  AI Engineering Agent — v${getVersion()}\n`));
   console.log(
     boxen(
@@ -93,4 +105,4 @@ export function showError(msg) {
 
 export function createSpinner(text) {
   return ora({ text, color: 'cyan' });
-}
+}