@bacnh85/pi-web 0.6.2 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.7.1 (2026-09-12)
+
+### Fixed
+
+- `before_agent_start` routing guidance now falls back to `pi.getActiveTools()`
+  when the host omits `systemPromptOptions` (mirrors pi-fff), so guidance no
+  longer silently skips injection.
+- README: corrected default backend URLs to `127.0.0.1` (matching code defaults
+  in `lib/config.ts`), removed the nonexistent `npm run test:unit` script
+  reference, documented the `web_search` `timeout_ms` parameter.
+
+## 0.7.0 (2026-09-11)
+
+### Added
+
+- **Local capture engine** — `web_screenshot` and `web_pdf` now capture
+  `localhost`/LAN/`file://` URLs via the locally installed Chrome/Chromium
+  (headless CLI, zero dependencies). The Crawl4AI daemon's browser runs on the
+  daemon host and SSRF-blocks private addresses, so local dev servers were
+  uncapturable before. Routing is automatic (`engine="auto"` default):
+  private URLs → local Chrome, public URLs → daemon, and a daemon SSRF-block
+  on an otherwise-public URL falls back to local Chrome automatically.
+  `engine="local"`/`"daemon"` forces one. New `web_screenshot` params:
+  `width` (1280), `height` (800), `full_page` (tall 8000px window — the
+  Chrome CLI has no true full-page flag). Binary discovery: `CHROME_PATH` env
+  → standard per-OS paths (Edge as Windows fallback). Captures run in an
+  isolated temp profile with a 30s timeout; `wait_for` maps to
+  `--virtual-time-budget`. Chrome versions that write the capture but never
+  exit (fresh `--user-data-dir` on macOS) are handled by polling for a
+  size-stable output file instead of requiring a clean exit. Review-hardened:
+  capture URLs are scheme-validated (http/https/file) before spawn so
+  switch-like strings can't be injected as Chrome flags; IPv6 loopback/ULA/
+  link-local (`[::1]`, `fc00::/7`, `fe80::/10`) route to local Chrome (Node
+  `URL.hostname` keeps brackets); daemon `details` payloads are preserved
+  (mime/artifact/full result) alongside the new `engine` key; timeout is
+  always a failure (a complete capture is caught by the stability poll first).
+  `web_status` reports the discovered local Chrome path.
+- New `extensions/lib/chrome.ts` (engine + `isLocalUrl`/`resolveEngine`/
+  `isSsrfBlocked` helpers) with unit tests in `test/unit/chrome.test.ts`;
+  live-verified against a local `http.server` (PNG magic, PDF magic, inline
+  image block, tmp cleanup, no orphan processes).
+
 ## 0.6.2 (2026-09-06)
 
 ### Changed

package/README.md

@@ -25,10 +25,10 @@ Variables:
 | Variable | Required | Default | Notes |
 |---|---|---|---|
 | `BRAVE_API_KEY` | No (1) | — | Brave Search API key |
-| `SEARXNG_BASE_URL` | No | `http://172.30.55.22:8888` | Self-hosted SearXNG |
+| `SEARXNG_BASE_URL` | No | `http://127.0.0.1:8888` | Self-hosted SearXNG |
 | `FIRECRAWL_API_URL` | No | `https://api.firecrawl.dev/v2` | Self-hosted or hosted |
 | `FIRECRAWL_API_KEY` | No (2) | — | Required for hosted Firecrawl |
-| `CRAWL4AI_API_URL` | No | `http://172.30.55.22:11235` | Self-hosted Crawl4AI |
+| `CRAWL4AI_API_URL` | No | `http://127.0.0.1:11235` | Self-hosted Crawl4AI |
 | `CRAWL4AI_API_TOKEN` | No (3) | — | Required if Crawl4AI auth enabled |
 
 > (1) At least one search backend (SearXNG, Brave, or Firecrawl) must be configured for `web_search`.
@@ -66,6 +66,7 @@ Parameters:
 | `engines` | string | — | SearXNG engine override, e.g. `google,github` |
 | `include_content` | boolean | false | Fetch page content alongside results |
 | `content_chars` | number | 5000 | Max content chars per result |
