pi-web-toolkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wade Huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# pi-web-toolkit
+
+Web research toolkit for [pi](https://pi.dev) agents. Search, fetch, browse, and batch-read the web.
+
+## Features
+
+| Tool | Purpose |
+|------|---------|
+| **`web_search`** | Search the web via SearXNG |
+| **`web_fetch`** | Fetch a single static page as clean markdown |
+| **`web_browse`** | Interact with a page (click, scroll, fill) then extract content |
+| **`web_batch_fetch`** | Fetch 2–10 pages in parallel for research synthesis |
+
+## Installation
+
+### Option 1: From npm (recommended)
+
+```bash
+pi install pi-web-toolkit
+```
+
+### Option 2: From GitHub
+
+```bash
+pi install git:github.com/Wade11s/pi-web-toolkit
+```
+
+## Requirements
+
+- **Node.js ≥ 20** — for running pi extensions
+- **SearXNG** — for `web_search`
+  ```bash
+  # Set your SearXNG instance URL (default: http://localhost:8080)
+  export SEARXNG_URL="http://localhost:8080"
+
+  # Self-host with Docker
+  docker run -d -p 8080:8080 -v searxng:/etc/searxng searxng/searxng
+  ```
+- **scrapling** — for `web_fetch` and `web_batch_fetch`
+  ```bash
+  # recommended: install scrapling via uv
+  uv tool install "scrapling[all]"
+  scrapling install
+  ```
+- **agent-browser** — for `web_browse`
+  ```bash
+  npm i -g agent-browser && agent-browser install
+  ```
+  Verify installation:
+  ```bash
+  agent-browser doctor
+  ```
+
+## Project Structure
+
+```
+pi-web-toolkit/
+├── extensions/
+│   ├── utils/
+│   │   └── scrapling.ts    # scrapling CLI wrapper
+│   ├── web_search.ts       # web_search
+│   ├── web_fetch.ts        # web_fetch
+│   ├── web_browse.ts       # web_browse (agent-browser)
+│   └── web_batch_fetch.ts  # web_batch_fetch
+├── docs/
+│   ├── tools.md
+│   └── guide.md
+├── package.json
+├── README.md
+└── LICENSE
+```
+
+## Reference
+
+- [Tool Reference](docs/tools.md) — Full parameter specs and usage examples for each tool.
+- [Usage Guide](docs/guide.md) — Decision tree and tool comparison.
+
+## License
+
+MIT

package/docs/guide.md

@@ -0,0 +1,41 @@
+# Usage Guide
+
+## Which Tool When? — Decision Tree
+
+```
+User asks about something external / current
+│
+├─→ web_search("...")
+│   │
+│   ├─→ 1 relevant result?
+│   │   └─→ web_fetch(url)                     ← static page
+│   │   OR
+│   │   └─→ web_browse(url, actions)           ← needs interaction
+│   │
+│   └─→ 2–5 relevant results?
+│       ├─→ All static pages?
+│       │   └─→ web_batch_fetch(urls[])        ← parallel fetch
+│       └─→ Some need interaction?
+│           └─→ web_fetch (static ones)
+│               web_browse (interactive ones)  ← sequential
+│
+└─→ User provides a URL directly
+    ├─→ Static / loads on first request?
+    │   └─→ web_fetch(url)
+    └─→ Needs clicking / scrolling / waiting?
+        └─→ web_browse(url, actions)
+```
+
+---
+
+## Tool Comparison
+
+| | `web_fetch` | `web_browse` | `web_batch_fetch` |
+|--|-------------|--------------|-------------------|
+| **Pages** | 1 | 1 | 2–10 |
+| **Browser** | Yes (scrapling) | Yes (agent-browser) | Yes (scrapling) |
+| **Interaction** | ❌ No | ✅ Click, fill, scroll, wait | ❌ No |
+| **Selector** | ✅ Per-URL | ✅ Final state | ✅ Applied to all |
+| **Stealthy** | ✅ Yes | ❌ No (planned) | ✅ Yes |
+| **Speed** | Fast | Slower (browser ops) | Medium (parallel) |
+| **Best for** | Articles, docs, blogs | SPAs, forms, pagination | Research synthesis |

package/docs/tools.md

@@ -0,0 +1,151 @@
+# Tool Reference
+
+## `web_search`
+
+Search the web via SearXNG. Returns ranked results with title, URL, and snippet.
+
+```typescript
+{
+  query: string,           // Search query
+  language?: string,       // Language code (en, de, fr...). Default: "auto"
+  results?: number,        // Max results (1–50). Default: 10
+}
+```
+
+**When to use:** The user asks about current events, facts, or anything requiring up-to-date information. This is always the **first step** of web research.
+
+---
+
+## `web_fetch`
+
+Fetch a single page and convert it to clean markdown. Uses scrapling's browser automation for JS-heavy sites.
+
+```typescript
+{
+  url: string,             // Full URL
+  selector?: string,       // CSS selector to extract only a specific area
+  stealthy?: boolean,      // Anti-bot mode for protected sites. Default: false
+}
+```
+
+**When to use:**
+- After `web_search` finds a relevant result
+- The page is static or loads its content on first request
+- You need to read **one** article, doc, or blog post
+
+**Example flow:**
+```
+User: "What's the latest Rust release?"
+→ web_search("latest Rust programming language release")
+→ web_fetch("https://blog.rust-lang.org/2026/06/02/maintainers-fund/")
+→ Agent answers with full context
+```
+
+---
+
+## `web_browse`
+
+Open a real browser, perform a chain of actions (click, fill, scroll, wait), then extract content.
+
+Uses the [agent-browser](https://github.com/vercel-labs/agent-browser) CLI for native browser automation via Chrome CDP.
+
+```typescript
+{
+  url: string,
+  actions: Array<
+    | { type: "click", selector: string }
+    | { type: "fill", selector: string, value: string }
+    | { type: "type", selector: string, value: string }
+    | { type: "press", key: string, selector?: string }
+    | { type: "wait", ms: number }
+    | { type: "wait_selector", selector: string, state?: "attached" | "visible" | "hidden" }
+    | { type: "scroll", direction: "down" | "up" | "bottom" | "top", amount?: number }
+  >,
+  selector?: string,       // Extract content from final page state
+  headless?: boolean,      // Default: true
+  timeout?: number,        // Overall browser batch timeout (ms). Default: 30000
+}
+```
+
+**When to use:**
+- The page requires **clicking** before showing target content (e.g. "Load more", pagination, tab switching)
+- The page requires **filling a form** (e.g. search box, login)
+- The page requires **scrolling** to load lazy content (infinite scroll)
+- The page requires **waiting** for JS to render content (SPA)
+
+**Example flows:**
+
+```
+# Click "Load more" twice, then extract articles
+→ web_browse({
+    url: "https://news.example.com",
+    actions: [
+      { type: "click", selector: "button.load-more" },
+      { type: "wait", ms: 1000 },
+      { type: "click", selector: "button.load-more" },
+      { type: "wait", ms: 1000 },
+    ],
+    selector: "article"
+  })
+
+# Fill a search form and press Enter
+→ web_browse({
+    url: "https://duckduckgo.com",
+    actions: [
+      { type: "fill", selector: "#searchbox_input", value: "async rust" },
+      { type: "press", key: "Enter" },
+      { type: "wait_selector", selector: "[data-result]", state: "visible" },
+    ],
+    selector: "[data-result]"
+  })
+
+# Scroll to bottom of infinite-scroll page
+→ web_browse({
+    url: "https://social.example.com/user/posts",
+    actions: [
+      { type: "scroll", direction: "bottom" },
+      { type: "wait", ms: 1500 },
+      { type: "scroll", direction: "bottom" },
+    ],
+    selector: ".post"
+  })
+```
+
+---
+
+## `web_batch_fetch`
+
+Fetch multiple pages in parallel and return aggregated content.
+
+```typescript
+{
+  urls: string[],          // 1–10 URLs
+  selector?: string,       // CSS selector applied to ALL pages
+  stealthy?: boolean,      // Default: false
+  max_concurrency?: number // Parallel fetches (1–5). Default: 3
+}
+```
+
+**When to use:**
+- After `web_search` returns **2–5 relevant results** that you want to read simultaneously
+- Cross-referencing multiple sources for the same topic
+- Comparing implementations across different docs/pages
+- Research synthesis requiring multiple sources
+
+**NOT for:** Single pages (use `web_fetch` — simpler and supports per-URL stealthy mode).
+
+**Example flow:**
+```
+User: "Compare Python asyncio, Trio, and curio"
+→ web_search("Python asyncio vs Trio vs curio comparison")
+→ web_batch_fetch({
+    urls: [
+      "https://docs.python.org/3/library/asyncio.html",
+      "https://trio.readthedocs.io/",
+      "https://curio.readthedocs.io/",
+    ],
+    selector: "article, .section, main",
+    max_concurrency: 3,
+  })
+→ Agent synthesizes comparison from all 3 sources
+```

package/extensions/utils/scrapling.ts

@@ -0,0 +1,36 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Run a scrapling CLI command with optional abort signal.
+ */
+export function runScrapling(
+  args: string[],
+  signal?: AbortSignal,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve) => {
+    const proc = spawn("scrapling", args, { shell: false, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    proc.on("close", (code, closeSignal) => {
+      const exitCode = code ?? 1;
+      const signalMessage = closeSignal ? `Process terminated by ${closeSignal}` : "";
+      resolve({ stdout, stderr: stderr || signalMessage, exitCode });
+    });
+    proc.on("error", (err) => resolve({ stdout, stderr: err.message, exitCode: 1 }));
+
+    if (signal) {
+      const kill = () => {
+        proc.kill("SIGTERM");
+      };
+      if (signal.aborted) kill();
+      else signal.addEventListener("abort", kill, { once: true });
+    }
+  });
+}

package/extensions/web_batch_fetch.ts

@@ -0,0 +1,249 @@
+/**
+ * Web Batch Fetch Extension — Concurrent multi-page fetching
+ *
+ * Provides a `web_batch_fetch` tool that fetches multiple URLs in parallel
+ * and returns their content as a single aggregated result.
+ *
+ * Use web_batch_fetch when the agent needs to read 2–5 pages at once
+ * (e.g., after web_search returns multiple relevant results).
+ *
+ * For a single page, use `web_fetch` instead — it has finer control
+ * (stealthy mode, per-URL selectors) and is simpler.
+ */
+
+import {
+  defineTool,
+  type ExtensionAPI,
+  truncateHead,
+  formatSize,
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { runScrapling } from "./utils/scrapling";
+
+interface FetchTask {
+  url: string;
+  tmpFile: string;
+}
+
+async function fetchOne(
+  task: FetchTask,
+  selector: string | undefined,
+  stealthy: boolean,
+  signal?: AbortSignal,
+): Promise<{ url: string; content: string; size: number; ok: boolean; error?: string }> {
+  const cmd = stealthy ? "stealthy-fetch" : "fetch";
+  const args = ["extract", cmd, task.url, task.tmpFile, "--ai-targeted"];
+  if (selector) args.push("--css-selector", selector);
+
+  const { stderr, exitCode } = await runScrapling(args, signal);
+
+  if (exitCode !== 0) {
+    // Fallback to GET
+    const fallback = await runScrapling(["extract", "get", task.url, task.tmpFile, "--ai-targeted"], signal);
+    if (fallback.exitCode !== 0) {
+      return { url: task.url, content: "", size: 0, ok: false, error: stderr || fallback.stderr };
+    }
+  }
+
+  try {
+    const content = await fs.promises.readFile(task.tmpFile, "utf-8");
+    const stats = await fs.promises.stat(task.tmpFile);
+    return { url: task.url, content, size: stats.size, ok: true };
+  } catch (err: any) {
+    return { url: task.url, content: "", size: 0, ok: false, error: err.message };
+  }
+}
+
+async function mapWithConcurrencyLimit<TIn, TOut>(
+  items: TIn[],
+  concurrency: number,
+  fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+  if (items.length === 0) return [];
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  const results: TOut[] = new Array(items.length);
+  let nextIndex = 0;
+
+  const workers = new Array(limit).fill(null).map(async () => {
+    while (true) {
+      const current = nextIndex++;
+      if (current >= items.length) return;
+      results[current] = await fn(items[current], current);
+    }
+  });
+
+  await Promise.all(workers);
+  return results;
+}
+
+export const WebBatchFetchParamsSchema = Type.Object({
+  urls: Type.Array(Type.String(), {
+    description: "List of URLs to fetch (2–5 recommended)",
+    minItems: 1,
+    maxItems: 10,
+  }),
+  selector: Type.Optional(Type.String({
+    description: "CSS selector applied to ALL pages to extract only relevant content",
+  })),
+  stealthy: Type.Optional(Type.Boolean({
+    description: "Use stealthy mode for all requests. Default: false",
+    default: false,
+  })),
+  max_concurrency: Type.Optional(Type.Integer({
+    description: "Max parallel fetches (1–5). Default: 3",
+    minimum: 1,
+    maximum: 5,
+    default: 3,
+  })),
+});
+
+export type WebBatchFetchInput = Static<typeof WebBatchFetchParamsSchema>;
+
+const webBatchFetchTool = defineTool({
+  name: "web_batch_fetch",
+  label: "Web Batch Fetch",
+  description: [
+    "Fetch multiple web pages in parallel and return their content aggregated.",
+    "Use web_batch_fetch AFTER web_search when there are 2–5 relevant results",
+    "that the agent wants to read simultaneously for comparison or synthesis.",
+    "For a single page, use web_fetch instead.",
+    `Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; if truncated, full output is saved to a temp file.`,
+  ].join(" "),
+  promptSnippet: "Fetch multiple URLs in parallel for research",
+  promptGuidelines: [
+    "Use web_batch_fetch when web_search returns multiple (2–5) relevant pages and the agent needs to read them all.",
+    "Use web_batch_fetch for cross-referencing sources, comparing implementations, or synthesizing research from multiple sites.",
+    "For a single URL, always use web_fetch — it supports per-URL selectors and stealthy mode.",
+    "If a page in the batch fails, the tool reports the error but continues with the others.",
+    "Keep batch sizes small (≤5) to avoid overwhelming the browser and token budget.",
+  ],
+  parameters: WebBatchFetchParamsSchema,
+
+  async execute(_toolCallId, params, signal, onUpdate) {
+    const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-batch-"));
+    const tasks: FetchTask[] = params.urls.map((url, i) => ({
+      url,
+      tmpFile: path.join(tmpDir, `page-${i}.md`),
+    }));
+    let fullOutputPath: string | undefined;
+
+    try {
+      const concurrency = Math.floor(Math.min(5, Math.max(1, params.max_concurrency ?? 3)));
+      onUpdate?.({ content: [{ type: "text", text: `Fetching ${tasks.length} pages with concurrency ${concurrency}...` }], details: {} });
+
+      const results = await mapWithConcurrencyLimit(
+        tasks,
+        concurrency,
+        (task, index) => {
+          onUpdate?.({ content: [{ type: "text", text: `Fetching ${task.url} (${index + 1}/${tasks.length})...` }], details: {} });
+          return fetchOne(task, params.selector, params.stealthy ?? false, signal);
+        },
+      );
+
+      const successCount = results.filter((r) => r.ok).length;
+      const lines: string[] = [
+        `Batch fetch: ${successCount}/${results.length} succeeded`,
+        "",
+      ];
+
+      for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        lines.push(`--- Page ${i + 1}: ${r.url} ---`);
+        if (r.ok) {
+          lines.push(`Size: ${r.size} bytes`);
+          lines.push("");
+          lines.push(r.content);
+        } else {
+          lines.push(`ERROR: ${r.error || "unknown error"}`);
+        }
+        lines.push("");
+      }
+
+      const rawText = lines.join("\n");
+      const truncation = truncateHead(rawText, {
+        maxLines: DEFAULT_MAX_LINES,
+        maxBytes: DEFAULT_MAX_BYTES,
+      });
+
+      let finalText = truncation.content;
+      if (truncation.truncated) {
+        const fullOutputDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-web-batch-"));
+        fullOutputPath = path.join(fullOutputDir, "output.txt");
+        await fs.promises.writeFile(fullOutputPath, rawText, "utf-8");
+        finalText += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). Full output saved to: ${fullOutputPath}]`;
+      }
+
+      onUpdate?.({ content: [{ type: "text", text: `Batch complete: ${successCount}/${results.length} succeeded` }], details: {} });
+      return {
+        content: [{ type: "text", text: finalText }],
+        details: {
+          urls: params.urls,
+          succeeded: successCount,
+          failed: results.length - successCount,
+          results: results.map((r) => ({ url: r.url, ok: r.ok, size: r.size })),
+          fullOutputPath,
+        },
+      };
+    } catch (err: any) {
+      throw new Error(`Batch fetch failed: ${err.message ?? err}`);
+    } finally {
+      // Cleanup tmp files
+      try {
+        for (const task of tasks) {
+          try { fs.unlinkSync(task.tmpFile); } catch { /* ignore */ }
+        }
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      } catch { /* ignore */ }
+    }
+  },
+
+  renderCall(args, theme) {
+    let text = theme.fg("toolTitle", theme.bold("web_batch_fetch "));
+    text += theme.fg("muted", `${args.urls?.length ?? 0} URLs`);
+    if (args.selector) {
+      text += theme.fg("dim", ` selector=${args.selector}`);
+    }
+    return new Text(text, 0, 0);
+  },
+
+  renderResult(result, { expanded, isPartial }, theme) {
+    if (isPartial) {
+      return new Text(theme.fg("warning", "Batch fetching..."), 0, 0);
+    }
+    const details = result.details as {
+      succeeded?: number;
+      failed?: number;
+      urls?: string[];
+      results?: Array<{ url: string; ok: boolean; size?: number }>;
+      fullOutputPath?: string;
+    } | undefined;
+    const total = details?.urls?.length ?? 0;
+    const ok = details?.succeeded ?? 0;
+    let text = theme.fg("success", `✓ ${ok}/${total} fetched`);
+    if (details?.failed) {
+      text += theme.fg("error", ` (${details.failed} failed)`);
+    }
+    if (expanded && details?.results) {
+      for (const r of details.results) {
+        text += `\n  ${r.ok ? theme.fg("success", "✓") : theme.fg("error", "✗")} ${theme.fg("dim", r.url)}`;
+        if (r.size) {
+          text += theme.fg("muted", ` ${formatSize(r.size)}`);
+        }
+      }
+    }
+    if (expanded && details?.fullOutputPath) {
+      text += `\n${theme.fg("dim", `Full output: ${details.fullOutputPath}`)}`;
+    }
+    return new Text(text, 0, 0);
+  },
+});
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(webBatchFetchTool);
+}

package/extensions/web_browse.ts

@@ -0,0 +1,415 @@
+/**
+ * Web Browse Extension — Interactive browser automation via agent-browser
+ *
+ * Provides a `web_browse` tool for multi-step page interaction using the
+ * agent-browser CLI (https://github.com/vercel-labs/agent-browser).
+ *
+ * Use web_browse when a page requires interaction (clicking, scrolling,
+ * filling forms, waiting for dynamic content) BEFORE its target content
+ * becomes available.
+ *
+ * For static pages that need no interaction, use `web_fetch` instead.
+ */
+
+import {
+  defineTool,
+  type ExtensionAPI,
+  truncateHead,
+  formatSize,
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+} from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+interface BrowseAction {
+  type: "click" | "fill" | "type" | "press" | "wait" | "wait_selector" | "scroll";
+  selector?: string;
+  value?: string;
+  key?: string;
+  ms?: number;
+  direction?: "down" | "up" | "bottom" | "top";
+  amount?: number;
+  state?: "attached" | "visible" | "hidden";
+}
+
+interface AgentBrowserBatchItem {
+  success: boolean;
+  command: string[];
+  result?: any;
+  error?: string | null;
+}
+
+function requireString(action: BrowseAction, field: "selector" | "value" | "key"): string {
+  const value = action[field];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Action "${action.type}" requires non-empty ${field}`);
+  }
+  return value;
+}
+
+function requireInteger(action: BrowseAction, field: "ms" | "amount"): number {
+  const value = action[field];
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`Action "${action.type}" requires non-negative integer ${field}`);
+  }
+  return value;
+}
+
+function waitForSelectorScript(selector: string, state: "attached" | "visible" | "hidden"): string {
+  const selectorLiteral = JSON.stringify(selector);
+  const stateLiteral = JSON.stringify(state);
+  return `await new Promise((resolve, reject) => {
+    const selector = ${selectorLiteral};
+    const state = ${stateLiteral};
+    const deadline = Date.now() + 30000;
+    const isVisible = (el) => !!(el && (el.offsetWidth || el.offsetHeight || el.getClientRects().length));
+    const check = () => {
+      const el = document.querySelector(selector);
+      const ok = state === "attached" ? !!el : state === "hidden" ? !isVisible(el) : isVisible(el);
+      if (ok) return resolve(true);
+      if (Date.now() > deadline) return reject(new Error(\`Timed out waiting for ${state} selector: ${selector}\`));
+      setTimeout(check, 100);
+    };
+    check();
+  })`;
+}
+
+function buildBatchCommands(
+  url: string,
+  actions: BrowseAction[],
+  selector?: string,
+): string[][] {
+  const commands: string[][] = [["open", url]];
+
+  for (const action of actions) {
+    switch (action.type) {
+      case "click":
+        commands.push(["click", requireString(action, "selector")]);
+        break;
+      case "fill":
+        commands.push(["fill", requireString(action, "selector"), requireString(action, "value")]);
+        break;
+      case "type":
+        commands.push(["type", requireString(action, "selector"), requireString(action, "value")]);
+        break;
+      case "press": {
+        if (action.selector) {
+          commands.push(["focus", action.selector]);
+        }
+        commands.push(["press", requireString(action, "key")]);
+        break;
+      }
+      case "wait":
+        commands.push(["wait", String(requireInteger(action, "ms"))]);
+        break;
+      case "wait_selector": {
+        const state = action.state ?? "visible";
+        const waitSelector = requireString(action, "selector");
+        if (state === "visible") {
+          commands.push(["wait", waitSelector]);
+        } else {
+          commands.push(["eval", waitForSelectorScript(waitSelector, state)]);
+        }
+        break;
+      }
+      case "scroll": {
+        const dir = action.direction ?? "down";
+        if (dir === "top") {
+          commands.push(["eval", "window.scrollTo(0, 0)"]);
+        } else if (dir === "bottom") {
+          commands.push(["eval", "window.scrollTo(0, document.body.scrollHeight)"]);
+        } else {
+          commands.push(["scroll", dir, String(action.amount ?? 500)]);
+        }
+        break;
+      }
+      default:
+        throw new Error(`Unsupported browser action: ${(action as BrowseAction).type}`);
+    }
+  }
+
+  // Extract content
+  if (selector) {
+    commands.push(["get", "text", selector, "--json"]);
+  } else {
+    commands.push(["snapshot", "-i", "--json"]);
+  }
+
+  // Metadata
+  commands.push(["get", "title", "--json"]);
+  commands.push(["get", "url", "--json"]);
+
+  return commands;
+}
+
+function runAgentBrowserBatch(
+  commands: string[][],
+  options: { session: string; headless: boolean; signal?: AbortSignal; timeout?: number },
+): Promise<AgentBrowserBatchItem[]> {
+  const args = ["--session", options.session];
+  if (!options.headless) args.push("--headed");
+  args.push("batch", "--bail", "--json");
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn("agent-browser", args, {
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let timeoutId: NodeJS.Timeout | undefined;
+    let settled = false;
+
+    const cleanup = () => {
+      if (timeoutId) clearTimeout(timeoutId);
+      if (options.signal) options.signal.removeEventListener("abort", kill);
+    };
+
+    const settleReject = (err: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    };
+
+    const kill = () => proc.kill("SIGTERM");
+
+    proc.stdout.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    if (options.timeout) {
+      timeoutId = setTimeout(() => {
+        proc.kill("SIGTERM");
+        settleReject(new Error(`agent-browser timed out after ${options.timeout}ms`));
+      }, options.timeout);
+    }
+
+    proc.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+
+      if (code !== 0 && !stdout.trim()) {
+        reject(new Error(`agent-browser failed (exit ${code}):\n${stderr || "unknown error"}`));
+        return;
+      }
+
+      try {
+        const results = JSON.parse(stdout) as AgentBrowserBatchItem[];
+        resolve(results);
+      } catch (err: any) {
+        reject(new Error(
+          `Failed to parse agent-browser output: ${err.message}\nstdout: ${stdout}\nstderr: ${stderr}`
+        ));
+      }
+    });
+
+    proc.on("error", (err: any) => {
+      if (err.code === "ENOENT") {
+        settleReject(new Error(
+          "agent-browser is not installed.\n\nInstall it with:\n  npm i -g agent-browser && agent-browser install\n\nThen run: agent-browser doctor"
+        ));
+      } else {
+        settleReject(err);
+      }
+    });
+
+    if (options.signal) {
+      if (options.signal.aborted) kill();
+      else options.signal.addEventListener("abort", kill, { once: true });
+    }
+
+    proc.stdin.write(JSON.stringify(commands));
+    proc.stdin.end();
+  });
+}
+
+function closeAgentBrowserSession(session: string, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const proc = spawn("agent-browser", ["--session", session, "close"], {
+      shell: false,
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    const done = () => resolve();
+    proc.on("close", done);
+    proc.on("error", done);
+    if (signal) {
+      const kill = () => proc.kill("SIGTERM");
+      if (signal.aborted) kill();
+      else signal.addEventListener("abort", kill, { once: true });
+    }
+  });
+}
+
+export const WebBrowseActionSchema = Type.Object({
+  type: StringEnum(["click", "fill", "type", "press", "wait", "wait_selector", "scroll"] as const),
+  selector: Type.Optional(Type.String({ description: "CSS selector for actions that target an element" })),
+  value: Type.Optional(Type.String({ description: "Value for fill/type actions" })),
+  key: Type.Optional(Type.String({ description: "Key for press actions, e.g. Enter or Tab" })),
+  ms: Type.Optional(Type.Integer({ description: "Milliseconds for wait actions", minimum: 0 })),
+  direction: Type.Optional(StringEnum(["down", "up", "bottom", "top"] as const)),
+  amount: Type.Optional(Type.Integer({ description: "Pixels for scroll up/down actions", minimum: 0 })),
+  state: Type.Optional(StringEnum(["attached", "visible", "hidden"] as const)),
+});
+
+export const WebBrowseParamsSchema = Type.Object({
+  url: Type.String({ description: "Starting URL to open in the browser" }),
+  actions: Type.Array(WebBrowseActionSchema, {
+    description: "Ordered list of actions to perform on the page. Required fields depend on action type.",
+    maxItems: 25,
+  }),
+  selector: Type.Optional(Type.String({ description: "CSS selector to extract content from the final page state" })),
+  headless: Type.Optional(Type.Boolean({ description: "Run browser headlessly. Default: true", default: true })),
+  timeout: Type.Optional(Type.Integer({ description: "Overall browser batch timeout in milliseconds. Default: 30000", minimum: 1, default: 30000 })),
+});
+
+export type WebBrowseInput = Static<typeof WebBrowseParamsSchema>;
+
+const webBrowseTool = defineTool({
+  name: "web_browse",
+  label: "Web Browse",
+  description: [
+    "Interact with a web page through a browser: navigate, click, fill forms, scroll,",
+    "wait for content, and then extract text.",
+    "Uses the agent-browser CLI for fast, native browser automation via Chrome CDP.",
+    "Use web_browse when the target content requires interaction (clicking buttons,",
+    "scrolling, filling search boxes, waiting for JS to load) before it becomes available.",
+    "For static pages that need no interaction, use web_fetch instead.",
+    `Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; if truncated, full output is saved to a temp file.`,
+  ].join(" "),
+  promptSnippet: "Interact with a web page (click, scroll, fill) and extract content",
+  promptGuidelines: [
+    "Use web_browse when a page requires clicking, scrolling, or form submission before showing target content.",
+    "Use web_browse for SPAs, pagination (click 'Load more'), search forms, tab switching, and modal dialogs.",
+    "For static articles, docs, or blogs that load everything on first request, prefer web_fetch.",
+    "After web_search returns results, prefer web_fetch for reading individual articles.",
+    "Only use web_browse if web_fetch fails to get the needed content.",
+    "Always provide a selector to extract only the relevant content area — avoid dumping full page text.",
+  ],
+  parameters: WebBrowseParamsSchema,
+
+  async execute(toolCallId, params, signal, onUpdate) {
+    let fullOutputPath: string | undefined;
+    const session = `pi-web-browse-${toolCallId}`;
+
+    try {
+      onUpdate?.({ content: [{ type: "text", text: `Browsing ${params.url}...` }], details: {} });
+
+      const commands = buildBatchCommands(
+        params.url,
+        params.actions as BrowseAction[],
+        params.selector,
+      );
+
+      const results = await runAgentBrowserBatch(commands, {
+        session,
+        headless: params.headless ?? true,
+        signal,
+        timeout: params.timeout ?? 30000,
+      });
+
+      const failed = results.find((r) => !r.success);
+      if (failed) {
+        const cmdStr = failed.command?.join(" ") ?? "unknown command";
+        const errMsg = failed.error ?? "unknown error";
+        throw new Error(`Browser action failed: ${cmdStr} — ${errMsg}`);
+      }
+
+      const contentResult = results.find((r) => {
+        if (r.command[0] === "snapshot" && r.command.includes("--json")) return true;
+        if (r.command[0] === "get" && r.command[1] === "text") return true;
+        return false;
+      });
+
+      const titleResult = results.find((r) => r.command[0] === "get" && r.command[1] === "title");
+      const urlResult = results.find((r) => r.command[0] === "get" && r.command[1] === "url");
+
+      let content = "";
+      if (contentResult?.success) {
+        if (contentResult.command[0] === "snapshot") {
+          content = contentResult.result?.snapshot ?? "";
+        } else {
+          content = contentResult.result?.text ?? "";
+        }
+      }
+
+      const title = titleResult?.result?.title ?? "";
+      const finalUrl = urlResult?.result?.url ?? params.url;
+
+      const lines: string[] = [
+        `Title: ${title || "(no title)"}`,
+        `URL: ${finalUrl}`,
+        "",
+        "---",
+        "",
+        content || "(no content extracted)",
+      ];
+
+      const rawText = lines.join("\n");
+      const truncation = truncateHead(rawText, {
+        maxLines: DEFAULT_MAX_LINES,
+        maxBytes: DEFAULT_MAX_BYTES,
+      });
+
+      let finalText = truncation.content;
+      if (truncation.truncated) {
+        const fullOutputDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-web-browse-"));
+        fullOutputPath = path.join(fullOutputDir, "output.txt");
+        await fs.promises.writeFile(fullOutputPath, rawText, "utf-8");
+        finalText += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). Full output saved to: ${fullOutputPath}]`;
+      }
+
+      onUpdate?.({ content: [{ type: "text", text: `Extracted from ${finalUrl}` }], details: {} });
+
+      return {
+        content: [{ type: "text", text: finalText }],
+        details: { title, url: finalUrl, fullOutputPath },
+      };
+    } catch (err: any) {
+      throw new Error(`Error browsing ${params.url}: ${err.message ?? err}`);
+    } finally {
+      await closeAgentBrowserSession(session, signal);
+    }
+  },
+
+  renderCall(args, theme) {
+    let text = theme.fg("toolTitle", theme.bold("web_browse "));
+    text += theme.fg("muted", args.url);
+    text += theme.fg("dim", ` (${args.actions?.length ?? 0} actions)`);
+    return new Text(text, 0, 0);
+  },
+
+  renderResult(result, { expanded, isPartial }, theme) {
+    if (isPartial) {
+      return new Text(theme.fg("warning", "Browsing..."), 0, 0);
+    }
+    const details = result.details as { title?: string; url?: string; fullOutputPath?: string } | undefined;
+    let text = theme.fg("success", "✓ Browsed");
+    if (details?.title) {
+      text += theme.fg("muted", ` — ${details.title}`);
+    }
+    if (expanded && details?.url) {
+      text += `\n${theme.fg("dim", details.url)}`;
+    }
+    if (expanded && details?.fullOutputPath) {
+      text += `\n${theme.fg("dim", `Full output: ${details.fullOutputPath}`)}`;
+    }
+    return new Text(text, 0, 0);
+  },
+});
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(webBrowseTool);
+}

package/extensions/web_fetch.ts

@@ -0,0 +1,138 @@
+/**
+ * Web Fetch Extension — Fetch full page content via scrapling
+ *
+ * Provides a `web_fetch` tool that downloads and extracts readable
+ * content from any URL using the scrapling CLI.
+ *
+ * Requires: `pip install "scrapling[all]"` and `scrapling install`
+ *
+ * Usage:
+ *   The LLM calls web_fetch with a URL after web_search finds relevant pages.
+ */
+
+import {
+  defineTool,
+  type ExtensionAPI,
+  truncateHead,
+  formatSize,
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { runScrapling } from "./utils/scrapling";
+
+export const WebFetchParamsSchema = Type.Object({
+  url: Type.String({ description: "Full URL to fetch (e.g. https://example.com/article)" }),
+  selector: Type.Optional(Type.String({ description: "CSS selector to extract only a specific part of the page" })),
+  stealthy: Type.Optional(Type.Boolean({ description: "Use stealthy mode for protected/anti-bot sites. Default: false", default: false })),
+});
+
+export type WebFetchInput = Static<typeof WebFetchParamsSchema>;
+
+const webFetchTool = defineTool({
+  name: "web_fetch",
+  label: "Web Fetch",
+  description: [
+    "Fetch and extract readable content from a web page URL.",
+    "Uses scrapling to download the page and convert it to clean markdown.",
+    "Use web_fetch AFTER web_search to read the full content of a result page.",
+    "Respects robots.txt and site ToS.",
+    `Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; if truncated, full output is saved to a temp file.`,
+  ].join(" "),
+  promptSnippet: "Fetch full page content from a URL as markdown",
+  promptGuidelines: [
+    "Use web_fetch after web_search to read full articles, docs, or pages found in search results.",
+    "Always pass the full URL including https://.",
+    "If the page is dynamic/JavaScript-heavy, the tool automatically uses browser automation.",
+  ],
+  parameters: WebFetchParamsSchema,
+
+  async execute(_toolCallId, params, signal) {
+    const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-web-fetch-"));
+    const tmpFile = path.join(tmpDir, "page.md");
+    let tmpFull: string | undefined;
+
+    try {
+      const cmd = params.stealthy ? "stealthy-fetch" : "fetch";
+      const args = ["extract", cmd, params.url, tmpFile, "--ai-targeted"];
+      if (params.selector) {
+        args.push("--css-selector", params.selector);
+      }
+
+      const { stdout, stderr, exitCode } = await runScrapling(args, signal);
+
+      if (exitCode !== 0) {
+        // Try fallback to simple HTTP GET if fetch/stealthy-fetch failed
+        if (!params.stealthy) {
+          const fallback = await runScrapling(["extract", "get", params.url, tmpFile, "--ai-targeted"], signal);
+          if (fallback.exitCode !== 0) {
+            throw new Error(`Failed to fetch ${params.url}\n\nscrapling error:\n${stderr || fallback.stderr}`);
+          }
+        } else {
+          throw new Error(`Failed to fetch ${params.url}\n\nscrapling error:\n${stderr}`);
+        }
+      }
+
+      const content = await fs.promises.readFile(tmpFile, "utf-8");
+      const stats = await fs.promises.stat(tmpFile);
+
+      const rawText = `Fetched: ${params.url}\nSize: ${stats.size} bytes\n\n---\n\n${content}`;
+      const truncation = truncateHead(rawText, {
+        maxLines: DEFAULT_MAX_LINES,
+        maxBytes: DEFAULT_MAX_BYTES,
+      });
+
+      let finalText = truncation.content;
+      if (truncation.truncated) {
+        const tmpFullDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-web-fetch-full-"));
+        tmpFull = path.join(tmpFullDir, "output.txt");
+        await fs.promises.writeFile(tmpFull, rawText, "utf-8");
+        finalText += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). Full output saved to: ${tmpFull}]`;
+      }
+
+      return {
+        content: [{ type: "text", text: finalText }],
+        details: { url: params.url, bytes: stats.size, fullOutputPath: tmpFull },
+      };
+    } catch (err: any) {
+      throw new Error(`Error fetching ${params.url}: ${err.message ?? err}`);
+    } finally {
+      try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
+    }
+  },
+
+  renderCall(args, theme) {
+    let text = theme.fg("toolTitle", theme.bold("web_fetch "));
+    text += theme.fg("muted", args.url);
+    if (args.selector) {
+      text += theme.fg("dim", ` selector=${args.selector}`);
+    }
+    return new Text(text, 0, 0);
+  },
+
+  renderResult(result, { expanded, isPartial }, theme) {
+    if (isPartial) {
+      return new Text(theme.fg("warning", "Fetching..."), 0, 0);
+    }
+    const details = result.details as { url?: string; bytes?: number; fullOutputPath?: string } | undefined;
+    let text = theme.fg("success", "✓ Fetched");
+    if (details?.bytes) {
+      text += theme.fg("muted", ` (${formatSize(details.bytes)})`);
+    }
+    if (expanded) {
+      text += `\n${theme.fg("dim", details?.url ?? "")}`;
+      if (details?.fullOutputPath) {
+        text += `\n${theme.fg("dim", `Full output: ${details.fullOutputPath}`)}`;
+      }
+    }
+    return new Text(text, 0, 0);
+  },
+});
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(webFetchTool);
+}

