pi-web-kit 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,24 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [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
+
+- Extract install telemetry to separate `src/install-telemetry.ts` module for consistency with monorepo guidelines.
+- Add root `index.ts` re-export and fix `pi.extensions` path to `./index.ts`.
+- Update `peerDependencies` to use `*` for Pi core packages.
+- Add Pi core packages to `devDependencies` for type checking.
+- Update `author` field to full name.
+
 ## [0.1.5] - 2026-05-20
 
 ### 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

@@ -1,6 +1,3 @@
-import { readFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
 import { type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -8,16 +5,11 @@ 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";
-
-const PACKAGE_NAME = "pi-web-kit";
-const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
-const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
-
-type InstallTelemetryState = { lastReportedVersion?: string };
+import { reportInstallTelemetry } from "../src/install-telemetry.js";
 
 export default function (pi: ExtensionAPI) {
   void reportInstallTelemetry();
@@ -108,6 +100,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";
@@ -160,72 +215,41 @@ 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.`;
-}
-
-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.`;
+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 });
 }
 
-function readJsonFile(path: string): unknown {
-  try {
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return {};
-  }
-}
-
-function isTruthyEnvFlag(value: string | undefined): boolean {
-  if (!value) return false;
-  return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
+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 });
 }
 
-function isInstallTelemetryEnabled(): boolean {
-  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
-  if (isTruthyEnvFlag(process.env.CI) || isTruthyEnvFlag(process.env.GITHUB_ACTIONS)) return false;
-  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
-  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as { enableInstallTelemetry?: unknown };
-  return settings.enableInstallTelemetry !== 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 getPackageVersion(): string {
-  try {
-    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version?: unknown };
-    return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
+function buildSearchDescription(_provider: SearchProviderName): string {
+  return "Search the web. Use query or queries; returns compact results grouped by query.";
 }
 
-function getInstallTelemetryUserAgent(version: string): string {
-  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
-  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
-  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
+function buildFetchDescription(_provider: FetchProviderName): string {
+  return "Fetch URL content. Results are cached by URL/options; use offset/limit to read long pages in chunks.";
 }
 
-export async function reportInstallTelemetry(): Promise<void> {
-  try {
-    if (!isInstallTelemetryEnabled()) return;
-
-    const version = getPackageVersion();
-    const telemetryDir = join(getAgentDir(), "extensions");
-    const statePath = join(telemetryDir, "pi-web-kit-install.json");
-    const state = readJsonFile(statePath) as InstallTelemetryState;
-    if (state.lastReportedVersion === version) return;
-
-    await mkdir(telemetryDir, { recursive: true });
-    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`);
-
-    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
-    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
-      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
-      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
-    });
-  } catch {
-    // Best-effort install telemetry: ignore settings, filesystem, and network failures.
-  }
-}
 
 function normalizeQueries(params: Record<string, any>): string[] {
   const raw = Array.isArray(params.queries) ? params.queries : params.query ? [params.query] : [];
@@ -315,12 +339,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" };
@@ -343,11 +392,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" })) };
 }

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./extensions/index.js";

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "pi-web-kit",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Context-efficient web search and fetch tools for Pi.",
   "type": "module",
   "license": "MIT",
-  "author": "jvm",
+  "author": "Jose Mocito",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jvm/pi-mono.git",
@@ -20,6 +20,9 @@
     "pi",
     "web-search",
     "web-fetch",
+    "library-docs",
+    "code-search",
+    "context7",
     "exa",
     "firecrawl"
   ],
@@ -28,10 +31,11 @@
   },
   "pi": {
     "extensions": [
-      "./extensions/index.ts"
+      "./index.ts"
     ]
   },
   "files": [
+    "index.ts",
     "extensions",
     "src",
     "README.md",
@@ -54,8 +58,12 @@
     "typebox": "*"
   },
   "devDependencies": {
+    "@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",
+    "tsx": "^4.22.4",
+    "typebox": "^1.1.39",
     "typescript": "^6.0.3"
   },
   "publishConfig": {

package/src/config.ts

@@ -26,6 +26,7 @@ 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();
@@ -63,9 +64,9 @@ 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;
+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;
 
-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/install-telemetry.ts

@@ -0,0 +1,69 @@
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const PACKAGE_NAME = "pi-web-kit";
+const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
+const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+
+type InstallTelemetryState = { lastReportedVersion?: string };
+
+function readJsonFile(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function isTruthyEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
+}
+
+function isInstallTelemetryEnabled(): boolean {
+  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
+  if (isTruthyEnvFlag(process.env.CI) || isTruthyEnvFlag(process.env.GITHUB_ACTIONS)) return false;
+  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as { enableInstallTelemetry?: unknown };
+  return settings.enableInstallTelemetry !== false;
+}
+
+function getPackageVersion(): string {
+  try {
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version?: unknown };
+    return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function getInstallTelemetryUserAgent(version: string): string {
+  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
+  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
+  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
+}
+
+export async function reportInstallTelemetry(): Promise<void> {
+  try {
+    if (!isInstallTelemetryEnabled()) return;
+
+    const version = getPackageVersion();
+    const telemetryDir = join(getAgentDir(), "extensions");
+    const statePath = join(telemetryDir, "pi-web-kit-install.json");
+    const state = readJsonFile(statePath) as InstallTelemetryState;
+    if (state.lastReportedVersion === version) return;
+
+    await mkdir(telemetryDir, { recursive: true });
+    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`);
+
+    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
+    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
+      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
+      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
+    });
+  } catch {
+    // Best-effort install telemetry: ignore settings, filesystem, and network failures.
+  }
+}

package/src/providers/context7.ts

@@ -0,0 +1,105 @@
+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>(`${BASE_URL}/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>(`${BASE_URL}/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 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.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";
 
@@ -61,4 +61,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: { "content-type": "application/json", "x-api-key": this.key },
+      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/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/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>;
 }