+| `timeout_ms` | number | per-backend | Request timeout in ms (SearXNG/static 15000, Firecrawl/Crawl4AI 60000) |
 
 **Auto-selection behavior:**
 
@@ -142,21 +143,39 @@ web_crawl url="https://example.com" mode=light poll=true    # Poll for completio
 
 ### `web_screenshot` — Page screenshot
 
-Captures a full-page PNG screenshot using Crawl4AI. Returns the PNG inline as an image block (multimodal models see it); text summary includes artifact/MIME/size.
+Captures a full-page PNG screenshot using the Crawl4AI daemon, or **local headless Chrome for localhost/LAN/file URLs** (auto-detected; see [Local capture](#local-capture)). Returns the PNG inline as an image block (multimodal models see it); text summary includes engine/MIME/size.
 
 ```
 web_screenshot url="https://example.com"
 web_screenshot url="https://example.com" wait_for=5 wait_for_images=true
+web_screenshot url="http://localhost:3000"           # local Chrome, auto-detected
+web_screenshot url="http://localhost:3000" full_page=true width=1280
+web_screenshot url="https://example.com" engine="daemon"  # force the daemon
 ```
 
+Local-engine params: `width` (default 1280), `height` (default 800), `full_page` (captures a tall 8000px window — the Chrome CLI has no true full-page flag).
+
 ### `web_pdf` — Page PDF
 
-Generates a PDF document using Crawl4AI. Returns base64-encoded PDF.
+Generates a PDF document using the Crawl4AI daemon, or **local headless Chrome** for localhost/LAN/file URLs (auto-detected). Returns base64-encoded PDF.
 
 ```
 web_pdf url="https://example.com/article"
+web_pdf url="http://localhost:3000"   # local Chrome, auto-detected
 ```
 
+### Local capture
+
+The Crawl4AI daemon's browser runs on the daemon host — it cannot reach (and SSRF-blocks) your `localhost`. pi-web therefore routes private URLs to a **locally installed Chrome/Chromium** in headless mode:
+
+| URL | Engine |
+|-----|--------|
+| `localhost`, `127.0.0.1`, LAN IPs (10/8, 172.16/12, 192.168/16, 169.254/16), `file://` | local Chrome |
+| public URLs | Crawl4AI daemon |
+| daemon SSRF-blocks a URL | automatic local-Chrome retry |
+
+Override with `engine="local"` / `engine="daemon"`. Binary discovery: `CHROME_PATH` env, then standard Chrome/Chromium paths per OS (Edge as a Windows fallback). Captures use an isolated temp profile, a 30s timeout, and `--virtual-time-budget` for `wait_for`.
+
 ### `web_status` — Provider status
 
 Shows all provider configuration status and Crawl4AI server health.
@@ -170,14 +189,15 @@ Typical output:
 ```json
 {
   "brave": { "apiKeyFound": true, "apiKeySource": "process.env" },
-  "searxng": { "baseUrl": "http://172.30.55.22:8888", ... },
-  "firecrawl": { "baseUrl": "http://172.30.55.22:3002/v2", ... },
+  "searxng": { "baseUrl": "http://127.0.0.1:8888", ... },
+  "firecrawl": { "baseUrl": "http://127.0.0.1:3002/v2", ... },
   "crawl4ai": {
-    "baseUrl": "http://172.30.55.22:11235",
+    "baseUrl": "http://127.0.0.1:11235",
     ...
     "health": { "status": "healthy", "version": "0.5.0", ... }
   },
-  "agy": { "installed": true }
+  "agy": { "installed": true },
+  "localChrome": { "path": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" }
 }
 ```
 
@@ -229,7 +249,4 @@ See [CHANGELOG.md](CHANGELOG.md) for release history.
 ```bash
 # Run all tests
 npm test
-
-# Run only unit tests
-npm run test:unit
 ```

package/extensions/index.ts

@@ -29,6 +29,13 @@ import {
   fetchCrawl4aiPdf,
   fetchCrawl4aiHealth,
 } from "./lib/crawl4ai";
+import {
+  capturePdf as captureLocalPdf,
+  captureScreenshot as captureLocalScreenshot,
+  findChromeBinary,
+  isSsrfBlocked,
+  resolveEngine,
+} from "./lib/chrome";
 
 // ---------------------------------------------------------------------------
 // Shared schema fragment
@@ -48,6 +55,14 @@ const crawl4aiControlSchema = {
   crawl4ai_api_token: Type.Optional(Type.String({ description: "Override $CRAWL4AI_API_TOKEN." })),
 };
 
+const engineSchema = {
+  engine: Type.Optional(Type.Union([
+    Type.Literal("auto"),
+    Type.Literal("local"),
+    Type.Literal("daemon"),
+  ], { default: "auto", description: "auto routes localhost/private/file URLs to local Chrome, the rest to the Crawl4AI daemon; local/daemon force one." })),
+};
+
 // ---------------------------------------------------------------------------
 // Always-on routing guidance (injected only when a web_* tool is active)
 // ---------------------------------------------------------------------------
@@ -286,33 +301,80 @@ export default function piWebExtension(pi: ExtensionAPI) {
     name: "web_screenshot",
     label: "Web Page Screenshot",
     description:
-      "Full-page PNG screenshot via Crawl4AI. The PNG is returned inline as an image block.",
+      "Full-page PNG screenshot via the Crawl4AI daemon, or via local headless Chrome for localhost/private/file URLs (auto-detected, engine overridable). The PNG is returned inline as an image block.",
     promptSnippet: "Screenshot a webpage",
-    promptGuidelines: ["Full-page PNG returned inline (multimodal models see it); use when web_extract fails on JS-heavy pages, or to visually inspect a built UI."],
+    promptGuidelines: ["PNG returned inline (multimodal models see it); use when web_extract fails on JS-heavy pages, or to visually inspect a built UI. Local dev servers (localhost/LAN/file://) capture automatically via local Chrome."],
     parameters: Type.Object({
       url: Type.String(),
       wait_for: Type.Optional(Type.Number({ default: 2, description: "Seconds to wait before capture." })),
       wait_for_images: Type.Optional(Type.Boolean({ default: false })),
+      engine: Type.Optional(engineSchema.engine),
+      width: Type.Optional(Type.Number({ default: 1280, description: "Local engine: viewport width." })),
+      height: Type.Optional(Type.Number({ default: 800, description: "Local engine: viewport height (full_page uses 8000)." })),
+      full_page: Type.Optional(Type.Boolean({ default: false, description: "Local engine: capture a tall 8000px window to approximate full page." })),
       ...crawl4aiControlSchema,
       ...sharedControlSchema,
     }),
     async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-      const config = loadCrawl4aiConfig(params as Record<string, unknown>, cwdFromContext(ctx), includeProjectEnv(ctx));
-      const result = await fetchCrawl4aiScreenshot(
-        config,
-        params.url as string,
-        params.wait_for as number | undefined,
-        params.wait_for_images as boolean | undefined,
-        signal,
-      );
-      if (result.success === false) {
-        throw new Error(String(result.error_message ?? "Crawl4AI screenshot failed"));
+      const url = params.url as string;
+      let engine = resolveEngine(params.engine as string | undefined, url);
+      let screenshot: string | undefined;
+      let mime: string | undefined;
+      let size: number | undefined;
+      let artifactUrl: string | undefined;
+      let details: Record<string, unknown> = {};
+
+      if (engine === "local") {
+        const cap = await captureLocalScreenshot({
+          url,
+          width: params.width as number | undefined,
+          height: params.height as number | undefined,
+          fullPage: params.full_page as boolean | undefined,
+          waitForSec: params.wait_for as number | undefined,
+          signal,
+        });
+        screenshot = cap.base64;
+        mime = cap.mime;
+        size = cap.size;
+        details = { mime: cap.mime, size: cap.size };
+      } else {
+        const config = loadCrawl4aiConfig(params as Record<string, unknown>, cwdFromContext(ctx), includeProjectEnv(ctx));
+        try {
+          const result = await fetchCrawl4aiScreenshot(
+            config,
+            url,
+            params.wait_for as number | undefined,
+            params.wait_for_images as boolean | undefined,
+            signal,
+          );
+          if (result.success === false) {
+            throw new Error(String(result.error_message ?? "Crawl4AI screenshot failed"));
+          }
+          screenshot = result.screenshot as string | undefined;
+          artifactUrl = result.url as string | undefined;
+          mime = result.mime as string | undefined;
+          size = result.size as number | undefined;
+          details = { ...result };
+        } catch (err) {
+          // Daemon can't render this URL (SSRF-blocked); retry via local Chrome.
+          if (!isSsrfBlocked(err) || !findChromeBinary()) throw err;
+          engine = "local";
+          const cap = await captureLocalScreenshot({
+            url,
+            width: params.width as number | undefined,
+            height: params.height as number | undefined,
+            fullPage: params.full_page as boolean | undefined,
+            waitForSec: params.wait_for as number | undefined,
+            signal,
+          });
+          screenshot = cap.base64;
+          mime = cap.mime;
+          size = cap.size;
+          details = { mime: cap.mime, size: cap.size, fallback: "daemon SSRF-blocked this URL" };
+        }
       }
-      const screenshot = result.screenshot as string | undefined;
-      const artifactUrl = result.url as string | undefined;
-      const mime = result.mime as string | undefined;
-      const size = result.size as number | undefined;
-      let text = `Screenshot: ${params.url}\n`;
+
+      let text = `Screenshot: ${url}\nEngine: ${engine === "local" ? "local-chrome" : "crawl4ai"}\n`;
       if (artifactUrl) text += `Artifact: ${artifactUrl}\n`;
       if (mime) text += `MIME: ${mime}\n`;
       if (size) text += `Size: ${size} bytes\n`;
@@ -321,7 +383,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
         { type: "text", text: truncateText(text) },
       ];
       if (screenshot) content.push({ type: "image", data: screenshot, mimeType: mime || "image/png" });
-      return { content, details: { ...result, url: params.url } };
+      return { content, details: { ...details, url, engine } };
     },
   });
 
