pi-fox 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Changed
+- `/web-switch` renamed to `/search` with expanded hub (switch, add, add-custom, remove, onboarding)
+- Search provider management moved out of `/browser`; `/browser` now manages browser engine settings only (headless, supervised)
+- `/search <provider-id>` for instant provider switching at runtime (e.g. `/search brave`)
+- `fetch_content` now uses [Turndown](https://github.com/mixmark-io/turndown) for HTML→Markdown conversion (replaces regex tag stripping). Falls back to plain text strip if Turndown throws on malformed HTML.
+- `/browser` command handlers extracted to named async functions: `runProviderSwitch`, `runProviderAdd`, `runProviderRemove`, `runCustomProviderWizard`, `runCollectProviderMeta`, `runCollectTransform`, `runTestTransform`, `saveCustomProvider`
+- `PROVIDER_REGISTRY` changed from `const` to `let` — rebuilt at startup with custom providers appended
+- `ProviderId` widened to `"brave" | "perplexity" | "tavily" | "exa" | "gemini" | (string & {})` to support dynamic custom provider IDs
+
+### Added
+- Custom search provider wizard — add any search API via `/search` → "Add custom provider" without editing source code
+- `buildCustomProviderImpl()` — wraps user-defined config into a `ProviderImpl`, slots into the existing registry, fallback chain, and `/search` automatically
+- Full `async function(query, n, apiKey, fetchJson)` transform contract — handles both request building and response parsing in one user-written function
+- Live raw→mapped test loop in wizard (Step 3): shows raw API JSON and mapped `SearchResult` side by side, flags missing fields before saving
+- Pi agent snippet in transform step — copyable prompt for getting transform help from your pi agent
+- `fetchJsonCapturing` helper — captures raw API response during wizard test without affecting production search paths
+- `TRANSFORM_DRAFT_PATH` template file at `~/.pi/web-cache/custom-provider-draft.js` — editable in any editor or via pi agent
+- Added (dev): `@types/turndown` — TypeScript types for Turndown
+- `turndown` was already listed in `package.json` and is now actively used

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vanitea
+
+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,131 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/vaniteav/pi-fox/main/docs/banner.png" alt="Pi-Fox banner" width="100%">
+
+# pi-fox
+
+> A fox doesn't knock on the door. It finds the gap in the fence, slips through, and comes back with exactly what you sent it for. Pi-Fox is that instinct for your agent — quiet, quick, and it always brings receipts.
+
+[![npm version](https://badge.fury.io/js/pi-fox.svg)](https://badge.fury.io/js/pi-fox)
+[![npm downloads](https://img.shields.io/npm/dw/pi-fox)](https://www.npmjs.com/package/pi-fox)
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L2J320X82M)
+
+</div>
+
+---
+
+Pi-Fox gives your pi agent a full [Playwright](https://playwright.dev/) browser (Firefox by default, Chromium and WebKit supported) — no API key required. Navigate pages, click, type, screenshot, and extract clean readable text out of the box. For better agentic web search, drop in a key for any of four providers — Brave, Tavily, Exa, or Gemini — all with free tiers. Prefer a different one? Use the setup wizard to add it.
+
+With supervised mode, every move is captured and saved to your local filesystem as a chronological audit trail. Run headless by default; flip it visible when you want to watch it work. Change any setting by asking your agent or editing a single JSON file.
+
+Under the hood it's a single TypeScript extension: a `ProviderImpl` registry for search backends, `withSupervisedScreenshot` wrapping every browser action, and `fetchJson` for all API calls — no curl, no shell-outs.
+
+## Install
+
+**Via npm (recommended):**
+```bash
+pi install npm:pi-fox
+```
+
+**Manual:**
+```bash
+git clone https://github.com/vaniteav/pi-fox
+cp -r pi-fox ~/.pi/agent/extensions/
+npx playwright install firefox
+```
+
+## Setup
+
+Load pi and run `/search` — the setup wizard will guide you through picking a search provider and storing your API key.
+
+Search providers are optional. Browser automation works without any key configured.
+
+## Search providers
+
+| Provider | Free tier | Notes |
+|---|---|---|
+| Brave Search | 2,000 queries/mo | [Get API key](https://api.search.brave.com/) |
+| Tavily | 1,000 queries/mo | [Get API key](https://tavily.com/) |
+| Exa | 2,500 queries/mo | [Get API key](https://exa.ai/) |
+| Gemini | Free tier | [Get API key](https://aistudio.google.com/app/apikey) |
+
+You only need one. The first key you configure becomes the active provider automatically. With multiple providers configured, use `/search <provider-id>` to switch instantly at runtime (e.g. `/search brave`).
+
+## Tools
+
+### Browser (15 tools)
+
+| Tool | Description |
+|---|---|
+| `browser_navigate` | Navigate to a URL. |
+| `browser_click` | Click an element by CSS selector, visible text, or ARIA role. |
+| `browser_type` | Type into an input, textarea, or contenteditable element. |
+| `browser_snapshot` | Get the accessibility tree of the current page — structure, roles, and states. |
+| `browser_screenshot` | Take a screenshot, returned as a base64 PNG or JPEG. |
+| `browser_evaluate` | Run arbitrary JavaScript in the page context and return the result. |
+| `browser_wait` | Wait for an element to appear or disappear, or pause for a fixed timeout. |
+| `browser_new_tab` | Open a new browser tab. |
+| `browser_list_tabs` | List all open tabs with their index, URL, and title. |
+| `browser_close_tab` | Close the current tab. |
+| `browser_select_tab` | Switch focus to a tab by its index. |
+| `browser_back` | Navigate back one step in browser history. |
+| `browser_forward` | Navigate forward one step in browser history. |
+| `browser_reload` | Reload the current page. |
+| `browser_close` | Close the entire browser session and free resources. |
+
+### Web (4 tools)
+
+| Tool | Description |
+|---|---|
+| `web_search` | Search the web via your configured provider; supports multi-query, recency filtering, and domain filtering. |
+| `code_search` | Search for code examples, API docs, and Stack Overflow answers; uses Exa when available, falls back to `web_search`. |
+| `fetch_content` | Fetch one or more URLs and extract clean readable text from the HTML. |
+| `get_search_content` | Retrieve cached content from a previous search or fetch by response ID or URL. |
+
+## Commands
+
+- `/browser` — Browser status and settings: engine, headless mode, supervised mode.
+- `/search` — Search provider management: status, switch, add, remove, and onboarding wizard. Use `/search <provider-id>` to switch instantly at runtime (e.g. `/search brave`).
+
+## Supervised mode
+
+Screenshots are saved to `~/Pictures/pi-fox/sessions/<timestamp>/` after every navigation, click, and interaction — a chronological record of everything your agent did in the browser. Supervised mode is **on by default**.
+
+Once you trust the workflow, turn it off:
+
+```json
+{ "browserExt": { "supervised": false } }
+```
+
+Or just ask your agent: *"turn off supervised mode."*
+
+## Configuration
+
+Full example block in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "browserExt": {
+    "supervised": true,
+    "headless": true,
+    "suppressStartupMessage": false,
+    "activeProvider": "brave",
+    "BRAVE_API_KEY": "...",
+    "TAVILY_API_KEY": "...",
+    "EXA_API_KEY": "...",
+    "GEMINI_API_KEY": "..."
+  }
+}
+```
+
+You only need the key(s) for providers you want to use. All settings can also be changed by asking your agent — for example: *"switch to Exa for searches"* or *"run the browser in visible mode."*
+
+## Credits
+
+- Browser automation powered by [Playwright](https://playwright.dev/) (Microsoft)
+- Built for [pi coding agent](https://github.com/earendil-works/pi-coding-agent) by earendil-works
+
+## License
+
+MIT