opencode-webfetch-plugin 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# Opencode Google AI Search Plugin
+
+An Opencode plugin that exposes a native tool (`google_ai_search_plus`) for querying Google AI Mode (aka Google SGE). It uses Playwright to load the AI panel directly and converts the full response into markdown with Turndown so the output renders just like the built-in `webfetch` tool.
+
+## Features
+
+- Direct navigation to Google AI Mode with stealth browser headers.
+- Waits for the progressive response to stabilise before extraction.
+- Captures headings, lists, tables, and sources from the AI panel.
+- Converts the response to markdown to avoid truncated tool output.
+- Provides rich metadata (response time, source count, table presence) for the assistant model.
+
+## Installation
+
+1. Clone or download this repository.
+2. Install dependencies and build the plugin:
+
+   ```bash
+   bun install
+   bun run build
+   ```
+
+   > Note: If you encounter TypeScript compilation errors, you may need to fix quote escaping issues in the source code.
+
+   > Playwright is declared as a peer dependency. Install it (and Chromium) in the same project that will host the plugin:
+   >
+   > ```bash
+   > bun install
+   > npx playwright install chromium
+   > ```
+   >
+   > Note: Use `npx` instead of `bunx` if bunx is not available.
+
+3. Add the plugin to Opencode. You can either:
+
+   - Drop the built files into your project: copy the entire folder somewhere in your repo and add the relative path in `opencode.json`:
+
+     ```json
+     {
+       "plugin": [
+         "file:///absolute/path/to/google_ai_search/dist/index.js"
+       ]
+     }
+     ```
+
+     > Important: Use absolute paths starting with `file:///` instead of relative paths to avoid module resolution issues.
+
+   - Or publish this package to npm (e.g. `npm publish`) and reference it by name:
+
+     ```json
+     {
+       "plugin": [
+         "opencode-google-ai-search-plugin"
+       ]
+     }
+     ```
+
+4. Restart Opencode. The new tool (`google_ai_search_plus`) will appear in the tool list.
+
+## Usage
+
+Once the plugin is loaded, call the tool from any Opencode session:
+
+```text
+google_ai_search_plus "What is the difference between TypeScript and JavaScript?"
+```
+
+Parameters:
+
+| Name     | Type    | Description                                                       |
+|----------|---------|-------------------------------------------------------------------|
+| `query`  | string  | Question or topic to submit to Google AI Mode.                    |
+| `timeout`| number  | Optional timeout in seconds (default 30, max 120).                |
+| `followUp` | boolean | Treats the query as part of the same conversation (session reuse). |
+
+The tool returns a markdown-formatted answer plus metadata about the response, including source count and whether a comparison table was detected.
+
+## Notes
+
+- Google frequently throttles automated traffic. If you see timeout or “blocking” errors, wait a few minutes or reduce query frequency.
+- The plugin stores no state; each call launches (or reuses) an isolated headless Chromium session via Playwright.
+- Formatting mirrors the built-in `webfetch` tool so Opencode renders the full AI answer without summarising it.
+- You can customise the tool ID by editing `src/index.ts` before publishing.
+
+## Development
+
+- `bun run build` compiles TypeScript to the `dist/` folder (ESM output with type declarations).
+- `bun run clean` removes the build artefacts.
+- Update the version in `package.json` before publishing to npm.
+
+## License
+
+MIT

package/bun.lock