@@ -330,25 +392,51 @@ export default function piWebExtension(pi: ExtensionAPI) {
     name: "web_pdf",
     label: "Web Page PDF",
     description:
-      "PDF document via Crawl4AI.",
+      "PDF document via the Crawl4AI daemon, or via local headless Chrome for localhost/private/file URLs (auto-detected, engine overridable).",
     promptSnippet: "PDF a webpage",
-    promptGuidelines: ["Printable/archivable page snapshot; returns base64 PDF."],
+    promptGuidelines: ["Printable/archivable page snapshot; returns base64 PDF. Local dev servers capture automatically via local Chrome."],
     parameters: Type.Object({
       url: Type.String(),
+      engine: Type.Optional(engineSchema.engine),
       ...crawl4aiControlSchema,
       ...sharedControlSchema,
     }),
     async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-      const config = loadCrawl4aiConfig(params as Record<string, unknown>, cwdFromContext(ctx), includeProjectEnv(ctx));
-      const result = await fetchCrawl4aiPdf(config, params.url as string, signal);
-      const pdf = result.pdf as string | undefined;
-      const artifactUrl = result.url as string | undefined;
-      const size = result.size as number | undefined;
-      let text = `PDF: ${params.url}\n`;
+      const url = params.url as string;
+      let engine = resolveEngine(params.engine as string | undefined, url);
+      let pdf: string | undefined;
+      let artifactUrl: string | undefined;
+      let size: number | undefined;
+      let details: Record<string, unknown> = {};
+
+      if (engine === "local") {
+        const cap = await captureLocalPdf({ url, signal });
+        pdf = cap.base64;
+        size = cap.size;
+        details = { mime: cap.mime, size: cap.size };
+      } else {
+        const config = loadCrawl4aiConfig(params as Record<string, unknown>, cwdFromContext(ctx), includeProjectEnv(ctx));
+        try {
+          const result = await fetchCrawl4aiPdf(config, url, signal);
+          pdf = result.pdf as string | undefined;
+          artifactUrl = result.url as string | undefined;
+          size = result.size as number | undefined;
+          details = { ...result };
+        } catch (err) {
+          if (!isSsrfBlocked(err) || !findChromeBinary()) throw err;
+          engine = "local";
+          const cap = await captureLocalPdf({ url, signal });
+          pdf = cap.base64;
+          size = cap.size;
+          details = { mime: cap.mime, size: cap.size, fallback: "daemon SSRF-blocked this URL" };
+        }
+      }
+
+      let text = `PDF: ${url}\nEngine: ${engine === "local" ? "local-chrome" : "crawl4ai"}\n`;
       if (pdf) text += `Data: base64 PDF (${pdf.length} chars)\n`;
       if (artifactUrl) text += `Artifact: ${artifactUrl}\n`;
       if (size) text += `Size: ${size} bytes\n`;
-      return { content: [{ type: "text" as const, text: truncateText(text) }], details: { ...result, url: params.url } };
+      return { content: [{ type: "text" as const, text: truncateText(text) }], details: { ...details, url, engine } };
     },
   });
 
