pi-cloudflare-browser-run 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre@AI
+
+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,107 @@
+# pi-cloudflare-browser-run
+
+Pi extension that gives the model **web browsing tools** backed by
+[Cloudflare Browser Run](https://developers.cloudflare.com/browser-run/) —
+headless Chrome on CF's network. Pages render with a real browser, so
+JS-heavy/SPA sites work, and the request comes from Cloudflare's network
+(not your machine).
+
+No Workers, no proxy: the extension calls Browser Run Quick Actions over
+the v4 REST API directly.
+
+## Tools
+
+| tool | what it does |
+|---|---|
+| `browse` | fetch a public URL, return clean **markdown** text (default; also `screenshot` / `pdf` actions) |
+| `screenshot` | save a PNG of the page locally, returns the file path |
+| `pdf` | save a PDF of the page locally, returns the file path |
+
+## Install
+
+```bash
+pi install npm:pi-cloudflare-browser-run
+```
+
+Restart `pi` if it was already running.
+
+## Auth (required)
+
+The tools call Cloudflare Browser Run on your behalf, so they need a Cloudflare
+API token with **Browser Rendering: Edit** permission plus your account id.
+
+### 1. Create the token (one time)
+
+1. Open https://dash.cloudflare.com/profile/api-tokens
+2. **Create Token** → under *Start with a template* pick
+   **"Browser Rendering: Edit"** (or *Create Custom Token* and add the
+   **Browser Rendering — Edit** permission)
+3. Copy the token (shown once) — it starts with a random string
+4. Find your account id: dashboard URL is
+   `dash.cloudflare.com/<ACCOUNT_ID>/...` (also shown under the account's
+   *Overview* or in the Workers dashboard)
+
+### 2. Give the extension the credentials
+
+Create `~/.pi/agent/cloudflare-browser-run.json` (keys use the `a_b_c`
+form, `cf_` prefix):
+
+```json
+{
+  "cf_api_token": "paste-your-token-here",
+  "cf_account_id": "paste-your-account-id"
+}
+```
+
+Optional: `"cf_api_base"` (default `https://api.cloudflare.com/client/v4`).
+
+If either value is missing the tools reply with a setup hint instead of
+erroring — nothing breaks.
+
+### 3. Verify
+
+```bash
+curl -X POST \
+  "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/markdown" \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://example.com"}'
+```
+
+A `200` with markdown text means the token works.
+
+## Usage
+
+Ask the model to browse something — it will pick the tool itself:
+
+```
+> what's on the Cloudflare blog today?
+> open https://example.com and summarize it
+> screenshot https://news.ycombinator.com
+```
+
+Screenshots/PDFs are saved under
+`/tmp/pi-cloudflare-browser-run/` (macOS/Linux) and the returned path can
+be opened directly.
+
+## Security
+
+- **Public web only**: every URL passes an SSRF guard before the API is
+  called — non-http(s) protocols, localhost, private/reserved IPs, IPv6
+  literals, userinfo, and oversized URLs are rejected.
+- The token is read from the environment at load time; it is never logged
+  and never written to disk by this extension.
+- Browser Run itself identifies its traffic as a bot (`Well-behaved Bot
+  Mode`), which is the compliant way to scrape.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-cloudflare-browser-run",
+  "version": "0.1.0",
+  "description": "Pi extension: web browsing tools (markdown / screenshot / pdf) powered by Cloudflare Browser Run. Headless Chrome on CF's network — JS-rendered pages, login sessions, WebMCP-capable.",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test:unit": "node --import tsx --test tests/unit-*.mjs",
+    "test": "npm run test:unit",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "cloudflare",
+    "browser-run",
+    "browser",
+    "agent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "typebox": "^1.3.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}

package/src/api.ts