@@ -0,0 +1,39 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "opencode-google-ai-search-plugin",
+      "dependencies": {
+        "turndown": "latest",
+      },
+      "devDependencies": {
+        "@opencode-ai/plugin": "latest",
+        "typescript": "latest",
+      },
+      "peerDependencies": {
+        "@opencode-ai/plugin": "latest",
+        "playwright": "latest",
+      },
+    },
+  },
+  "packages": {
+    "@mixmark-io/domino": ["@mixmark-io/domino@2.2.0", "", {}, "sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw=="],
+
+    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.2.10", "", { "dependencies": { "@opencode-ai/sdk": "1.2.10", "zod": "4.1.8" } }, "sha512-Z1BMqNHnD8AGAEb+kUz0b2SOuiODwdQLdCA4aVGTXqkGzhiD44OVxr85MeoJ5AMTnnea9SnJ3jp9GAQ5riXA5g=="],
+
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.2.10", "", {}, "sha512-SyXcVqry2hitPVvQtvXOhqsWyFhSycG/+LTLYXrcq8AFmd9FR7dyBSDB3f5Ol6IPkYOegk8P2Eg2kKPNSNiKGw=="],
+
+    "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
+
+    "playwright": ["playwright@1.58.2", "", { "dependencies": { "playwright-core": "1.58.2" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A=="],
+
+    "playwright-core": ["playwright-core@1.58.2", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg=="],
+
+    "turndown": ["turndown@7.2.2", "", { "dependencies": { "@mixmark-io/domino": "^2.2.0" } }, "sha512-1F7db8BiExOKxjSMU2b7if62D/XOyQyZbPKq/nUwopfgnHlqXHqQ0lvfUTeUIr1lZJzOPFn43dODyMSIfvWRKQ=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "zod": ["zod@4.1.8", "", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="],
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "opencode-webfetch-plugin",
+  "version": "0.1.0",
+  "description": "An opencode plugin that exposes a webfetch tool capable of human-in-the-loop interaction for handling captchas and logins.",
+  "type": "module",
+  "module": "./src/index.ts",
+  "scripts": {},
+  "keywords": [
+    "opencode",
+    "plugin",
+    "google",
+    "ai",
+    "search"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "jsdom": "^28.1.0",
+    "turndown": "^7.2.2"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "latest",
+    "playwright": "latest"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "latest",
+    "@types/jsdom": "^28.0.0",
+    "@types/mozilla-readability": "^0.2.1",
+    "@types/node": "^25.3.0",
+    "@types/turndown": "^5.0.6",
+    "typescript": "latest"
+  }
+}

package/plan.md

@@ -0,0 +1,45 @@
+# 开发计划 (Development Plan)
+
+基于 `research.md` 的架构设计，针对支持人机协同的 `Opencode-Google-AI-Search-Plugin`（现更偏向通用网页读取与交互插件），制定以下分步开发计划：
+
+## 第一阶段：项目初始化与依赖配置 (Project Setup & Dependencies)
+1. **清理历史代码**：基于原有项目基础，移除特定于“仅限 Google 搜索”的无头代码，为新的单一入口工具做准备。
+2. **安装必要依赖**：
+   - 确保 `playwright` 依赖配置正确。
+   - 安装内容提取和格式化工具：`turndown`, `@mozilla/readability`（可能需要使用 `jsdom` 或在 Playwright 浏览器上下文中直接执行 Readability）。
+   - 安装对应的 TypeScript 类型定义文件。
+
+## 第二阶段：浏览器上下文与生命周期管理 (Browser Context Management)
+1. **实现 BrowserManager 类**：
+   - 管理单例的浏览器实例。
+   - **持久化配置**：使用 `playwright.chromium.launchPersistentContext`，并在项目根目录或指定系统临时目录创建一个 `.userdata` 文件夹，用于存储 Cookies 和 LocalStorage。
+   - **有头模式**：默认配置 `headless: false`，确保人类可以随时看到页面内容并进行干预。
+   - 处理浏览器的启动、页面标签页的创建以及插件关闭时的清理工作。
+
+## 第三阶段：人机协同挂起/恢复机制 (Human-in-the-Loop Mechanism)
+1. **终端交互模块**：利用 Node.js 原生的 `readline` 模块，封装一个 `askForHumanHelp(message)` 函数。该函数会阻塞当前 `Promise`，在终端输出提示信息，并等待用户按下回车键。
+2. **状态监测与拦截逻辑**：
+   - 页面加载 `goto` 时设置合理的超时时间。
+   - （可选/基础版）当 Agent 请求页面时，先尝试加载。如果加载超时，或者通过简单的 URL/DOM 探测发现类似 Cloudflare 的盾、登录墙等特征，主动触发 `askForHumanHelp`。
+   - （进阶版）考虑到启发式探测可能不完善，始终提供一个兜底机制：即使没检测到验证码，只要获取不到核心内容，就可以让用户决定是否介入。
+
+## 第四阶段：页面内容提取与降噪 (Content Extraction & Formatting)
+1. **核心提取逻辑**：在页面加载完成（或人类接管并确认完成后），注入 `@mozilla/readability` 脚本到页面中执行，或者提取 HTML 到 Node 端处理。Readability 能有效去除广告、侧边栏和导航。
+2. **Markdown 转换**：将 Readability 提取出的纯净 HTML片段传递给 `turndown`，转换为高质量的 Markdown 文本，极大降低 LLM Token 消耗。
+
+## 第五阶段：核心工具注册与整合 (Opencode Tool Registration)
+1. **重构 `src/index.ts`**：
+   - 清除原有针对 Google 搜索的多个特定工具。
+   - 仅注册一个核心工具：`webfetch`。
+   - **工具参数**：`url`（必填，目标网址）和 `query`（可选，如果不提供 URL 则作为搜索引擎的搜索词处理）。
+2. **串联流程**：
+   - Agent 调用 `webfetch` -> 检查/启动 BrowserManager -> 新建 Tab 打开 URL -> 检测是否需要人类协助 -> （如果需要）终端挂起并等待人类回车 -> 获取页面 DOM -> Readability + Turndown 转换 -> 返回 Markdown 结果给 Agent。
+
+## 第六阶段：测试与调优 (Testing & Refinement)
+1. 测试正常网页抓取（如 Wikipedia、GitHub 项目页）。
+2. 测试拦截验证网页（手动寻找一个带有 Cloudflare 验证或必须登录的页面，验证挂起机制和回车恢复机制）。
+3. 测试异常处理和容错机制（如用户强行关闭了浏览器窗口等情况的处理）。
+
+---
+
+请确认以上开发计划是否符合您的预期？如果确认无误，我们将进入第一阶段的编码工作。

package/research.md

@@ -0,0 +1,76 @@
+# 针对 Opencode 人机协同交互式浏览器插件的技术调研
+
+## 背景与目标
+
+当前参考项目 `Opencode-Google-AI-Search-Plugin` 展示了如何利用 `@opencode-ai/plugin` 机制封装 Playwright 进行自动化 Google 搜索（无头模式 `headless: true`）。但这种方式面临一个严重问题：**当遇到反爬虫机制（如 Google 的 CAPTCHA）、需要登录才能访问的网页时，Agent 会直接失败（抛出异常）。**
+
+本调研旨在设计一个**支持人机协同、可持久化、高度可控**的 Opencode 浏览器控制插件。Agent（如 LLM）可以通过该插件调度浏览器进行信息检索和操作，同时在遇到拦截或需要授权时，允许人类接管浏览器完成验证或登录操作，随后交还控制权给 Agent。
+
+## 1. 核心技术选型
+
+### 1.1 浏览器引擎控制框架：Playwright 
+**推荐使用 Playwright 而非 Puppeteer**。
+- **原因**：当前 Opencode 已有通过 `peerDependencies` 使用 Playwright 的基础。Playwright 支持更现代的 Web 特性、多浏览器引擎（Chromium, Firefox, WebKit），且在处理跨域（iframe）和等待机制（Auto-waiting）上比 Puppeteer 更智能。
+- **实现方式**：可以继续采用动态导入 `import("playwright")` 结合 `/tmp/node_modules/playwright` 的后备机制。
+
+### 1.2 浏览器运行模式：Persistent Context (持久化上下文) 与有头模式
+当前的 Google 搜索插件每次调用启动的是临时会话（无持久化），且是无头模式（`headless: true`）。
+针对我们的新需求，需要做以下改动：
+- **Headless 模式切换**：默认可以后台运行，但必须支持开启 `headless: false`（有头模式），从而让用户能看到界面进行登录、过验证码等操作。
+- **持久化数据 (userDataDir)**：必须使用 `playwright.chromium.launchPersistentContext(userDataDir, options)` 替代普通的 `launch`。这样用户的登录状态、Cookies、LocalStorage 都会被保存到本地硬盘。下次启动 Agent 时，不再需要重新登录。
+
+## 2. 架构设计与交互流程
+
+### 2.1 基础架构
+插件应在初始化时维护一个全局单例的 Browser Context（持久化），并在其上暴露一组供 Agent 使用的 Tools (函数集)。
+
+### 2.2 核心暴露工具 (Tools) 规划
+针对 Opencode 的 Agent，为了最大化保持 Agent 职责单一且减少不可控的自动化失败（如复杂的 DOM 变化、验证码、登录墙），我们**仅对外暴露一个核心 Tool**：
+
+1. `webfetch(url_or_query)`: 获取指定网页的最终渲染内容或执行搜索。
+   - **输入**: 一个 URL，或者一个搜索关键词（插件内部可将其转化为特定搜索引擎的 URL）。
+   - **输出**: 该网页（或搜索结果页面）的主体内容，通常转换为高质量的 Markdown 格式，去除了广告、导航栏等噪音。
+
+**设计理念**：所有复杂的中间过程（如登录、重定向、CAPTCHA 人机验证、甚至翻页寻找特定信息）**均不由 Agent 自动处理，而是由插件内部拦截并转移给人类执行**。
+
+### 2.3 人机验证 (Human-in-the-loop) 机制设计
+当 Agent 调用 `webfetch` 请求一个页面时，插件内部的执行流程如下：
+
+1. **发起请求**：插件使用 Playwright 打开目标 URL。
+2. **状态监测**：插件监听页面加载后的状态。如果检测到以下情况（可通过 URL 变化、特定元素出现等启发式规则判断）：
+   - 被重定向到了登录页面（如 `/login`, `auth0.com` 等）。
+   - 出现了典型的反爬虫挑战（如 Cloudflare 的 "Checking your browser..."，Google 的 CAPTCHA）。
+   - 页面迟迟未加载出���期的主体内容。
+3. **人类接管**：
+   - 插件主动**挂起**当前 `webfetch` 的 Promise。
+   - 插件在 Opencode 终端输出高亮提示：“[需要人类协助] 访问 `https://xxx` 遇到障碍（如登录/验证码）。请在弹出的浏览器窗口中完成操作，获取到最终目标页面后，在终端按回车键继续...”。
+   - （可选）如果浏览器窗口在后台，插件尝试将其唤起至前台。
+4. **人类操作**：人类在真实的浏览器窗口中输入账号密码、点选验证码、甚至手动点击搜索结果跳转到目标详情页。
+5. **恢复与提取**：
+   - 人类确认操作完成并在终端按下回车。
+   - 插件恢复 Promise 的执行，此时直接提取**当前浏览器所处页面**的 DOM 结构。
+   - 将提取的 HTML 通过 `turndown`（结合 Readability 算法）转换为 Markdown，并返回给 Agent。
+
+这种设计将最困难的“导航和越权”交给了人类，而 Agent 只需专注于“提出需求 (`webfetch`)”和“分析结果 (Markdown)”。
+
+## 3. 技术难点与解决方案
+
+### 3.1 动态 Headless 切换的局限
+**痛点**：Playwright 启动后无法动态切换无头和有头模式。一直开着有头模式（弹出窗口）会打扰用户正常的编码工作。
+**解决方案**：
+1. **方案 A (默认有头并最小化)**：使用 `headless: false`，但通过参数/系统命令将其启动时最小化或放置在后台。
+2. **方案 B (CDP Attach - 推荐)**：用户自己电脑上开一个开启了 debug 端口的 Chrome (`chrome.exe --remote-debugging-port=9222`)。插件不去 `launch` 浏览器，而是通过 `playwright.chromium.connectOverCDP('http://localhost:9222')` 接入。这样用户平时就在这个 Chrome 里正常上网、保持登录，Agent 在后台操控新建的 Tab。当需要验证时，用户切到该 Tab 即可。
+
+### 3.2 页面内容的 Markdown 提取
+为了让大模型 (LLM) 高效阅读网页，不能直接返回完整 HTML（Token 消耗极大且噪音多）。
+**解决方案**：
+参考原项目，使用 `turndown` 库，并结合 Playwright 的 `page.evaluate()` 清理不必要的 script、style、nav、footer 等标签，提取主体内容的文本。可以结合 Mozilla 的 `Readability.js` 来提取核心正文。
+
+### 3.3 状态管理与防卡死
+**痛点**：网络状况差或者死链会导致 Agent 长时间等待。
+**解决方案**：
+所有的 Tool 调用（`goto`, `click`）必须设置合理的 `timeout`。当发生超时时，捕获异常并告诉 Agent "Timeout occurred"，让 Agent 决定是重试、放弃还是请求人类帮助。
+
+## 5. 总结
+
+实现这样一个支持人机协作的 Opencode 浏览器插件在技术上是完全可行的。最核心的转变在于从**"一次性的无头自动化脚本"**转变为**"长期存活的、由人类和 Agent 共享的持久化浏览器上下文"**。通过赋予 Agent 遇到障碍时主动寻求人类帮助的能力，将极大拓宽该插件在复杂网络环境（反爬、强登录态网站）下的应用边界。

package/src/BrowserManager.ts

@@ -0,0 +1,223 @@
+import type { ToolContext } from "@opencode-ai/plugin";
+
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+import { HumanInteractor } from './HumanInteractor.js';
+import { Extractor } from './Extractor.js';
+import type { BrowserContext, Page } from 'playwright';
+
+type PlaywrightModule = typeof import('playwright');
+
+export class BrowserManager {
+  private context: BrowserContext | null = null;
+  private page: Page | null = null;
+  private readonly playwright: PlaywrightModule;
+  private readonly client: any;
+
+  constructor(playwright: PlaywrightModule, client: any) {
+    this.playwright = playwright;
+    this.client = client;
+  }
+
+  /**
+   * Initializes the persistent context if not already done.
+   */
+  public async ensureContext(): Promise<void> {
+    let isConnected = false;
+    if (this.context && this.page) {
+      try {
+        // Simple check to see if the page is still open and connected
+        isConnected = !this.page.isClosed();
+      } catch (e) {
+        isConnected = false;
+      }
+    }
+
+    if (isConnected) {
+      return;
+    }
+
+    // Clean up just in case
+    await this.dispose();
+
+    const userDataDir = path.resolve(os.homedir(), '.cache/opencode/user-data');
+    if (!fs.existsSync(userDataDir)) {
+      fs.mkdirSync(userDataDir, { recursive: true });
+    }
+
+    // Launch a persistent context with extension support
+    const extensionPath = path.resolve(os.homedir(), '.cache/opencode/extensions');
+    const extensions: string[] = [];
+    if (fs.existsSync(extensionPath)) {
+      const dirs = fs.readdirSync(extensionPath).map(d => path.join(extensionPath, d));
+      extensions.push(...dirs.filter(d => fs.statSync(d).isDirectory()));
+    }
+
+    const launchOptions: Parameters<typeof this.playwright.chromium.launchPersistentContext>[1] = {
+      headless: false,
+      args: [
+        '--no-sandbox',
+        '--disable-dev-shm-usage',
+        '--disable-blink-features=AutomationControlled',
+        '--disable-features=VizDisplayCompositor',
+        '--window-size=1280,720',
+        ...(extensions.length > 0 ? [
+          `--disable-extensions-except=${extensions.join(',')}`,
+          `--load-extension=${extensions.join(',')}`
+        ] : []),
+      ],
+      viewport: { width: 1280, height: 720 },
+    };
+
+    this.context = await this.playwright.chromium.launchPersistentContext(userDataDir, launchOptions);
+
+    // Create a new page or use the default one created by launchPersistentContext
+    const pages = this.context.pages();
+    if (pages.length > 0) {
+      this.page = pages[0];
+    } else {
+      this.page = await this.context.newPage();
+    }
+
+    // Mask webdriver
+    await this.page.addInitScript(() => {
+      Object.defineProperty(navigator, 'webdriver', {
+        get: () => false,
+      });
+
+      const chrome = (window as any).chrome;
+      if (chrome && chrome.runtime && chrome.runtime.onConnect) {
+        delete chrome.runtime.onConnect;
+      }
+    });
+  }
+
+  /**
+   * Navigates to a URL and tries to extract the content.
+   * Prompts the user via terminal if it encounters a captcha or login screen.
+   */
+  public async fetchWebpage(url: string, timeout: number, ctx: ToolContext): Promise<string> {
+    await this.ensureContext();
+    if (!this.page) throw new Error('Page not initialized');
+
+    console.log(`\nNavigating to: ${url}`);
+    
+    // Add a listener to handle abortions
+    const onAbort = () => {
+      console.log('Operation aborted by user or timeout.');
+    };
+    ctx.abort.addEventListener('abort', onAbort);
+
+    try {
+      // Go to the requested URL
+      await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout }).catch((e) => {
+        console.warn(`Navigation might have timed out or failed partially: ${e.message}`);
+      });
+
+      // too fast
+      await this.page.waitForTimeout(2000);
+
+      // Basic heuristic to check if human intervention is needed
+      const needsHelp = await this.detectBlockers(this.page);
+      
+      if (needsHelp.blocked) {
+        await HumanInteractor.askForHumanHelp(`The page appears to be blocked or requires login.\nReason: ${needsHelp.reason}\nURL: ${this.page.url()}`, ctx, this.client, () => this.detectBlockers(this.page));
+      } else {
+        // Wait a little bit for dynamic content if not blocked
+        await this.page.waitForTimeout(2000);
+      }
+
+      // Allow one more check in case the user didn't fully resolve it, or if it redirected
+      const needsHelpAgain = await this.detectBlockers(this.page);
+      if (needsHelpAgain.blocked) {
+        await HumanInteractor.askForHumanHelp(`Still detected a blocker.\nReason: ${needsHelpAgain.reason}\nPlease complete the action and try again.`, ctx, this.client, () => this.detectBlockers(this.page));
+      }
+
+      // Extract content as Markdown
+      console.log('Extracting page content...');
+      const markdown = await Extractor.extractMarkdown(this.page, this.page.url());
+      return markdown;
+    } finally {
+      ctx.abort.removeEventListener('abort', onAbort);
+    }
+  }
+
+  /**
+   * Detects if the current page is blocked by Captcha, Cloudflare, or a Login wall.
+   */
+  private async detectBlockers(page: Page | null): Promise<{ blocked: boolean; reason?: string }> {
+    try {
+      if (page == null) return {blocked: false}
+      const url = page.url();
+
+      // 0. Check for about:blank (no network connection)
+      if (url === 'about:blank') {
+        return { blocked: true, reason: 'No network connection. Please check your internet and press Enter to continue.' };
+      }
+
+      // 1. Check URL patterns for logins or known captchas
+      if (url.includes('/login') || url.includes('/signin') || url.includes('auth0.com')) {
+        return { blocked: true, reason: 'Login page detected.' };
+      }
+
+      // 2. Check for Cloudflare Turnstile or similar challenge pages
+      const isCloudflare = await page.evaluate(() => {
+        const title = document.title.toLowerCase();
+        const text = document.body.innerText.toLowerCase();
+        
+        if (title.includes('just a moment') || title.includes('attention required!')) {
+          return true;
+        }
+        if (text.includes('checking your browser before accessing') || text.includes('enable javascript and cookies to continue')) {
+          return true;
+        }
+        return false;
+      });
+
+      if (isCloudflare) {
+        return { blocked: true, reason: 'Cloudflare challenge detected.' };
+      }
+
+      // 3. Check for typical Captcha iframes (reCAPTCHA, hCaptcha)
+      const hasCaptcha = await page.evaluate(() => {
+        const iframes = Array.from(document.querySelectorAll('iframe'));
+        return iframes.some((f) => {
+          const src = f.src.toLowerCase();
+          return src.includes('recaptcha') || src.includes('hcaptcha') || src.includes('turnstile');
+        });
+      });
+
+      if (hasCaptcha) {
+        // Sometimes captchas are invisible, but if they are visible, we might be blocked.
+        return { blocked: true, reason: 'Captcha iframe detected on page.' };
+      }
+
+      // 4. Check for Google "Sorry" page
+      if (url.includes('/sorry/')) {
+        return { blocked: true, reason: 'Google automated access blocker detected.' };
+      }
+
+    } catch (e) {
+      console.error('Error detecting blockers:', e);
+    }
+
+    return { blocked: false };
+  }
+
+  /**
+   * Close the browser context safely.
+   */
+  public async dispose(): Promise<void> {
+    try {
+      if (this.context) {
+        await this.context.close().catch(() => {});
+      }
+    } catch (e) {
+      // Ignore errors on close
+    } finally {
+      this.context = null;
+      this.page = null;
+    }
+  }
+}

package/src/Extractor.ts

@@ -0,0 +1,47 @@
+import { Readability } from '@mozilla/readability';
+import { JSDOM } from 'jsdom';
+import TurndownService from 'turndown';
+import type { Page } from 'playwright';
+
+export class Extractor {
+  /**
+   * Extracts the main content of a Playwright page and converts it to Markdown.
+   * @param page The Playwright Page object.
+   * @param url The current URL of the page.
+   * @returns The main content formatted as Markdown.
+   */
+  static async extractMarkdown(page: Page, url: string): Promise<string> {
+    // 1. Get full HTML content from the page
+    const htmlContent = await page.content();
+    
+    // 2. Parse HTML using JSDOM
+    const doc = new JSDOM(htmlContent, { url });
+
+    // 3. Extract core content using Readability
+    const reader = new Readability(doc.window.document);
+    const article = reader.parse();
+
+    if (!article || !article.content) {
+      // Fallback if Readability fails
+      const bodyText = await page.evaluate(() => document.body.innerText);
+      return `Failed to extract main article content.\n\nRaw Body Text:\n${bodyText.substring(0, 5000)}`;
+    }
+
+    // 4. Convert extracted HTML to clean Markdown
+    const turndownService = new TurndownService({
+      headingStyle: 'atx',
+      hr: '---',
+      bulletListMarker: '-',
+      codeBlockStyle: 'fenced',
+      emDelimiter: '*',
+    });
+
+    // Remove noisy elements just in case
+    turndownService.remove(['script', 'style', 'noscript', 'iframe']);
+
+    let markdown = turndownService.turndown(article.content);
+    
+    // Format the output
+    return `# ${article.title || 'Extracted Page Content'}\n\n**Source URL:** ${url}\n\n---\n\n${markdown}`;
+  }
+}

package/src/HumanInteractor.ts

@@ -0,0 +1,46 @@
+import type { ToolContext } from '@opencode-ai/plugin'
+import { resolve } from 'dns';
+import { title } from 'process';
+
+const sleep = (t: number) => new Promise(resolve => {
+  setTimeout(() => {
+    resolve(null)
+  }, t);
+})
+export class HumanInteractor {
+  /**
+   * Instructs the LLM to pause and asks the human to resolve the issue in the browser.
+   * Pre-fills the TUI prompt so the user can just press Enter to continue.
+   */
+  static async askForHumanHelp (
+    message: string,
+    ctx: ToolContext,
+    client: any,
+    checker: any,
+  ): Promise<void> {
+    try {
+
+      while(true) {
+        // Show a toast to notify the user immediately
+        client?.tui?.showToast({
+          body: {
+            title: 'Browser Action Required',
+            message,
+            variant: 'warning'
+          }
+          // duration: 10000
+        })
+
+        await sleep(5000)
+        const res = await checker();
+        if (res.blocked) {
+          continue
+        } else {
+          break
+        }
+      }
+    } catch (e) {
+      console.error(e)
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+import { type Plugin, tool } from "@opencode-ai/plugin";
+import { BrowserManager } from "./BrowserManager.js";
+
+type PlaywrightModule = typeof import("playwright");
+
+const DEFAULT_TIMEOUT = 30_000;
+const MAX_TIMEOUT = 120_000;
+
+let globalManager: BrowserManager | null = null;
+
+export const WebfetchPlugin: Plugin = async ({ client }) => {
+  const WebfetchTool = tool({
+    description: "Fetch a webpage's main content in markdown.",
+    args: {
+      url: tool.schema.string().describe("The URL to fetch."),
+      // timeout: tool.schema
+      //   .number()
+      //   .min(5)
+      //   .max(120)
+      //   .optional()
+      //   .describe("Timeout in seconds (default: 30, max: 120)"),
+    },
+    async execute(params: any, ctx: any) {
+      if (!globalManager) {
+        const playwright = await loadPlaywright();
+        globalManager = new BrowserManager(playwright, client);
+      }
+      
+      const manager = globalManager;
+      const timeoutMs = Math.min((params.timeout ?? DEFAULT_TIMEOUT / 1000) * 1000, MAX_TIMEOUT);
+
+      const abortHandler = () => {
+        manager.dispose().catch(() => undefined);
+      };
+      ctx.abort.addEventListener("abort", abortHandler, { once: true });
+
+      try {
+        let targetUrl = params.url;
+        // If it's not a valid URL (e.g., just a string query), convert to Google search
+        if (!/^https?:\/\//i.test(targetUrl)) {
+          targetUrl = `https://www.google.com/search?q=${encodeURIComponent(targetUrl)}`;
+        }
+
+        const markdownResult = await manager.fetchWebpage(targetUrl, timeoutMs, ctx);
+
+        ctx.metadata({
+          title: `Webfetch: ${targetUrl}`,
+          metadata: {
+            url: targetUrl,
+            length: markdownResult.length,
+          },
+        });
+
+        return markdownResult;
+      } catch (error) {
+        throw error;
+      } finally {
+        ctx.abort.removeEventListener("abort", abortHandler);
+      }
+    },
+  });
+
+  return {
+    tool: {
+      webfetch: WebfetchTool
+    }
+  };
+};
+
+async function loadPlaywright(): Promise<PlaywrightModule> {
+  try {
+    return await import("playwright");
+  } catch (error) {
+    try {
+      // @ts-ignore
+      return await import("/tmp/node_modules/playwright");
+    } catch {
+      throw new Error(
+        "webfetch plugin requires Playwright. Install it with: bun install playwright && bunx playwright install chromium",
+        { cause: error },
+      );
+    }
+  }
+}
+
+export default WebfetchPlugin;

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}