package/extensions/web_search.ts

@@ -0,0 +1,179 @@
+/**
+ * SearXNG Web Search Extension for Pi
+ *
+ * Provides a `web_search` tool that queries a SearXNG instance.
+ *
+ * Configuration:
+ *   Set SEARXNG_URL env var to your instance (default: http://localhost:8080)
+ *
+ * Usage:
+ *   The LLM can call web_search with a query to get search results.
+ */
+
+import {
+  defineTool,
+  type ExtensionAPI,
+  truncateHead,
+  formatSize,
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const SEARXNG_URL = (process.env.SEARXNG_URL || "http://localhost:8080").replace(/\/$/, "");
+
+interface SearxResult {
+  title: string;
+  url: string;
+  content?: string;
+  engine?: string;
+  score?: number;
+}
+
+interface SearxResponse {
+  query: string;
+  results: SearxResult[];
+  suggestions?: string[];
+}
+
+export const WebSearchParamsSchema = Type.Object({
+  query: Type.String({ description: "Search query" }),
+  language: Type.Optional(Type.String({ description: "Language code (e.g. en, en-US, de). Default: auto", default: "auto" })),
+  results: Type.Optional(Type.Integer({ description: "Max number of results to return (1-50). Default: 10", minimum: 1, maximum: 50, default: 10 })),
+});
+
+export type WebSearchInput = Static<typeof WebSearchParamsSchema>;
+
+const webSearchTool = defineTool({
+  name: "web_search",
+  label: "Web Search",
+  description: [
+    "Search the web using a SearXNG instance.",
+    "Returns a list of results with title, URL, and snippet.",
+    "Use web_search when the user asks about current events, facts, or anything",
+    "that requires up-to-date information beyond the model's training data.",
+    `Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; if truncated, full output is saved to a temp file.`,
+  ].join(" "),
+  promptSnippet: "Search the web for current information",
+  promptGuidelines: [
+    "Use web_search when the user asks about recent events, current data, or external facts.",
+    "Use web_search to verify claims, find documentation, or discover resources online.",
+  ],
+  parameters: WebSearchParamsSchema,
+
+  async execute(_toolCallId, params, signal) {
+    const maxResults = Math.floor(Math.min(50, Math.max(1, params.results ?? 10)));
+    const searchParams = new URLSearchParams({
+      q: params.query,
+      format: "json",
+      language: params.language ?? "auto",
+    });
+
+    const url = `${SEARXNG_URL}/search?${searchParams.toString()}`;
+
+    let fullOutputPath: string | undefined;
+
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { Accept: "application/json" },
+        signal,
+      });
+
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`SearXNG error: ${response.status} ${response.statusText}\n${body}`);
+      }
+
+      const data = (await response.json()) as SearxResponse;
+
+      if (!data.results || data.results.length === 0) {
+        let text = `No results found for "${data.query}".`;
+        if (data.suggestions && data.suggestions.length > 0) {
+          text += `\n\nSuggestions:\n${data.suggestions.map((s) => `- ${s}`).join("\n")}`;
+        }
+        return {
+          content: [{ type: "text", text }],
+          details: { query: data.query, totalResults: 0, results: [], fullOutputPath: undefined },
+        };
+      }
+
+      const lines: string[] = [
+        `Results for "${data.query}":`,
+        "",
+      ];
+
+      for (let i = 0; i < Math.min(maxResults, data.results.length); i++) {
+        const r = data.results[i];
+        lines.push(`${i + 1}. ${r.title}`);
+        lines.push(`   URL: ${r.url}`);
+        if (r.content) {
+          const snippet = r.content.replace(/\s+/g, " ").trim();
+          lines.push(`   ${snippet}`);
+        }
+        if (r.engine) {
+          lines.push(`   [engine: ${r.engine}]`);
+        }
+        lines.push("");
+      }
+
+      const rawText = lines.join("\n");
+      const truncation = truncateHead(rawText, {
+        maxLines: DEFAULT_MAX_LINES,
+        maxBytes: DEFAULT_MAX_BYTES,
+      });
+
+      let finalText = truncation.content;
+      if (truncation.truncated) {
+        const tmpDir = await mkdtemp(path.join(os.tmpdir(), "pi-web-search-"));
+        fullOutputPath = path.join(tmpDir, "output.txt");
+        await writeFile(fullOutputPath, rawText, "utf-8");
+        finalText += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). Full output saved to: ${fullOutputPath}]`;
+      }
+
+      return {
+        content: [{ type: "text", text: finalText }],
+        details: { query: data.query, totalResults: data.results.length, results: data.results.slice(0, maxResults), fullOutputPath },
+      };
+    } catch (err: any) {
+      throw new Error(`Failed to query SearXNG at ${SEARXNG_URL}: ${err.message ?? err}`);
+    }
+  },
+
+  renderCall(args, theme) {
+    let text = theme.fg("toolTitle", theme.bold("web_search "));
+    text += theme.fg("muted", args.query);
+    if (args.results) {
+      text += theme.fg("dim", ` results=${args.results}`);
+    }
+    return new Text(text, 0, 0);
+  },
+
+  renderResult(result, { expanded, isPartial }, theme) {
+    if (isPartial) {
+      return new Text(theme.fg("warning", "Searching..."), 0, 0);
+    }
+    const details = result.details as { query?: string; totalResults?: number; results?: Array<{ title?: string; url?: string }>; fullOutputPath?: string } | undefined;
+    let text = theme.fg("success", `✓ ${details?.totalResults ?? 0} results`);
+    if (details?.query) {
+      text += theme.fg("muted", ` for ${details.query}`);
+    }
+    if (expanded && details?.results?.length) {
+      for (const r of details.results.slice(0, 10)) {
+        text += `\n  ${theme.fg("dim", `${r.title ?? "(untitled)"} — ${r.url ?? ""}`)}`;
+      }
+    }
+    if (expanded && details?.fullOutputPath) {
+      text += `\n${theme.fg("dim", `Full output: ${details.fullOutputPath}`)}`;
+    }
+    return new Text(text, 0, 0);
+  },
+});
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(webSearchTool);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "pi-web-toolkit",
+  "version": "0.1.0",
+  "description": "Web research toolkit for the pi coding agent. Search via SearXNG, fetch static pages with scrapling, browse interactively via agent-browser, and batch-read sources in parallel.",
+  "author": "Wade Huang <fastwade11@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wade11s/pi-web-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Wade11s/pi-web-toolkit/issues"
+  },
+  "homepage": "https://github.com/Wade11s/pi-web-toolkit#readme",
+  "keywords": ["pi-package", "pi-extension", "web-search", "scrapling", "agent-browser"],
+  "files": ["extensions", "docs", "README.md", "package.json", "LICENSE"],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/web_search.ts",
+      "./extensions/web_fetch.ts",
+      "./extensions/web_browse.ts",
+      "./extensions/web_batch_fetch.ts"
+    ]
+  }
+}