@@ -396,6 +484,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
           apiTokenSource: c4aiToken.value ? c4aiToken.source : "not set",
         },
         agy: { installed: isAgyInstalled() },
+        localChrome: { path: findChromeBinary() ?? "not found" },
       };
 
       // Crawl4AI health check
@@ -416,7 +505,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
   // Inject the backend-selection protocol only when a web_* tool is actually
   // active, so recon agents / sessions without pi-web carry zero overhead.
   pi.on("before_agent_start", async (event) => {
-    const active = event.systemPromptOptions?.selectedTools ?? [];
+    const active = event.systemPromptOptions?.selectedTools ?? pi.getActiveTools();
     if (!active.some((t) => t.startsWith("web_"))) return;
     return { systemPrompt: `${event.systemPrompt}\n\n${WEB_ROUTING_GUIDANCE}` };
   });

package/extensions/lib/chrome.ts

@@ -0,0 +1,296 @@
+// Local headless Chrome capture — for localhost/private/file:// URLs the
+// remote Crawl4AI daemon cannot reach (its SSRF protection blocks them).
+// Zero dependencies: drives the locally installed Chrome/Chromium binary.
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+export interface LocalCapture {
+  base64: string;
+  mime: string;
+  size: number;
+}
+
+const CHROME_TIMEOUT_MS = 30_000;
+// ponytail: tall-window approximates full page (CLI has no fullPage flag) —
+// Playwright tier if this proves insufficient.
+const FULL_PAGE_HEIGHT = 8000;
+
+/** Locate a locally installed Chrome/Chromium (or Edge as a Windows fallback). */
+export function findChromeBinary(): string | null {
+  const candidates: string[] = [];
+  if (process.env.CHROME_PATH) candidates.push(process.env.CHROME_PATH);
+  switch (process.platform) {
+    case "darwin": {
+      const apps = ["/Applications", path.join(process.env.HOME ?? "", "Applications")];
+      for (const app of apps) {
+        candidates.push(
+          path.join(app, "Google Chrome.app/Contents/MacOS/Google Chrome"),
+          path.join(app, "Chromium.app/Contents/MacOS/Chromium"),
+        );
+      }
+      break;
+    }
+    case "win32": {
+      const roots = [
+        "C:\\Program Files",
+        "C:\\Program Files (x86)",
+        process.env.LOCALAPPDATA ?? "",
+      ].filter(Boolean);
+      for (const root of roots) {
+        candidates.push(
+          path.join(root, "Google\\Chrome\\Application\\chrome.exe"),
+          path.join(root, "Microsoft\\Edge\\Application\\msedge.exe"),
+        );
+      }
+      break;
+    }
+    default: {
+      const dirs = [
+        ...(process.env.PATH ?? "").split(":").filter(Boolean),
+        "/usr/bin",
+        "/usr/local/bin",
+        "/snap/bin",
+      ];
+      for (const dir of dirs) {
+        candidates.push(
+          path.join(dir, "google-chrome"),
+          path.join(dir, "google-chrome-stable"),
+          path.join(dir, "chromium"),
+          path.join(dir, "chromium-browser"),
+        );
+      }
+    }
+  }
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+
+/** True for URLs a remote daemon provably cannot render: file://, localhost, loopback, private ranges. */
+export function isLocalUrl(raw: string): boolean {
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    return false;
+  }
+  if (u.protocol === "file:") return true;
+  const host = u.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  if (host === "::1") return true;
+  if (host.includes(":")) {
+    // IPv6 ULA fc00::/7 and link-local fe80::/10 are private too.
+    if (/^f[cd]/.test(host) || /^fe[89ab]/.test(host)) return true;
+    return false;
+  }
+  const m = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (m) {
+    const a = Number(m[1]);
+    const b = Number(m[2]);
+    if (a === 127 || a === 10 || a === 0) return true;
+    if (a === 172 && b >= 16 && b <= 31) return true; // 172.16/12
+    if (a === 192 && b === 168) return true;
+    if (a === 169 && b === 254) return true; // link-local
+  }
+  return false;
+}
+
+/** Daemon SSRF/URL-blocked failures that a local-Chrome retry can rescue. */
+export function isSsrfBlocked(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  return /SSRF|URL blocked/i.test(msg);
+}
+
+/** Pick the capture engine: local Chrome or the remote Crawl4AI daemon. */
+export function resolveEngine(engine: string | undefined, url: string): "local" | "daemon" {
+  if (engine === "local" || engine === "daemon") return engine;
+  return isLocalUrl(url) ? "local" : "daemon";
+}
+
+export interface ScreenshotArgsOpts {
+  chromePath: string;
+  outPath: string;
+  userDataDir: string;
+  url: string;
+  width: number;
+  height: number;
+  fullPage?: boolean;
+  waitForSec?: number;
+}
+
+export function buildScreenshotArgs(opts: ScreenshotArgsOpts): string[] {
+  const height = opts.fullPage ? FULL_PAGE_HEIGHT : opts.height;
+  return [
+    opts.chromePath,
+    "--headless",
+    "--no-first-run",
+    "--disable-gpu",
+    `--user-data-dir=${opts.userDataDir}`,
+    "--hide-scrollbars",
+    `--window-size=${opts.width},${height}`,
+    ...(opts.waitForSec ? [`--virtual-time-budget=${Math.round(opts.waitForSec * 1000)}`] : []),
+    `--screenshot=${opts.outPath}`,
+    opts.url,
+  ];
+}
+
+export function buildPdfArgs(opts: {
+  chromePath: string;
+  outPath: string;
+  userDataDir: string;
+  url: string;
+}): string[] {
+  return [
+    opts.chromePath,
+    "--headless",
+    "--no-first-run",
+    "--disable-gpu",
+    `--user-data-dir=${opts.userDataDir}`,
+    "--no-pdf-header-footer",
+    `--print-to-pdf=${opts.outPath}`,
+    opts.url,
+  ];
+}
+
+function runChrome(
+  args: string[],
+  outPath: string,
+  signal?: AbortSignal,
+  timeoutMs: number = CHROME_TIMEOUT_MS,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(args[0], args.slice(1), { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    let settled = false;
+    let lastSize = -1;
+    let stablePolls = 0;
+    let fileTimer: ReturnType<typeof setInterval> | undefined;
+    const finish = (err?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(killTimer);
+      clearInterval(fileTimer);
+      signal?.removeEventListener("abort", onAbort);
+      if (err) reject(err);
+      else resolve();
+    };
+    const onAbort = () => {
+      child.kill("SIGKILL");
+      finish(new Error("Local capture aborted"));
+    };
+    const killTimer = setTimeout(() => {
+      child.kill("SIGKILL");
+      // Always a failure: a complete capture is caught earlier by the
+      // size-stability poll, so surviving to the timeout means the output
+      // never settled (or never appeared) — a file here may be mid-write.
+      finish(new Error(`Local capture timed out after ${timeoutMs / 1000}s`));
+    }, timeoutMs);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    child.stderr?.on("data", (d: Buffer) => {
+      stderr += d.toString();
+    });
+    child.on("error", (err) => finish(err));
+    child.on("close", (code) => {
+      if (existsSync(outPath)) finish();
+      else finish(new Error(`Chrome exited with code ${code}: ${stderr.slice(-400)}`));
+    });
+    // Resolve as soon as the capture file is written and stable, then kill —
+    // don't require a clean Chrome exit (some versions hang after writing,
+    // e.g. fresh --user-data-dir on macOS).
+    fileTimer = setInterval(() => {
+      if (!existsSync(outPath)) return;
+      const size = statSync(outPath).size;
+      if (size > 0 && size === lastSize) {
+        if (++stablePolls >= 2) {
+          child.kill("SIGKILL");
+          finish();
+        }
+      } else {
+        stablePolls = 0;
+        lastSize = size;
+      }
+    }, 250);
+  });
+}
+
+async function readCapture(outPath: string, mime: string): Promise<LocalCapture> {
+  const buf = readFileSync(outPath);
+  return { base64: buf.toString("base64"), mime, size: buf.length };
+}
+
+function assertCaptureUrl(url: string): void {
+  // Trust boundary: the URL becomes a spawn argv element — a scheme check
+  // keeps strings like "--proxy-server=http://evil" from parsing as switches.
+  if (!/^https?:\/\//i.test(url) && !/^file:\/\//i.test(url)) {
+    throw new Error(`Invalid capture URL (${url.slice(0, 80)}): must be http://, https://, or file://`);
+  }
+}
+
+export async function captureScreenshot(opts: {
+  url: string;
+  width?: number;
+  height?: number;
+  fullPage?: boolean;
+  waitForSec?: number;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}): Promise<LocalCapture> {
+  assertCaptureUrl(opts.url);
+  const chromePath = findChromeBinary();
+  if (!chromePath) {
+    throw new Error("No local Chrome/Chromium found — install Chrome or set CHROME_PATH.");
+  }
+  const dir = mkdtempSync(path.join(tmpdir(), "pi-web-capture-"));
+  try {
+    const outPath = path.join(dir, "screenshot.png");
+    await runChrome(
+      buildScreenshotArgs({
+        chromePath,
+        outPath,
+        userDataDir: path.join(dir, "profile"),
+        url: opts.url,
+        width: opts.width ?? 1280,
+        height: opts.height ?? 800,
+        fullPage: opts.fullPage,
+        waitForSec: opts.waitForSec,
+      }),
+      outPath,
+      opts.signal,
+      opts.timeoutMs,
+    );
+    return await readCapture(outPath, "image/png");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export async function capturePdf(opts: {
+  url: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}): Promise<LocalCapture> {
+  assertCaptureUrl(opts.url);
+  const chromePath = findChromeBinary();
+  if (!chromePath) {
+    throw new Error("No local Chrome/Chromium found — install Chrome or set CHROME_PATH.");
+  }
+  const dir = mkdtempSync(path.join(tmpdir(), "pi-web-capture-"));
+  try {
+    const outPath = path.join(dir, "page.pdf");
+    await runChrome(
+      buildPdfArgs({
+        chromePath,
+        outPath,
+        userDataDir: path.join(dir, "profile"),
+        url: opts.url,
+      }),
+      outPath,
+      opts.signal,
+      opts.timeoutMs,
+    );
+    return await readCapture(outPath, "application/pdf");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-web",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Pi extension for web search, page extraction, Firecrawl scraping/crawling, and Crawl4AI headless browser crawling.",
   "type": "module",
   "license": "MIT",

package/skills/pi-web/SKILL.md

@@ -15,8 +15,8 @@ Use the **7 unified tools** from the `pi-web` extension for all web-related task
 | `web_extract` | Extract readable content from a URL | Static (JSDOM) → Dynamic (Firecrawl) → Full (Crawl4AI) → agy (model-backed) |
 | `web_map` | Discover URLs from a site | Firecrawl Map (only option) |
 | `web_crawl` | Crawl multiple pages from a site | Light (Firecrawl) or Full (Crawl4AI) |
-| `web_screenshot` | Capture page screenshot as PNG | Crawl4AI (only option) |
-| `web_pdf` | Generate page PDF | Crawl4AI (only option) |
+| `web_screenshot` | Capture page screenshot as PNG | Crawl4AI daemon (public URLs) or local headless Chrome (localhost/LAN/file URLs — auto-detected) |
+| `web_pdf` | Generate page PDF | Crawl4AI daemon (public URLs) or local headless Chrome (localhost/LAN/file URLs — auto-detected) |
 | `web_status` | Check provider configuration and health | — |
 
 ## Decision Tree