@bacnh85/pi-web 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to `pi-web` will be documented in this file.
+
+## 0.5.6 (2026-08-01)
+
+### Features
+
+- **Portable instructions:** pi-web now self-injects its backend-selection routing guidance via a gated `before_agent_start` hook (fires only when a `web_*` tool is active). This guidance previously lived in the global `~/.pi/agent/AGENTS.md`; moving it here makes it travel with the package and carry zero overhead when pi-web is absent. Per-tool `promptGuidelines` are unchanged.
+
+## 0.5.5 (2026-07-30)
+
+### Improvements
+
+- Patch version bump for release sync and package documentation update.
+
+## 0.5.4 (2026-07-24)
+
+### Fixes
+
+- Fixed best-effort error handling for `web_extract` and improved fallback reporting across search and extraction modules.
+
+## 0.5.3 (2026-07-20)
+
+### Features
+
+- Support Pi 0.82.0 ESM extension loading.
+
+## 0.4.0 (2026-07-10)
+
+### Features
+
+- Consolidated 14 backend-specific tools into 7 unified tools (`web_search`, `web_extract`, `web_map`, `web_crawl`, `web_screenshot`, `web_pdf`, `web_status`).
+- Auto-selection and adaptive fallback between static (JSDOM), dynamic (Firecrawl), and full (Crawl4AI) backends.

package/README.md

@@ -1,4 +1,4 @@
-# pi-web v0.5
+# @bacnh85/pi-web
 
 Pi extension for **unified web search, content extraction, site crawling, and page capture**.
 
@@ -10,14 +10,6 @@ Auto-selects the best backend from SearXNG (self-hosted), Brave Search, Firecraw
 pi install npm:@bacnh85/pi-web
 ```
 
-From this repository:
-
-```bash
-pi install ./extensions/pi-web
-# or test directly
-pi -e ./extensions/pi-web
-```
-
 ## Configuration
 
 Environment lookup order:
@@ -45,6 +37,10 @@ Variables:
 
 Secrets are never printed; `web_status` reports only presence/source.
 
+### Always-on routing guidance
+
+When any `web_*` tool is active, pi-web injects a condensed backend-selection protocol (SearXNG → Brave → Firecrawl ordering, Firecrawl precision/scrape caveats, source-citation rule) into the system prompt via a `before_agent_start` hook. This travels with the package — no edits to `~/.pi/agent/AGENTS.md` are required — and carries zero overhead when pi-web is not loaded.
+
 ## Tools
 
 ### `web_search` — Unified search
@@ -218,6 +214,10 @@ v0.4 replaces the 14 individual backend-specific tools with 7 unified tools:
 
 All v0.3 tool names were removed in v0.4. Update any agent instructions or skills that reference the old names.
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## Development
 
 ```bash

package/extensions/index.ts

@@ -48,6 +48,35 @@ const crawl4aiControlSchema = {
   crawl4ai_api_token: Type.Optional(Type.String({ description: "Override $CRAWL4AI_API_TOKEN." })),
 };
 
+// ---------------------------------------------------------------------------
+// Always-on routing guidance (injected only when a web_* tool is active)
+// ---------------------------------------------------------------------------
+
+// Portable home for the pi-web backend-selection protocol. Previously forced
+// always-on via ~/.pi/agent/AGENTS.md; now self-injected by this extension so
+// the guidance travels with the package and disappears when pi-web is absent.
+const WEB_ROUTING_GUIDANCE = `## Web Tool Routing (pi-web)
+
+The pi-web extension provides 7 unified tools that auto-select the best backend:
+
+- **\`web_search\`** — Search the web (auto: SearXNG → Brave → Firecrawl). Use
+  \`backend\` for explicit control, \`engines\` for SearXNG tuning.
+- **\`web_extract\`** — Extract readable content from a URL (auto: static JSDOM
+  → dynamic Firecrawl → full Crawl4AI). Use \`mode\` for explicit control.
+- **\`web_map\`** — Discover URLs from a site (Firecrawl Map).
+- **\`web_crawl\`** — Crawl multiple pages. \`mode: "light"\` (Firecrawl) or
+  \`mode: "full"\` (Crawl4AI).
+- **\`web_screenshot\`** / **\`web_pdf\`** — Visual/page capture (Crawl4AI).
+- **\`web_status\`** — Check provider configuration and server health.
+
+Backend selection rules:
+
+- Firecrawl Search has poor semantic accuracy on domain-specific queries; prefer
+  SearXNG or Brave for precision (force via \`backend\`).
+- Firecrawl Scrape fails on bot-protected sites (e.g. Ansible docs); Crawl4AI
+  handles those (force via \`mode: "full"\`).
+- Always cite source URLs when web results materially support an answer.`;
+
 
 // ---------------------------------------------------------------------------
 // Extension entry point
@@ -414,4 +443,13 @@ export default function piWebExtension(pi: ExtensionAPI) {
     },
   });
 
+  // ── Always-on routing guidance ──────────────────────────────────────────
+  // 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 ?? [];
+    if (!active.some((t) => t.startsWith("web_"))) return;
+    return { systemPrompt: `${event.systemPrompt}\n\n${WEB_ROUTING_GUIDANCE}` };
+  });
+
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-web",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Pi extension for web search, page extraction, Firecrawl scraping/crawling, and Crawl4AI headless browser crawling.",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,7 @@
   },
   "files": [
     "README.md",
+    "CHANGELOG.md",
     "extensions/index.ts",
     "extensions/lib/",
     "extensions/types.d.ts",