pi-web-kit 0.1.6 → 0.2.1

package/CHANGELOG.md

@@ -1,11 +1,21 @@
 # Changelog
 
+## 0.2.1 - 2026-06-14
+
 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.0] - 2026-06-13
+
+### Added
+
+- Add `library_search` and `library_docs` tools backed by Context7.
+- Add `code_search` backed by Exa Code.
+- Gate optional developer-search tool registration on API key availability.
+
 ## [0.1.6] - 2026-06-06
 
 ### Changed

package/README.md

@@ -1,14 +1,16 @@
 # pi-web-kit
 
-Context-efficient web search and fetch tools for [Pi](https://pi.dev): `web_search` and `web_fetch`.
+Context-efficient web and developer search tools for [Pi](https://pi.dev): `web_search`, `web_fetch`, `library_search`, `library_docs`, and `code_search`.
 
-`pi-web-kit` provides provider-backed search and page fetching with bounded output, chunked reads, URL validation, and an in-memory fetch cache designed for agent workflows.
+`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.
 
 ## 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.
-- Multiple provider backends: Exa MCP, Exa API, TinyFish, Brave Search, Firecrawl, and markdown.new.
+- `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.
@@ -96,7 +98,8 @@ PI_OFFLINE=1        # disables install/update telemetry
 PI_TELEMETRY=0      # disables install/update telemetry
 PI_WEB_KIT_PROVIDER_SEARCH=exa_mcp|exa|tinyfish|brave|firecrawl
 PI_WEB_KIT_PROVIDER_FETCH=exa_mcp|exa|tinyfish|markdown_new|firecrawl
-EXA_API_KEY=...
+EXA_API_KEY=...          # enables Exa provider and code_search
+CONTEXT7_API_KEY=...     # enables library_search and library_docs
 TINYFISH_API_KEY=...
 BRAVE_SEARCH_API_KEY=...
 FIRECRAWL_API_KEY=...
@@ -118,7 +121,9 @@ Example:
   "provider_search": "firecrawl",
   "provider_fetch": "markdown_new",
   "apiKeys": {
-    "firecrawl": "..."
+    "firecrawl": "...",
+    "context7": "...",
+    "exa": "..."
   },
   "markdownNew": {
     "method": "auto",
@@ -165,6 +170,39 @@ Fetches page content with the active fetch provider. Results are cached in memor
 
 Provider-specific parameters are exposed only for the configured provider, such as TinyFish `format`, markdown.new `method` / `retainImages`, or Firecrawl `format`, `waitFor`, `mobile`, `location`, and `maxAge`.
 
+### `library_search`
+
+Resolves packages, frameworks, SDKs, APIs, CLIs, and libraries to canonical library IDs.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `libraryName` | string | Library/package/framework name to search for. |
+| `query` | string | Optional user task/question for relevance ranking. |
+| `fast` | boolean | Skip LLM reranking for lower latency. |
+| `limit` | integer | Maximum libraries to return. Range: 1-20. Default: 10. |
+
+### `library_docs`
+
+Fetches current docs and code snippets for a library. Provide `libraryId`, or provide `libraryName` and the tool resolves the best match first.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `libraryId` | string | Canonical library ID, such as `/vercel/next.js`. |
+| `libraryName` | string | Library name to resolve when `libraryId` is not known. |
+| `query` | string | Specific docs question or coding task. |
+| `version` | string | Optional version/tag to pin, appended as `@version`. |
+| `fast` | boolean | Skip LLM reranking for lower latency. |
+| `limit` | integer | Maximum code and info snippets to return. Range: 1-20. Default: 10. |
+
+### `code_search`
+
+Finds practical code examples, implementation context, setup snippets, migrations, usage patterns, and error-message research.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `query` | string | Code-context query. |
+| `tokensNum` | `"dynamic"` or integer | Output token target. Integer range: 50-100000. Default: `"dynamic"`. |
+
 ## Cache and limits
 
 `web_fetch` uses an in-memory cache for the current Pi process.
@@ -183,7 +221,7 @@ Cache keys include the provider, canonical URL, fetch-affecting parameters, rele
 
 ## Privacy and security
 
-`pi-web-kit` sends search queries and fetched URLs to the configured provider. Fetch providers may also receive provider-specific options. API keys are read from environment variables or local config files and are used only for provider requests.
+`pi-web-kit` sends search queries and fetched URLs to the configured provider. Developer-search tools send library/doc queries to Context7 and code-context queries to Exa when those tools are enabled. Fetch providers may also receive provider-specific options. API keys are read from environment variables or local config files and are used only for provider requests.
 
 The extension rejects non-HTTP(S) URLs and URLs with embedded username/password credentials. Provider responses are not sandboxed; they are returned to Pi as tool output.
 

package/extensions/index.ts

@@ -5,7 +5,7 @@ import { fetchCache, type CachedPage } from "../src/cache.js";
 import { resolveConfig } from "../src/config.js";
 import { DEFAULT_FETCH_LIMIT, DEFAULT_NUM_RESULTS, MAX_LIMIT, MAX_NUM_RESULTS, MAX_OFFSET, MAX_QUERY_COUNT, MAX_URL_COUNT, MULTI_FETCH_LIMIT } from "../src/limits.js";
 import { truncateText } from "../src/http.js";
-import { createFetchProvider, createSearchProvider } from "../src/providers/index.js";
+import { createCodeSearchProvider, createContext7Provider, createFetchProvider, createSearchProvider } from "../src/providers/index.js";
 import { mapFetchResults } from "../src/providers/fallback.js";
 import type { FetchProviderName, SearchProviderName, WebFetchResult } from "../src/types.js";
 import { canonicalWebUrl, normalizeUrlInput } from "../src/urls.js";
@@ -55,8 +55,7 @@ export default function (pi: ExtensionAPI) {
         emitProgress(onUpdate, progress);
       }
       const result = { provider: config.provider_search, queries: grouped };
-      const text = truncateText(JSON.stringify(result, null, 2));
-      return { content: [{ type: "text", text }], details: boundedDetails(result) };
+      return jsonToolResult(result);
     },
     renderCall(args, theme) {
       return new Text(renderWebCall("search", args as Record<string, any>, theme), 0, 0);
@@ -85,13 +84,10 @@ export default function (pi: ExtensionAPI) {
       assertProviderUnchanged("web_fetch", startupConfig.provider_fetch, config.provider_fetch);
       const progress = createProgress("fetch", config.provider_fetch, urls);
       const result = await fetchWithCache(config.provider_fetch, params, urls, signal, config, (event) => {
-        if (event.status === "current") markProgressCurrent(progress, event.url);
-        else if (event.status === "done") markProgressDone(progress, event.url, event.note);
-        else if (event.status === "error") markProgressError(progress, event.url, event.error);
+        updateFetchProgress(progress, event);
         emitProgress(onUpdate, progress);
       });
-      const text = truncateText(JSON.stringify(result, null, 2));
-      return { content: [{ type: "text", text }], details: boundedDetails(result) };
+      return jsonToolResult(result);
     },
     renderCall(args, theme) {
       return new Text(renderWebCall("fetch", args as Record<string, any>, theme), 0, 0);
@@ -100,6 +96,69 @@ export default function (pi: ExtensionAPI) {
       return renderWebResult("fetch", result, options, theme, context);
     },
   });
+
+  if (startupConfig.apiKeys.context7) {
+    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."],
+      parameters: buildLibrarySearchSchema(),
+      async execute(_toolCallId, rawParams, signal, _onUpdate, ctx) {
+        const params = rawParams as Record<string, any>;
+        const libraryName = requiredString(params.libraryName, "libraryName");
+        const query = optionalString(params.query, "query") ?? libraryName;
+        const limit = parseInteger(params.limit, 10, "limit", 1, MAX_NUM_RESULTS);
+        const provider = createContext7Provider(runtimeConfig(pi, ctx.cwd));
+        const result = await provider.searchLibraries({ libraryName, query, fast: params.fast === true, limit }, signal);
+        return jsonToolResult(result);
+      },
+    });
+
+    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."],
+      parameters: buildLibraryDocsSchema(),
+      async execute(_toolCallId, rawParams, signal, _onUpdate, ctx) {
+        const params = rawParams as Record<string, any>;
+        const query = requiredString(params.query, "query");
+        const limit = parseInteger(params.limit, 10, "limit", 1, MAX_NUM_RESULTS);
+        const provider = createContext7Provider(runtimeConfig(pi, ctx.cwd));
+        let libraryId = optionalString(params.libraryId, "libraryId");
+        if (!libraryId) {
+          const libraryName = requiredString(params.libraryName, "libraryName");
+          const resolved = await provider.searchLibraries({ libraryName, query, fast: params.fast === true, limit: 1 }, signal);
+          libraryId = resolved.results[0]?.id;
+          if (!libraryId) throw new Error(`No library found for '${libraryName}'. Try library_search with a more specific name.`);
+        }
+        const result = await provider.getDocs({ libraryId, query, version: optionalString(params.version, "version"), type: "json", fast: params.fast === true, limit }, signal);
+        return jsonToolResult(result);
+      },
+    });
+  }
+
+  if (startupConfig.apiKeys.exa) {
+    pi.registerTool({
+      name: "code_search",
+      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."],
+      parameters: buildCodeSearchSchema(),
+      async execute(_toolCallId, rawParams, signal, _onUpdate, ctx) {
+        const params = rawParams as Record<string, any>;
+        const query = requiredString(params.query, "query");
+        const tokensNum = parseTokensNum(params.tokensNum);
+        const provider = createCodeSearchProvider(runtimeConfig(pi, ctx.cwd));
+        const result = await provider.searchCode({ query, tokensNum }, signal);
+        return jsonToolResult(result);
+      },
+    });
+  }
 }
 
 type ProgressKind = "search" | "fetch";
