pi-web-kit 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -1,13 +1,19 @@
 # Changelog
 
-## 0.2.3 - 2026-07-17
-
 All notable changes to this project will be documented in this file.
 
 This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning for releases.
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-07-28
+
+### Changed
+
+- Rewrite `library_search`, `library_docs`, `web_search`, and `code_search` prompts so `library_docs` is the default for versioned library/framework/SDK docs (even familiar libraries), `library_search` is reserved for inspecting candidate matches, and `web_search`/`code_search` defer to it. Removes the "ambiguous library" wording that suppressed calls to well-known libraries. The `web_search`/`code_search` deferrals are emitted only when Context7 is configured, so installations without `CONTEXT7_API_KEY` are unaffected. Provider behavior and tool schemas are unchanged.
+
+## [0.2.3] - 2026-07-17
+
 ### Fixed
 
 - Honor project-local config only after Pi confirms project trust.
@@ -24,6 +30,10 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [0.2.1] - 2026-06-14
 
+### Changed
+
+- Simplify provider, configuration, cache, and URL handling while preserving the public tool surface.
+
 ## [0.2.0] - 2026-06-13
 
 ### Added

package/README.md

@@ -1,20 +1,16 @@
 # pi-web-kit
 
-Context-efficient web and developer search tools for [Pi](https://pi.dev): `web_search`, `web_fetch`, `library_search`, `library_docs`, and `code_search`.
+Give [Pi](https://pi.dev) current web knowledge, authoritative library docs, and real-world code examples without flooding model context.
 
-`pi-web-kit` provides provider-backed search, page fetching, library docs lookup, and code-context search with bounded output, chunked reads, URL validation, and an in-memory fetch cache designed for agent workflows.
+`pi-web-kit` combines search, page reading, version-aware documentation, and code research behind five agent-ready tools with bounded, cache-aware output.
 
 ## Features
 
-- `web_search` for current/external web information, including multi-query searches.
-- `web_fetch` for reading one or more URLs, with `offset` / `limit` chunk reads for long pages.
-- `library_search` and `library_docs` for library resolution and current, version-aware documentation/code examples.
-- `code_search` for practical examples and implementation context.
-- Multiple provider backends: Exa MCP, Exa API, TinyFish, Brave Search, Firecrawl, markdown.new, Context7, and Exa Code.
-- Provider-tailored tool schemas at Pi startup/reload.
-- URL validation: HTTP(S)-only, no embedded credentials, fragment stripping, duplicate removal, and length/count limits.
-- In-memory fetch cache with TTL, LRU eviction, max entry count, max byte count, and cache keys based on provider/config/fetch-affecting options.
-- Bounded provider concurrency and network timeouts.
+- **Research the live web** — search current information and read single or multiple pages without leaving Pi.
+- **Use docs that match the task** — resolve libraries and retrieve focused, version-aware documentation with code examples.
+- **Find proven implementation patterns** — search practical usage, setup, migrations, and error context across real code.
+- **Spend context wisely** — compact search results, chunked page reads, bounded output, and fetch caching keep research useful without overwhelming the model.
+- **Choose your providers** — mix Exa, TinyFish, Brave, Firecrawl, markdown.new, Context7, and Exa Code based on coverage, cost, and credentials.
 
 ## Installation
 

package/extensions/index.ts

@@ -38,8 +38,17 @@ function registerTools(pi: ExtensionAPI, startupConfig: ReturnType<typeof resolv
     name: "web_search",
     label: "Web Search",
     description: buildSearchDescription(startupConfig.provider_search),
-    promptSnippet: "Find current or external web information.",
-    promptGuidelines: ["Use web_search to find current or external web information."],
+    promptSnippet: startupConfig.apiKeys.context7
+      ? "Search the live web for current events, news, and non-library topics."
+      : "Find current or external web information.",
+    promptGuidelines: [
+      startupConfig.apiKeys.context7
+        ? "Use web_search for current events, news, and non-library topics."
+        : "Use web_search to find current or external web information.",
+      ...(startupConfig.apiKeys.context7
+        ? ["Prefer library_docs over web_search for versioned library/framework/SDK documentation."]
+        : []),
+    ],
     parameters: buildSearchSchema(startupConfig.provider_search),
     async execute(_toolCallId, rawParams, signal, onUpdate, ctx) {
       const params = rawParams as Record<string, any>;
@@ -108,9 +117,9 @@ function registerTools(pi: ExtensionAPI, startupConfig: ReturnType<typeof resolv
     pi.registerTool({
       name: "library_search",
       label: "Library Search",
-      description: "Resolve library, package, framework, SDK, API, or CLI names to canonical library IDs.",
-      promptSnippet: "Resolve a library name to a canonical library ID before querying docs.",
-      promptGuidelines: ["Use library_search when a library/framework/package is ambiguous or you need a canonical library ID."],
+      description: "Resolve library, package, framework, SDK, API, or CLI names to canonical library IDs with version, trust, and snippet metadata. Use when you need to inspect candidate matches (official sources, versions, forks); library_docs resolves names automatically.",
+      promptSnippet: "List candidate library IDs; library_docs resolves names on its own.",
+      promptGuidelines: ["Use library_search only to inspect matching libraries (official source, versions, forks) before a precise library_docs call.", "Not needed for ordinary doc lookups — library_docs resolves a libraryName for you."],
       parameters: buildLibrarySearchSchema(),
       async execute(_toolCallId, rawParams, signal, _onUpdate, ctx) {
         const params = rawParams as Record<string, any>;
@@ -126,9 +135,9 @@ function registerTools(pi: ExtensionAPI, startupConfig: ReturnType<typeof resolv
     pi.registerTool({
       name: "library_docs",
       label: "Library Docs",
-      description: "Fetch current, version-aware documentation and code examples for a library.",
-      promptSnippet: "Get current library documentation and code examples.",
-      promptGuidelines: ["Use library_docs for current APIs, framework behavior, SDK examples, package docs, and version-specific library questions."],
+      description: "Fetch current, version-aware documentation and code examples for a library. Pass libraryName to resolve it automatically, or a known libraryId.",
+      promptSnippet: "Get current, version-aware library/framework/SDK docs and code examples.",
+      promptGuidelines: ["Use library_docs for any library, framework, SDK, API, or CLI — even familiar ones like React, Next.js, Prisma, or Express. Training data may be outdated; this returns version-specific docs.", "Prefer library_docs over web_search or your own knowledge for library/API questions. Pass libraryName and query; you rarely need library_search first."],
       parameters: buildLibraryDocsSchema(),
       async execute(_toolCallId, rawParams, signal, _onUpdate, ctx) {
         const params = rawParams as Record<string, any>;
@@ -154,7 +163,10 @@ function registerTools(pi: ExtensionAPI, startupConfig: ReturnType<typeof resolv
       label: "Code Search",
       description: "Find practical code examples, usage patterns, setup snippets, migrations, and error context.",
       promptSnippet: "Find real-world code examples, usage patterns, migrations, and error context.",
-      promptGuidelines: ["Use code_search for real-world code examples, GitHub/open-source usage patterns, API syntax examples, setup snippets, migrations, and error messages."],
+      promptGuidelines: [
+        "Use code_search for real-world code examples, usage patterns, setup snippets, migrations, and error context from open source.",
+        ...(startupConfig.apiKeys.context7 ? ["Prefer library_docs for official API/reference documentation."] : []),
+      ],
       parameters: buildCodeSearchSchema(),
       async execute(_toolCallId, rawParams, signal, _onUpdate, ctx) {
         const params = rawParams as Record<string, any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-kit",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Context-efficient web search and fetch tools for Pi.",
   "type": "module",
   "license": "MIT",
@@ -58,13 +58,13 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.0",
-    "@earendil-works/pi-coding-agent": "^0.80.0",
-    "@earendil-works/pi-tui": "^0.80.0",
-    "@types/node": "^26.1.0",
-    "tsx": "^4.23.0",
-    "typebox": "^1.3.4",
-    "typescript": "^6.0.3"
+    "@earendil-works/pi-ai": "^0.80.10",
+    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-tui": "^0.80.10",
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
+    "typebox": "^1.3.6",
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"