@@ -0,0 +1,135 @@
+// Cloudflare Browser Run REST client.
+// Quick Actions are one-shot HTTP calls: headless Chrome on CF's network
+// renders the URL and returns markdown / PNG / PDF. No Workers needed —
+// a scoped API token is enough.
+//
+// Endpoints (v4 API):
+//   POST /accounts/{ACCOUNT_ID}/browser-rendering/{screenshot|markdown|pdf}
+//
+// Security: URL strictness first — only public http(s), localhost / private
+// / reserved IPs / IPv6 literals / userinfo are rejected (SSRF guard).
+
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const homedirPath = (): string => homedir();
+const joinPath = (...parts: string[]): string => join(...parts);
+
+export type Action = "markdown" | "screenshot" | "pdf";
+
+export type ApiResult =
+  | { ok: true; action: Action; content: string | Uint8Array }
+  | { ok: false; action?: Action; content?: undefined; error: string };
+
+const MAX_URL_LENGTH = 2048;
+const DEFAULT_API_BASE = "https://api.cloudflare.com/client/v4";
+
+function isPrivateIp(ip: string): boolean {
+  if (ip === "::1" || ip === "::" || ip === "0.0.0.0") return true;
+  if (ip.startsWith("::ffff:")) ip = ip.slice(7);
+  if (!/^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) return false; // hostname, not an IP
+  const parts = ip.split(".").map(Number);
+  if (parts.some((n) => n < 0 || n > 255)) return true;
+  const [a, b] = parts;
+  return (
+    a === 10 ||
+    a === 127 ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    (a === 100 && b >= 64 && b <= 127) || // CGNAT
+    (a === 192 && b === 0) || // 192.0.0.0/24 (incl. IETF)
+    (a === 198 && (b === 18 || b === 19)) || // benchmarking
+    a >= 224 // multicast/reserved
+  );
+}
+
+/** Reject non-http(s), oversized, userinfo, or SSRF-prone URLs. */
+export function assertSafeUrl(raw: string): string {
+  if (!raw || raw.length > MAX_URL_LENGTH) throw new Error("url too long or empty");
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw new Error("invalid URL");
+  }
+  if (u.protocol !== "http:" && u.protocol !== "https:") throw new Error("only http/https allowed");
+  if (u.username || u.password) throw new Error("userinfo not allowed");
+  if (u.hostname === "localhost") throw new Error("localhost not allowed");
+  const host = u.hostname.toLowerCase();
+  if (/\.local$/.test(host)) throw new Error("local hostnames not allowed");
+  const ipCandidate = host.replace(/^\[|\]$/g, "");
+  if (ipCandidate.includes(":")) throw new Error("IPv6 literal not allowed");
+  if (isPrivateIp(ipCandidate)) throw new Error("private/reserved IP not allowed");
+  return u.toString();
+}
+
+export interface BrowserRunConfig {
+  apiToken: string;
+  accountId: string;
+  apiBase?: string;
+}
+
+/** Read credentials from ~/.pi/agent/cloudflare-browser-run.json.
+ *  Keys use the `a_b_c` form: cf_api_token / cf_account_id / cf_api_base.
+ *  `configPath` is injectable for tests. Returns a config or a setup-hint
+ *  error. */
+export function loadConfig(configPath?: string): BrowserRunConfig | { error: string } {
+  let file: Record<string, string> = {};
+  const p = configPath ?? joinPath(homedirPath(), ".pi", "agent", "cloudflare-browser-run.json");
+  try {
+    file = JSON.parse(readFileSync(p, "utf8")) as Record<string, string>;
+  } catch {
+    // no config file — nothing to read
+  }
+  const apiToken = file["cf_api_token"] ?? file.apiToken;
+  const accountId = file["cf_account_id"] ?? file.accountId;
+  if (!apiToken) {
+    return {
+      error:
+        "cf_api_token missing in ~/.pi/agent/cloudflare-browser-run.json — " +
+        "create a token with Browser Rendering:Edit permission",
+    };
+  }
+  if (!accountId) {
+    return {
+      error:
+        "cf_account_id missing in ~/.pi/agent/cloudflare-browser-run.json — " +
+        "your Cloudflare account id",
+    };
+  }
+  return {
+    apiToken,
+    accountId,
+    apiBase: file["cf_api_base"] ?? file.apiBase ?? DEFAULT_API_BASE,
+  };
+}
+
+export async function browserRunAction(config: BrowserRunConfig, action: Action, rawUrl: string): Promise<ApiResult> {
+  try {
+    const url = assertSafeUrl(rawUrl);
+    const base = (config.apiBase ?? DEFAULT_API_BASE).replace(/\/$/, "");
+    const endpoint = `${base}/accounts/${encodeURIComponent(config.accountId)}/browser-rendering/${action}`;
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${config.apiToken}`,
+        "Content-Type": "application/json",
+        "user-agent":
+          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
+      },
+      body: JSON.stringify({ url }),
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      return { ok: false, error: `Browser Run ${action} failed (HTTP ${res.status}): ${body.slice(0, 200)}` };
+    }
+    if (action === "markdown") {
+      return { ok: true, action, content: await res.text() };
+    }
+    return { ok: true, action, content: new Uint8Array(await res.arrayBuffer()) };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/src/index.ts

@@ -0,0 +1,124 @@
+// pi-cloudflare-browser-run — Pi extension registering web-browsing tools
+// backed by Cloudflare Browser Run Quick Actions.
+//
+// Tools:
+//   browse(url, action?)       read a page as clean markdown (default)
+//   screenshot(url)            save a PNG of the page, returns local path
+//   pdf(url)                   save a PDF of the page, returns local path
+//
+// Auth: CLOUDFLARE_API_TOKEN (Browser Rendering:Edit) + CLOUDFLARE_ACCOUNT_ID
+// env vars. No Workers, no proxy — direct v4 REST calls.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { mkdirSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { browserRunAction, loadConfig, type Action } from "./api.js";
+
+const urlSchema = Type.Object({
+  url: Type.String({ minLength: 1, description: "Public http(s) URL, e.g. https://example.com" }),
+});
+const browseSchema = Type.Object({
+  url: Type.String({ minLength: 1, description: "Public http(s) URL, e.g. https://example.com" }),
+  action: Type.Optional(
+    Type.Union(
+      [
+        Type.Literal("markdown"),
+        Type.Literal("screenshot"),
+        Type.Literal("pdf"),
+      ],
+      { description: "What to extract (default markdown)" },
+    ),
+  ),
+});
+
+const ACTION_LABEL: Record<Action, string> = {
+  markdown: "markdown text",
+  screenshot: "PNG",
+  pdf: "PDF",
+};
+
+function toolResult(text: string) {
+  return { content: [{ type: "text" as const, text }], details: {} };
+}
+
+function saveToTemp(action: Action, data: Uint8Array): string {
+  const dir = join(tmpdir(), "pi-cloudflare-browser-run");
+  mkdirSync(dir, { recursive: true });
+  const ext = action === "screenshot" ? "png" : "pdf";
+  const file = join(dir, `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.${ext}`);
+  writeFileSync(file, data);
+  return file;
+}
+
+export default function (pi: ExtensionAPI) {
+  const config = loadConfig();
+
+  pi.registerTool({
+    name: "browse",
+    label: "Browse",
+    description:
+      "Fetch a public web page in a headless Chrome (Cloudflare Browser Run) " +
+      "and return clean markdown text. Use for ANY web access: reading articles, " +
+      "checking live sites, extracting text from JS-rendered pages.",
+    promptSnippet: "browse a public URL (markdown / screenshot / pdf)",
+    promptGuidelines: [
+      "Prefer browse over guessing for anything that changed recently or lives on the web.",
+      "browse only accepts public http(s) URLs; private/localhost addresses are rejected.",
+    ],
+    parameters: browseSchema,
+    executionMode: "sequential",
+    async execute(_toolCallId, params) {
+      const action: Action = (params.action ?? "markdown") as Action;
+      const cfg = typeof config === "object" && "apiToken" in config ? config : null;
+      if (!cfg) return toolResult(`browse unavailable: ${(config as { error: string }).error}`);
+      const r = await browserRunAction(cfg, action, params.url);
+      if (!r.ok) return toolResult(`browse failed: ${"error" in r ? r.error : "unknown"}`);
+      if (action === "markdown") {
+        const text = String(r.content).slice(0, 100_000);
+        return toolResult(text || "(page returned no readable text)");
+      }
+      const file = saveToTemp(action, r.content as Uint8Array);
+      return toolResult(`${ACTION_LABEL[action]} saved to ${file}`);
+    },
+  });
+
+  pi.registerTool({
+    name: "screenshot",
+    label: "Screenshot",
+    description:
+      "Take a screenshot of a public web page in headless Chrome (Cloudflare " +
+      "Browser Run) and save it locally as PNG. Returns the local file path.",
+    promptSnippet: "screenshot a public URL to PNG",
+    parameters: urlSchema,
+    executionMode: "sequential",
+    async execute(_toolCallId, params) {
+      const cfg = typeof config === "object" && "apiToken" in config ? config : null;
+      if (!cfg) return toolResult(`screenshot unavailable: ${(config as { error: string }).error}`);
+      const r = await browserRunAction(cfg, "screenshot", params.url);
+      if (!r.ok) return toolResult(`screenshot failed: ${"error" in r ? r.error : "unknown"}`);
+      const file = saveToTemp("screenshot", r.content as Uint8Array);
+      return toolResult(`screenshot saved to ${file}`);
+    },
+  });
+
+  pi.registerTool({
+    name: "pdf",
+    label: "Save as PDF",
+    description:
+      "Render a public web page to PDF in headless Chrome (Cloudflare Browser " +
+      "Run) and save it locally. Returns the local file path.",
+    promptSnippet: "save a public URL as PDF",
+    parameters: urlSchema,
+    executionMode: "sequential",
+    async execute(_toolCallId, params) {
+      const cfg = typeof config === "object" && "apiToken" in config ? config : null;
+      if (!cfg) return toolResult(`pdf unavailable: ${(config as { error: string }).error}`);
+      const r = await browserRunAction(cfg, "pdf", params.url);
+      if (!r.ok) return toolResult(`pdf failed: ${"error" in r ? r.error : "unknown"}`);
+      const file = saveToTemp("pdf", r.content as Uint8Array);
+      return toolResult(`pdf saved to ${file}`);
+    },
+  });
+}