@@ -152,12 +211,39 @@ export function buildFetchSchema(provider: FetchProviderName) {
   return Type.Object(props, { additionalProperties: false });
 }
 
-function buildSearchDescription(provider: SearchProviderName): string {
-  return `Search the web with startup provider '${provider}'. Use query or queries; returns compact results grouped by query. Restart/reload pi after provider changes.`;
+export function buildLibrarySearchSchema() {
+  return Type.Object({
+    libraryName: Type.String({ description: "Library, package, framework, SDK, API, CLI, or product name", minLength: 1, maxLength: 500 }),
+    query: Type.Optional(Type.String({ description: "User task/question used for relevance ranking", minLength: 1, maxLength: 500 })),
+    fast: Type.Optional(Type.Boolean({ description: "Skip LLM reranking for lower latency" })),
+    limit: Type.Optional(int("Maximum libraries to return", 1, MAX_NUM_RESULTS)),
+  }, { additionalProperties: false });
+}
+
+export function buildLibraryDocsSchema() {
+  return Type.Object({
+    libraryId: Type.Optional(Type.String({ description: "Canonical library ID, for example /vercel/next.js", minLength: 1, maxLength: 500 })),
+    libraryName: Type.Optional(Type.String({ description: "Library name to resolve when libraryId is not known", minLength: 1, maxLength: 500 })),
+    query: Type.String({ description: "Specific docs question or coding task", minLength: 1, maxLength: 500 }),
+    version: Type.Optional(Type.String({ description: "Optional version/tag to pin, appended as @version", minLength: 1, maxLength: 100 })),
+    fast: Type.Optional(Type.Boolean({ description: "Skip LLM reranking for lower latency" })),
+    limit: Type.Optional(int("Maximum code and info snippets to return", 1, MAX_NUM_RESULTS)),
+  }, { additionalProperties: false });
+}
+
+export function buildCodeSearchSchema() {
+  return Type.Object({
+    query: Type.String({ description: "Code-context query for examples, APIs, setup, migrations, or errors", minLength: 1, maxLength: 2000 }),
+    tokensNum: Type.Optional(Type.Union([Type.Literal("dynamic"), int("Target response tokens", 50, MAX_LIMIT)])),
+  }, { additionalProperties: false });
+}
+
+function buildSearchDescription(_provider: SearchProviderName): string {
+  return "Search the web. Use query or queries; returns compact results grouped by query.";
 }
 
-function buildFetchDescription(provider: FetchProviderName): string {
-  return `Fetch URL content with startup provider '${provider}'. Results are cached by URL/options; use offset/limit to read long pages in chunks. Restart/reload pi after provider changes.`;
+function buildFetchDescription(_provider: FetchProviderName): string {
+  return "Fetch URL content. Results are cached by URL/options; use offset/limit to read long pages in chunks.";
 }
 
 
@@ -249,12 +335,37 @@ export function buildCacheKey(provider: FetchProviderName, url: string, params:
   return `${provider}\0${scope}\0${JSON.stringify(affecting)}\0${canonical}`;
 }
 
+function runtimeConfig(pi: ExtensionAPI, cwd: string) {
+  return resolveConfig({ providerSearch: pi.getFlag("web-provider-search"), providerFetch: pi.getFlag("web-provider-fetch") }, cwd);
+}
+
+function jsonToolResult(result: unknown) {
+  const text = truncateText(JSON.stringify(result, null, 2));
+  return { content: [{ type: "text" as const, text }], details: boundedDetails(result) };
+}
+
 function parseInteger(value: unknown, defaultValue: number, name: string, min: number, max: number): number {
   if (value == null) return defaultValue;
   if (typeof value !== "number" || !Number.isInteger(value) || !Number.isFinite(value) || value < min || value > max) throw new Error(`${name} must be a finite integer between ${min} and ${max}.`);
   return value;
 }
 
+function requiredString(value: unknown, name: string): string {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${name} must be a non-empty string.`);
+  return value.trim();
+}
+
+function optionalString(value: unknown, name: string): string | undefined {
+  if (value == null) return undefined;
+  return requiredString(value, name);
+}
+
+function parseTokensNum(value: unknown): "dynamic" | number {
+  if (value == null) return "dynamic";
+  if (value === "dynamic") return "dynamic";
+  return parseInteger(value, 0, "tokensNum", 50, MAX_LIMIT);
+}
+
 function fetchConfigDefaults(provider: FetchProviderName, config?: any): Record<string, unknown> {
   if (provider === "markdown_new") return { method: config?.markdownNew?.method ?? "auto", retainImages: config?.markdownNew?.retainImages ?? false };
   if (provider === "firecrawl") return { onlyMainContent: true, format: "markdown" };
@@ -277,11 +388,74 @@ function assertProviderUnchanged(tool: string, startup: string, runtime: string)
 }
 
 function boundedDetails(value: any): unknown {
-  if (value?.queries && Array.isArray(value.queries)) return { provider: value.provider, queries: value.queries.map((q: any) => ({ query: q.query, resultCount: (q.results ?? []).length, results: (q.results ?? []).map((r: any) => ({ title: r.title, url: r.url, siteName: r.siteName, position: r.position })) })) };
-  if (value?.results && Array.isArray(value.results)) return { provider: value.provider, results: value.results.map((r: any) => ({ url: r.url, fetchedUrl: r.fetchedUrl, title: r.title, format: r.format, cached: r.cached, refreshed: r.refreshed, cacheKey: r.cacheKey, range: r.range, error: r.error })) };
+  if (value?.queries && Array.isArray(value.queries)) return searchDetails(value);
+  if (value?.provider === "context7" && value?.results && Array.isArray(value.results)) return librarySearchDetails(value);
+  if (value?.provider === "context7" && value?.codeSnippets && value?.infoSnippets) return libraryDocsDetails(value);
+  if (value?.provider === "exa" && typeof value.response === "string") return codeSearchDetails(value);
+  if (value?.results && Array.isArray(value.results)) return fetchDetails(value);
   return value;
 }
 
+function searchDetails(value: any) {
+  return {
+    provider: value.provider,
+    queries: value.queries.map((q: any) => ({
+      query: q.query,
+      resultCount: (q.results ?? []).length,
+      results: (q.results ?? []).map((r: any) => ({ title: r.title, url: r.url, siteName: r.siteName, position: r.position })),
+    })),
+  };
+}
+
+function librarySearchDetails(value: any) {
+  return {
+    provider: value.provider,
+    libraryName: value.libraryName,
+    resultCount: value.results.length,
+    results: value.results.map((r: any) => ({ id: r.id, title: r.title, state: r.state, trustScore: r.trustScore, versions: r.versions })),
+  };
+}
+
+function libraryDocsDetails(value: any) {
+  const codeSources = value.codeSnippets.map((s: any) => s.codeId);
+  const infoSources = value.infoSnippets.map((s: any) => s.pageId);
+  return {
+    provider: value.provider,
+    libraryId: value.libraryId,
+    query: value.query,
+    codeSnippetCount: value.codeSnippets.length,
+    infoSnippetCount: value.infoSnippets.length,
+    sources: [...codeSources, ...infoSources].filter(Boolean).slice(0, MAX_NUM_RESULTS),
+  };
+}
+
+function codeSearchDetails(value: any) {
+  return {
+    provider: value.provider,
+    query: value.query,
+    resultsCount: value.resultsCount,
+    outputTokens: value.outputTokens,
+    requestId: value.requestId,
+  };
+}
+
+function fetchDetails(value: any) {
+  return {
+    provider: value.provider,
+    results: value.results.map((r: any) => ({
+      url: r.url,
+      fetchedUrl: r.fetchedUrl,
+      title: r.title,
+      format: r.format,
+      cached: r.cached,
+      refreshed: r.refreshed,
+      cacheKey: r.cacheKey,
+      range: r.range,
+      error: r.error,
+    })),
+  };
+}
+
 function createProgress(kind: ProgressKind, provider: string, labels: string[]): WebProgress {
   return { kind, provider, total: labels.length, completed: 0, items: labels.map((label) => ({ label, status: "pending" })) };
 }
@@ -307,6 +481,20 @@ function markProgressError(progress: WebProgress, label: string, error?: string)
   progress.completed++;
 }
 
+function updateFetchProgress(progress: WebProgress, event: FetchProgressEvent) {
+  switch (event.status) {
+    case "current":
+      markProgressCurrent(progress, event.url);
+      break;
+    case "done":
+      markProgressDone(progress, event.url, event.note);
+      break;
+    case "error":
+      markProgressError(progress, event.url, event.error);
+      break;
+  }
+}
+
 function emitProgress(onUpdate: ((patch: any) => void) | undefined, progress: WebProgress) {
   const verb = progress.kind === "search" ? "Searching web" : "Fetching pages";
   onUpdate?.({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-kit",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Context-efficient web search and fetch tools for Pi.",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,9 @@
     "pi",
     "web-search",
     "web-fetch",
+    "library-docs",
+    "code-search",
+    "context7",
     "exa",
     "firecrawl"
   ],
@@ -55,12 +58,12 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.75.4",
-    "@earendil-works/pi-coding-agent": "^0.75.4",
-    "@earendil-works/pi-tui": "^0.75.4",
+    "@earendil-works/pi-ai": "^0.78.0",
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "@earendil-works/pi-tui": "^0.78.0",
     "@types/node": "^25.6.2",
-    "tsx": "^4.21.0",
-    "typebox": "^1.1.33",
+    "tsx": "^4.22.4",
+    "typebox": "^1.1.39",
     "typescript": "^6.0.3"
   },
   "publishConfig": {

package/src/cache.ts

@@ -22,7 +22,10 @@ export class FetchCache {
   constructor(private opts = { maxEntries: FETCH_CACHE_MAX_ENTRIES, maxBytes: FETCH_CACHE_MAX_BYTES, ttlMs: FETCH_CACHE_TTL_MS }) {}
 
   get totalCachedBytes() { return this.totalBytes; }
-  get size() { this.evictExpired(); return this.entries.size; }
+  get size() {
+    this.evictExpired();
+    return this.entries.size;
+  }
 
   get(key: string, now = Date.now()): CachedPage | undefined {
     const entry = this.entries.get(key);
@@ -47,11 +50,15 @@ export class FetchCache {
     return stored;
   }
 
-  clear() { this.entries.clear(); this.totalBytes = 0; }
+  clear() {
+    this.entries.clear();
+    this.totalBytes = 0;
+  }
 
   private delete(key: string) {
     const old = this.entries.get(key);
-    if (old) this.totalBytes -= old.page.bytes;
+    if (!old) return;
+    this.totalBytes -= old.page.bytes;
     this.entries.delete(key);
   }
 
@@ -65,7 +72,9 @@ export class FetchCache {
   }
 
   private evictExpired(now = Date.now()) {
-    for (const [key, entry] of this.entries) if (now - entry.page.fetchedAt > this.opts.ttlMs) this.delete(key);
+    for (const [key, entry] of this.entries) {
+      if (now - entry.page.fetchedAt > this.opts.ttlMs) this.delete(key);
+    }
   }
 }
 

package/src/config.ts

@@ -5,6 +5,19 @@ import type { FetchProviderName, SearchProviderName, WebKitConfig } from "./type
 
 const SEARCH = ["exa_mcp", "exa", "tinyfish", "brave", "firecrawl"] as const;
 const FETCH = ["exa_mcp", "exa", "tinyfish", "markdown_new", "firecrawl"] as const;
+const DEFAULT_CONFIG: WebKitConfig = {
+  provider_search: "exa_mcp",
+  provider_fetch: "exa_mcp",
+  apiKeys: {},
+  markdownNew: { method: "auto", retainImages: false },
+};
+const PROVIDER_ENV_NAMES = {
+  exa: "EXA_API_KEY",
+  tinyfish: "TINYFISH_API_KEY",
+  brave: "BRAVE_SEARCH_API_KEY",
+  firecrawl: "FIRECRAWL_API_KEY",
+  context7: "CONTEXT7_API_KEY",
+} as const;
 
 type PartialConfig = Partial<Omit<WebKitConfig, "apiKeys" | "markdownNew">> & {
   apiKeys?: Partial<WebKitConfig["apiKeys"]>;
@@ -12,12 +25,7 @@ type PartialConfig = Partial<Omit<WebKitConfig, "apiKeys" | "markdownNew">> & {
 };
 
 export function resolveConfig(flags: { providerSearch?: unknown; providerFetch?: unknown } = {}, cwd = process.cwd(), env = process.env): WebKitConfig {
-  let cfg: WebKitConfig = {
-    provider_search: "exa_mcp",
-    provider_fetch: "exa_mcp",
-    apiKeys: {},
-    markdownNew: { method: "auto", retainImages: false },
-  };
+  let cfg = DEFAULT_CONFIG;
   cfg = merge(cfg, {
     provider_search: env.PI_WEB_KIT_PROVIDER_SEARCH as SearchProviderName | undefined,
     provider_fetch: env.PI_WEB_KIT_PROVIDER_FETCH as FetchProviderName | undefined,
@@ -26,11 +34,13 @@ export function resolveConfig(flags: { providerSearch?: unknown; providerFetch?:
       tinyfish: env.TINYFISH_API_KEY,
       brave: env.BRAVE_SEARCH_API_KEY,
       firecrawl: env.FIRECRAWL_API_KEY,
+      context7: env.CONTEXT7_API_KEY,
     },
   });
   const home = env.HOME ?? homedir();
   for (const path of [join(home, ".pi/agent/pi-web-kit.json"), join(cwd, ".pi-web-kit.json")]) {
-    try { cfg = merge(cfg, JSON.parse(readFileSync(path, "utf8")) as PartialConfig); } catch (e: any) { if (e?.code !== "ENOENT") throw e; }
+    const fileConfig = readConfigFile(path);
+    if (fileConfig) cfg = merge(cfg, fileConfig);
   }
   cfg = merge(cfg, {
     provider_search: flags.providerSearch as SearchProviderName | undefined,
@@ -63,9 +73,16 @@ export function validateFetchProvider(name: string): asserts name is FetchProvid
   if (!FETCH.includes(name as FetchProviderName)) throw new Error(`Unknown fetch provider '${name}'. Expected one of: ${FETCH.join(", ")}.`);
 }
 
-const PROVIDER_ENV_NAMES = { exa: "EXA_API_KEY", tinyfish: "TINYFISH_API_KEY", brave: "BRAVE_SEARCH_API_KEY", firecrawl: "FIRECRAWL_API_KEY" } as const;
+function readConfigFile(path: string): PartialConfig | undefined {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as PartialConfig;
+  } catch (e: any) {
+    if (e?.code !== "ENOENT") throw e;
+    return undefined;
+  }
+}
 
-export function requireKey(config: WebKitConfig, provider: "exa" | "tinyfish" | "brave" | "firecrawl"): string {
+export function requireKey(config: WebKitConfig, provider: "exa" | "tinyfish" | "brave" | "firecrawl" | "context7"): string {
   const key = config.apiKeys[provider];
   const envName = PROVIDER_ENV_NAMES[provider];
   if (!key) throw new Error(`${provider} provider requires ${envName} or apiKeys.${provider} in .pi-web-kit.json / ~/.pi/agent/pi-web-kit.json.`);

package/src/providers/context7.ts

@@ -0,0 +1,111 @@
+import { requestJson } from "../http.js";
+import type { Context7ContextInput, Context7DocsResult, Context7LibrarySearchInput, Context7LibrarySearchResult, WebKitConfig } from "../types.js";
+import { requireKey } from "../config.js";
+
+const BASE_URL = "https://context7.com/api/v2/";
+
+export class Context7Provider {
+  private key: string;
+  constructor(config: WebKitConfig) { this.key = requireKey(config, "context7"); }
+
+  async searchLibraries(input: Context7LibrarySearchInput, signal?: AbortSignal): Promise<Context7LibrarySearchResult> {
+    const query = input.query ?? input.libraryName;
+    const params = new URLSearchParams({ libraryName: input.libraryName, query });
+    addFastParam(params, input.fast);
+    const data = await requestJson<any>(buildApiUrl("libs/search", params), {
+      headers: this.headers(),
+      signal,
+      timeoutMs: 30_000,
+    });
+    const limit = input.limit ?? 10;
+    return {
+      provider: "context7",
+      libraryName: input.libraryName,
+      query,
+      searchFilterApplied: data.searchFilterApplied,
+      results: (data.results ?? []).slice(0, limit).map(toLibraryResult).filter((r: any) => r.id),
+    };
+  }
+
+  async getDocs(input: Context7ContextInput, signal?: AbortSignal): Promise<Context7DocsResult> {
+    const libraryId = withVersion(input.libraryId, input.version);
+    const params = new URLSearchParams({ libraryId, query: input.query, type: input.type ?? "json" });
+    addFastParam(params, input.fast);
+    const data = await requestJson<any>(buildApiUrl("context", params), {
+      headers: this.headers(),
+      signal,
+      timeoutMs: 45_000,
+    });
+    const limit = input.limit ?? 10;
+    return {
+      provider: "context7",
+      libraryId,
+      query: input.query,
+      codeSnippets: (data.codeSnippets ?? []).slice(0, limit).map(toCodeSnippet),
+      infoSnippets: (data.infoSnippets ?? []).slice(0, limit).map(toInfoSnippet),
+      rules: data.rules,
+    };
+  }
+
+  private headers(): HeadersInit {
+    return { authorization: `Bearer ${this.key}` };
+  }
+}
+
+function addFastParam(params: URLSearchParams, fast?: boolean) {
+  if (fast != null) params.set("fast", String(fast));
+}
+
+function buildApiUrl(pathname: "libs/search" | "context", params: URLSearchParams): string {
+  const url = new URL(pathname, BASE_URL);
+  for (const [key, value] of params) url.searchParams.set(key, value);
+  return url.toString();
+}
+
+function toLibraryResult(r: any) {
+  return {
+    id: r.id,
+    title: r.title,
+    description: r.description,
+    branch: r.branch,
+    lastUpdateDate: r.lastUpdateDate,
+    state: r.state,
+    totalTokens: r.totalTokens,
+    totalSnippets: r.totalSnippets,
+    stars: r.stars,
+    trustScore: r.trustScore,
+    benchmarkScore: r.benchmarkScore,
+    versions: r.versions,
+  };
+}
+
+function toCodeSnippet(s: any) {
+  return {
+    codeTitle: s.codeTitle,
+    codeDescription: s.codeDescription,
+    codeLanguage: s.codeLanguage,
+    codeTokens: s.codeTokens,
+    codeId: s.codeId,
+    pageTitle: s.pageTitle,
+    sourceFile: s.sourceFile,
+    isDynamic: s.isDynamic,
+    codeList: s.codeList,
+  };
+}
+
+function toInfoSnippet(s: any) {
+  return {
+    pageId: s.pageId,
+    breadcrumb: s.breadcrumb,
+    content: s.content,
+    contentTokens: s.contentTokens,
+  };
+}
+
+function withVersion(libraryId: string, version?: string): string {
+  const id = libraryId.trim();
+  const v = version?.trim();
+  if (!v) return id;
+  if (id.endsWith(`@${v}`) || id.endsWith(`/${v}`)) return id;
+  return `${id}@${v}`;
+}

package/src/providers/exa-mcp.ts

@@ -73,18 +73,29 @@ function textFromContent(result: any): string {
 function normalizeSearch(result: any) {
   const structured = result?.structuredContent ?? result?.result ?? result;
   const list = structured.results ?? structured.data ?? structured.items;
-  if (Array.isArray(list)) return list.map((r: any, i: number) => ({ title: r.title, url: r.url, snippet: asSnippet(r.snippet ?? r.text ?? r.summary ?? r.highlights), siteName: r.siteName, position: i + 1 })).filter((r: any) => r.url);
+  if (Array.isArray(list)) return list.map(toSearchResult).filter((r: any) => r.url);
   const text = textFromContent(result);
   const urls = [...text.matchAll(/https?:\/\/[^\s)\]}>"']+/g)].map((m) => m[0]);
   return [...new Set(urls)].map((url, i) => ({ url, snippet: i === 0 ? text.slice(0, 1000) : undefined, position: i + 1 }));
 }
 
+function toSearchResult(r: any, index: number) {
+  return {
+    title: r.title,
+    url: r.url,
+    snippet: asSnippet(r.snippet ?? r.text ?? r.summary ?? r.highlights),
+    siteName: r.siteName,
+    position: index + 1,
+  };
+}
+
 function normalizeFetch(result: any, urls: string[]) {
   const structured = result?.structuredContent ?? result?.result ?? result;
   const list = structured.results ?? structured.data ?? structured.pages;
   if (Array.isArray(list)) return urls.map((url, i) => {
     const r = list.find((x: any) => urlsMatch(x.url, url)) ?? list[i];
-    return r ? { url, title: r.title, content: r.markdown ?? r.text ?? r.content ?? r.html, format: "markdown" as const, metadata: r, error: r.error } : { url, error: "No content returned by Exa MCP." };
+    if (!r) return { url, error: "No content returned by Exa MCP." };
+    return { url, title: r.title, content: r.markdown ?? r.text ?? r.content ?? r.html, format: "markdown" as const, metadata: r, error: r.error };
   });
   const text = textFromContent(result);
   return urls.length <= 1 ? [{ url: urls[0] ?? "", content: text, format: "markdown" as const }] : urls.map((url) => ({ url, content: text, format: "markdown" as const }));

package/src/providers/exa.ts

@@ -1,7 +1,7 @@
 import { asSnippet, normalizeUrls, requestJson } from "../http.js";
 import { DEFAULT_NUM_RESULTS } from "../limits.js";
 import { urlsMatch } from "../urls.js";
-import type { FetchInput, FetchProvider, SearchInput, SearchProvider, WebFetchResult, WebKitConfig } from "../types.js";
+import type { ExaCodeInput, ExaCodeResult, FetchInput, FetchProvider, SearchInput, SearchProvider, WebFetchResult, WebKitConfig } from "../types.js";
 import { requireKey } from "../config.js";
 import { applyExaFetchFallbacks } from "./fallback.js";
 
@@ -9,6 +9,10 @@ export class ExaProvider implements SearchProvider, FetchProvider {
   private key: string;
   constructor(private config: WebKitConfig) { this.key = requireKey(config, "exa"); }
 
+  private headers() {
+    return { "content-type": "application/json", "x-api-key": this.key };
+  }
+
   async search(input: SearchInput, signal?: AbortSignal) {
     const body = {
       query: input.query,
@@ -25,7 +29,7 @@ export class ExaProvider implements SearchProvider, FetchProvider {
     };
     const data = await requestJson<any>("https://api.exa.ai/search", {
       method: "POST",
-      headers: { "content-type": "application/json", "x-api-key": this.key },
+      headers: this.headers(),
       body: JSON.stringify(body),
       signal,
       timeoutMs: 30000,
@@ -48,7 +52,7 @@ export class ExaProvider implements SearchProvider, FetchProvider {
     if (urls.length === 0) return { provider: "exa", results: [] };
     const data = await requestJson<any>("https://api.exa.ai/contents", {
       method: "POST",
-      headers: { "content-type": "application/json", "x-api-key": this.key },
+      headers: this.headers(),
       body: JSON.stringify({ urls, text: true, highlights: false }),
       signal,
       timeoutMs: 45000,
@@ -61,4 +65,26 @@ export class ExaProvider implements SearchProvider, FetchProvider {
     }) };
     return applyExaFetchFallbacks(this.config, input, urls, primary, signal);
   }
+
+  async searchCode(input: ExaCodeInput, signal?: AbortSignal): Promise<ExaCodeResult> {
+    const data = await requestJson<any>("https://api.exa.ai/context", {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({
+        query: input.query,
+        tokensNum: input.tokensNum ?? "dynamic",
+      }),
+      signal,
+      timeoutMs: 45_000,
+    });
+    return {
+      provider: "exa",
+      query: data.query ?? input.query,
+      response: data.response ?? "",
+      resultsCount: data.resultsCount,
+      searchTime: data.searchTime,
+      outputTokens: data.outputTokens,
+      requestId: data.requestId,
+    };
+  }
 }

package/src/providers/firecrawl.ts

@@ -48,8 +48,8 @@ export class FirecrawlProvider implements SearchProvider, FetchProvider {
           }),
         });
         const d = data.data ?? data;
-        const selected = format === "html" ? d.html : format === "json" ? d.json : d.markdown;
-        const content = typeof selected === "string" ? selected : selected == null ? undefined : JSON.stringify(selected, null, 2);
+        const selected = selectFirecrawlContent(d, format);
+        const content = stringifyContent(selected);
         return { url: d.url ?? url, content, format, title: d.metadata?.title, metadata: d.metadata ?? d };
       } catch (e) {
         return { url, error: e instanceof Error ? e.message : String(e) };
@@ -58,3 +58,19 @@ export class FirecrawlProvider implements SearchProvider, FetchProvider {
     return { provider: "firecrawl" as const, results };
   }
 }
+
+function selectFirecrawlContent(data: any, format: string): unknown {
+  switch (format) {
+    case "html":
+      return data.html;
+    case "json":
+      return data.json;
+    default:
+      return data.markdown;
+  }
+}
+
+function stringifyContent(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  return value == null ? undefined : JSON.stringify(value, null, 2);
+}

package/src/providers/index.ts

@@ -1,6 +1,7 @@
 import { validateFetchProvider, validateSearchProvider } from "../config.js";
 import type { FetchProvider, SearchProvider, WebKitConfig } from "../types.js";
 import { BraveProvider } from "./brave.js";
+import { Context7Provider } from "./context7.js";
 import { ExaMcpProvider } from "./exa-mcp.js";
 import { ExaProvider } from "./exa.js";
 import { FirecrawlProvider } from "./firecrawl.js";
@@ -28,3 +29,11 @@ export function createFetchProvider(config: WebKitConfig): FetchProvider {
     case "firecrawl": return new FirecrawlProvider(config);
   }
 }
+
+export function createContext7Provider(config: WebKitConfig): Context7Provider {
+  return new Context7Provider(config);
+}
+
+export function createCodeSearchProvider(config: WebKitConfig): ExaProvider {
+  return new ExaProvider(config);
+}

package/src/providers/tinyfish.ts

@@ -34,7 +34,11 @@ export class TinyFishProvider implements SearchProvider, FetchProvider {
       const r = list.find((x: any) => (x.url ?? x.source_url) === url) ?? list[i];
       if (!r) return { url, error: "No content returned by TinyFish." };
       const content = r.text ?? r.content ?? r.markdown ?? r.html;
-      return { url, content: typeof content === "string" ? content : JSON.stringify(content, null, 2), format: input.format ?? r.format ?? "markdown", title: r.title, metadata: r, error: r.error };
+      return { url, content: stringifyContent(content), format: input.format ?? r.format ?? "markdown", title: r.title, metadata: r, error: r.error };
     }) };
   }
 }
+
+function stringifyContent(value: unknown): string | undefined {
+  return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+}

package/src/types.ts

@@ -5,7 +5,7 @@ export type FetchFormat = "markdown" | "html" | "json";
 export interface WebKitConfig {
   provider_search: SearchProviderName;
   provider_fetch: FetchProviderName;
-  apiKeys: Partial<Record<"exa" | "tinyfish" | "brave" | "firecrawl", string>>;
+  apiKeys: Partial<Record<"exa" | "tinyfish" | "brave" | "firecrawl" | "context7", string>>;
   markdownNew: { method: "auto" | "ai" | "browser"; retainImages: boolean };
 }
 
@@ -38,6 +38,77 @@ export interface WebFetchResult {
   results: Array<{ url: string; content?: string; format?: FetchFormat; title?: string; metadata?: Record<string, unknown>; error?: string }>;
 }
 
+export interface Context7LibrarySearchInput {
+  libraryName: string;
+  query?: string;
+  fast?: boolean;
+  limit?: number;
+}
+
+export interface Context7LibrarySearchResult {
+  provider: "context7";
+  libraryName: string;
+  query: string;
+  searchFilterApplied?: boolean;
+  results: Array<{
+    id: string;
+    title?: string;
+    description?: string;
+    branch?: string;
+    lastUpdateDate?: string;
+    state?: string;
+    totalTokens?: number;
+    totalSnippets?: number;
+    stars?: number;
+    trustScore?: number;
+    benchmarkScore?: number;
+    versions?: string[];
+  }>;
+}
+
+export interface Context7ContextInput {
+  libraryId: string;
+  query: string;
+  version?: string;
+  type?: "json";
+  fast?: boolean;
+  limit?: number;
+}
+
+export interface Context7DocsResult {
+  provider: "context7";
+  libraryId: string;
+  query: string;
+  codeSnippets: Array<{
+    codeTitle?: string;
+    codeDescription?: string;
+    codeLanguage?: string;
+    codeTokens?: number;
+    codeId?: string;
+    pageTitle?: string;
+    sourceFile?: string;
+    isDynamic?: boolean;
+    codeList?: Array<{ language: string; code: string }>;
+  }>;
+  infoSnippets: Array<{ pageId?: string; breadcrumb?: string; content: string; contentTokens?: number }>;
+  rules?: unknown;
+}
+
+export interface ExaCodeInput {
+  query: string;
+  tokensNum?: "dynamic" | number;
+}
+
+export interface ExaCodeResult {
+  provider: "exa";
+  query: string;
+  response: string;
+  resultsCount?: number;
+  searchTime?: number;
+  outputTokens?: number;
+  requestId?: string;
+}
+
 export interface SearchProvider {
   search(input: SearchInput, signal?: AbortSignal): Promise<WebSearchResult>;
 }

package/src/urls.ts

@@ -17,10 +17,14 @@ export function normalizeWebUrl(value: string): string {
 export function canonicalWebUrl(value: string): string {
   const parsed = new URL(normalizeWebUrl(value));
   parsed.hostname = parsed.hostname.toLowerCase();
-  if ((parsed.protocol === "https:" && parsed.port === "443") || (parsed.protocol === "http:" && parsed.port === "80")) parsed.port = "";
+  if (isDefaultPort(parsed)) parsed.port = "";
   return parsed.toString();
 }
 
+function isDefaultPort(url: URL): boolean {
+  return (url.protocol === "https:" && url.port === "443") || (url.protocol === "http:" && url.port === "80");
+}
+
 export function normalizeUrlInput(input: { url?: string; urls?: string[] }, maxCount = MAX_URL_COUNT): string[] {
   const raw = [...(Array.isArray(input.urls) ? input.urls : []), ...(input.url ? [input.url] : [])].map((url) => String(url).trim()).filter(Boolean);
   const unique = [...new Set(raw.map(normalizeWebUrl))];
@@ -34,9 +38,12 @@ export function urlsMatch(a: string | undefined, b: string | undefined): boolean
     const ca = canonicalWebUrl(a);
     const cb = canonicalWebUrl(b);
     if (ca === cb) return true;
-    const trimSlash = (s: string) => s.endsWith("/") ? s.slice(0, -1) : s;
-    return trimSlash(ca) === trimSlash(cb);
+    return trimTrailingSlash(ca) === trimTrailingSlash(cb);
   } catch {
     return a === b;
   }
 }
+
+function trimTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}