@bacnh85/pi-web 0.5.5 → 0.5.7

package/CHANGELOG.md

@@ -1,7 +1,19 @@
 # Changelog
 
+## 0.5.7 (2026-08-05)
+
+### Improvements
+
+- Patch version bump for release sync and package documentation update.
+
 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

package/README.md

@@ -37,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

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,13 +1,13 @@
 {
   "name": "@bacnh85/pi-web",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Pi extension for web search, page extraction, Firecrawl scraping/crawling, and Crawl4AI headless browser crawling.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
-  "homepage": "https://github.com/bacnh85/pi-extensions#readme",
+  "homepage": "https://github.com/bacnh85/pi-extensions/tree/main/pi-web",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bacnh85/pi-extensions.git",