pi-web-kit 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -6,6 +6,22 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [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.
+- Keep structured tool output valid JSON under the 50KB limit with continuation metadata.
+- Derive opaque cache scopes from full API keys and hide internal cache keys from tool output.
+- Prevent provider fetch results from being assigned to more than one requested URL.
+- Remove the stale package-local lockfile in favor of the monorepo root lockfile.
+
 ## [0.2.2] - 2026-07-01
 
 ### Changed
@@ -14,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
 
@@ -89,7 +85,7 @@ Tool schemas are tailored to the configured providers at startup/reload, so only
 
 ## Configuration
 
-Resolution order: defaults < environment variables < global config < project config < CLI flags.
+Resolution order: defaults < environment variables < global config < trusted project config < CLI flags. Project config is ignored unless Pi trusts the current project, including in print, JSON, and RPC modes.
 
 ### Environment variables
 
@@ -217,7 +213,7 @@ Finds practical code examples, implementation context, setup snippets, migration
 | Max `numResults` | 20 |
 | Max URL length | 2048 characters |
 
-Cache keys include the provider, canonical URL, fetch-affecting parameters, relevant provider defaults, and a short API-key/account scope marker. `refresh: true` bypasses and replaces the cached entry.
+Cache keys include the provider, canonical URL, fetch-affecting parameters, relevant provider defaults, and an opaque SHA-256 API-key/account scope. Internal cache keys are never returned in tool output. `refresh: true` bypasses and replaces the cached entry.
 
 ## Privacy and security
 
@@ -236,7 +232,7 @@ Report security issues privately. See [SECURITY.md](SECURITY.md).
 | Invalid URL / scheme / credentials error | URL validation rejected the input. | Use an absolute `http:` or `https:` URL without username/password credentials. |
 | Timeout error | Provider request exceeded its timeout. | Retry, reduce URL count, or switch provider. |
 | No content returned | Provider returned no matching content or a redirected/canonicalized response could not be mapped. | Retry with `refresh: true`, fetch a single URL, or switch provider. |
-| Large page is truncated | Tool output is bounded for context efficiency. | Use `offset` and `limit` to continue reading chunks. |
+| Large page is truncated | Tool output is bounded to valid JSON under 50KB. | Continue with the returned `range.nextOffset`. |
 
 ## Development
 

package/extensions/index.ts

@@ -1,10 +1,10 @@
+import { createHash } from "node:crypto";
 import { type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 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 { 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";
@@ -22,17 +22,33 @@ export default function (pi: ExtensionAPI) {
     type: "string",
   });
 
-  const startupConfig = resolveConfig({
-    providerSearch: pi.getFlag("web-provider-search"),
-    providerFetch: pi.getFlag("web-provider-fetch"),
+  let registeredConfig = "";
+  pi.on("session_start", (_event, ctx) => {
+    const startupConfig = runtimeConfig(pi, ctx.cwd, projectIsTrusted(ctx));
+    const signature = toolConfigSignature(startupConfig);
+    if (signature === registeredConfig) return;
+    registerTools(pi, startupConfig);
+    syncOptionalTools(pi, startupConfig);
+    registeredConfig = signature;
   });
+}
 
+function registerTools(pi: ExtensionAPI, startupConfig: ReturnType<typeof resolveConfig>) {
   pi.registerTool({
     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>;
@@ -40,7 +56,7 @@ export default function (pi: ExtensionAPI) {
       const numResults = parseInteger(params.numResults, DEFAULT_NUM_RESULTS, "numResults", 1, MAX_NUM_RESULTS);
       if (queries.length === 0) throw new Error("web_search requires query or queries.");
 
-      const config = resolveConfig({ providerSearch: pi.getFlag("web-provider-search") }, ctx.cwd);
+      const config = runtimeConfig(pi, ctx.cwd, projectIsTrusted(ctx));
       assertProviderUnchanged("web_search", startupConfig.provider_search, config.provider_search);
       const provider = createSearchProvider(config);
       const grouped = [];
@@ -80,7 +96,7 @@ export default function (pi: ExtensionAPI) {
         throw new Error("web_fetch offset range reads require a single url, not urls.");
       }
 
-      const config = resolveConfig({ providerFetch: pi.getFlag("web-provider-fetch") }, ctx.cwd);
+      const config = runtimeConfig(pi, ctx.cwd, projectIsTrusted(ctx));
       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) => {
@@ -101,16 +117,16 @@ export default function (pi: ExtensionAPI) {
     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>;
         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 provider = createContext7Provider(runtimeConfig(pi, ctx.cwd, projectIsTrusted(ctx)));
         const result = await provider.searchLibraries({ libraryName, query, fast: params.fast === true, limit }, signal);
         return jsonToolResult(result);
       },
@@ -119,15 +135,15 @@ export default function (pi: ExtensionAPI) {
     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>;
         const query = requiredString(params.query, "query");
         const limit = parseInteger(params.limit, 10, "limit", 1, MAX_NUM_RESULTS);
-        const provider = createContext7Provider(runtimeConfig(pi, ctx.cwd));
+        const provider = createContext7Provider(runtimeConfig(pi, ctx.cwd, projectIsTrusted(ctx)));
         let libraryId = optionalString(params.libraryId, "libraryId");
         if (!libraryId) {
           const libraryName = requiredString(params.libraryName, "libraryName");
@@ -147,13 +163,16 @@ export default function (pi: ExtensionAPI) {
       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>;
         const query = requiredString(params.query, "query");
         const tokensNum = parseTokensNum(params.tokensNum);
-        const provider = createCodeSearchProvider(runtimeConfig(pi, ctx.cwd));
+        const provider = createCodeSearchProvider(runtimeConfig(pi, ctx.cwd, projectIsTrusted(ctx)));
         const result = await provider.searchCode({ query, tokensNum }, signal);
         return jsonToolResult(result);
       },
@@ -161,6 +180,27 @@ export default function (pi: ExtensionAPI) {
   }
 }
 
+const OPTIONAL_TOOLS = ["library_search", "library_docs", "code_search"];
+
+function toolConfigSignature(config: ReturnType<typeof resolveConfig>): string {
+  return JSON.stringify({
+    search: config.provider_search,
+    fetch: config.provider_fetch,
+    context7: !!config.apiKeys.context7,
+    exa: !!config.apiKeys.exa,
+  });
+}
+
+function syncOptionalTools(pi: ExtensionAPI, config: ReturnType<typeof resolveConfig>) {
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const enabled = [
+    ...(config.apiKeys.context7 ? ["library_search", "library_docs"] : []),
+    ...(config.apiKeys.exa ? ["code_search"] : []),
+  ];
+  const active = pi.getActiveTools().filter((name) => !OPTIONAL_TOOLS.includes(name));
+  pi.setActiveTools([...new Set([...active, ...enabled])]);
+}
+
 type ProgressKind = "search" | "fetch";
 type ProgressItem = { label: string; status: "pending" | "current" | "done" | "error"; note?: string; error?: string };
 type WebProgress = { kind: ProgressKind; provider: string; total: number; completed: number; items: ProgressItem[] };
@@ -320,7 +360,7 @@ export async function fetchWithCache(providerName: FetchProviderName, params: Re
 export function pageSlice(page: CachedPage, offset: number, limit: number, cached: boolean, refreshed: boolean) {
   const total = page.content.length;
   const content = page.content.slice(offset, offset + limit);
-  return { url: page.requestedUrl ?? page.url, fetchedUrl: page.url, title: page.title, content, format: page.format, cached, refreshed, cacheKey: page.cacheKey, range: { offset, limit, returned: content.length, total, truncated: offset > 0 || offset + content.length < total, hasPrevious: offset > 0, hasNext: offset + content.length < total } };
+  return { url: page.requestedUrl ?? page.url, fetchedUrl: page.url, title: page.title, content, format: page.format, cached, refreshed, range: { offset, limit, returned: content.length, total, truncated: offset > 0 || offset + content.length < total, hasPrevious: offset > 0, hasNext: offset + content.length < total, nextOffset: offset + content.length < total ? offset + content.length : undefined } };
 }
 
 export function buildCacheKey(provider: FetchProviderName, url: string, params: Record<string, any>, config?: any): string {
@@ -335,13 +375,163 @@ 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 projectIsTrusted(ctx: { isProjectTrusted?: () => boolean }): boolean {
+  return typeof ctx.isProjectTrusted === "function" && ctx.isProjectTrusted() === true;
+}
+
+function runtimeConfig(pi: ExtensionAPI, cwd: string, projectTrusted: boolean) {
+  return resolveConfig(
+    { providerSearch: pi.getFlag("web-provider-search"), providerFetch: pi.getFlag("web-provider-fetch") },
+    cwd,
+    process.env,
+    { includeProject: projectTrusted },
+  );
+}
+
+const MAX_OUTPUT_BYTES = 50_000;
+
+export function jsonToolResult(result: unknown) {
+  const bounded = boundStructuredResult(result);
+  return { content: [{ type: "text" as const, text: JSON.stringify(bounded) }], details: boundedDetails(bounded) };
+}
+
+function boundStructuredResult(result: unknown): unknown {
+  if (Buffer.byteLength(JSON.stringify(result)) <= MAX_OUTPUT_BYTES) return result;
+
+  if (isFetchResult(result)) {
+    const metadataBounded = limitFetchMetadata(result, 1_000);
+    let low = 0;
+    let high = Math.max(...metadataBounded.results.map((item: any) => typeof item.content === "string" ? item.content.length : 0));
+    const emptyContent = fetchResultWithContentLimit(metadataBounded, 0);
+    if (Buffer.byteLength(JSON.stringify(emptyContent)) > MAX_OUTPUT_BYTES) {
+      return { truncated: true, message: "Fetch metadata exceeded 50KB; retry with fewer URLs." };
+    }
+    let best: unknown = emptyContent;
+    while (low <= high) {
+      const middle = Math.floor((low + high) / 2);
+      const candidate = fetchResultWithContentLimit(metadataBounded, middle);
+      if (Buffer.byteLength(JSON.stringify(candidate)) <= MAX_OUTPUT_BYTES) {
+        best = candidate;
+        low = middle + 1;
+      } else {
+        high = middle - 1;
+      }
+    }
+    return best;
+  }
+
+  if (isSearchResult(result)) return boundSearchResult(result);
+
+  const compact = limitStrings(result, 1_000);
+  if (Buffer.byteLength(JSON.stringify(compact)) <= MAX_OUTPUT_BYTES) return compact;
+  return { truncated: true, message: "Structured result exceeded 50KB; refine the request or use smaller limits." };
+}
+
+function isFetchResult(value: any): value is { provider?: string; results: any[] } {
+  return !!value && Array.isArray(value.results) && value.results.some((item: any) => typeof item?.content === "string" && item?.range);
+}
+
+function isSearchResult(value: any): value is { provider?: string; queries: Array<{ query?: string; results?: any[] }> } {
+  return !!value && Array.isArray(value.queries) && value.queries.every((group: any) => Array.isArray(group?.results));
 }
 
-function jsonToolResult(result: unknown) {
-  const text = truncateText(JSON.stringify(result, null, 2));
-  return { content: [{ type: "text" as const, text }], details: boundedDetails(result) };
+function boundSearchResult(value: { provider?: string; queries: Array<{ query?: string; results?: any[] }> }) {
+  const compact = limitStrings(value, 1_000) as typeof value;
+  const maxSnippet = Math.max(0, ...compact.queries.flatMap((group) => (group.results ?? []).map((item) => typeof item?.snippet === "string" ? item.snippet.length : 0)));
+  let low = 0;
+  let high = maxSnippet;
+  let best = searchResultWithLimits(compact, 0);
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2);
+    const candidate = searchResultWithLimits(compact, middle);
+    if (Buffer.byteLength(JSON.stringify(candidate)) <= MAX_OUTPUT_BYTES) {
+      best = candidate;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+  if (Buffer.byteLength(JSON.stringify(best)) <= MAX_OUTPUT_BYTES) return best;
+
+  low = 0;
+  high = Math.max(0, ...compact.queries.map((group) => group.results?.length ?? 0));
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2);
+    const candidate = searchResultWithLimits(compact, 0, middle);
+    if (Buffer.byteLength(JSON.stringify(candidate)) <= MAX_OUTPUT_BYTES) {
+      best = candidate;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+  return Buffer.byteLength(JSON.stringify(best)) <= MAX_OUTPUT_BYTES
+    ? best
+    : { truncated: true, message: "Search metadata exceeded 50KB; retry with fewer queries or results." };
+}
+
+function searchResultWithLimits(value: { provider?: string; queries: Array<{ query?: string; results?: any[] }> }, snippetChars: number, resultsPerQuery?: number) {
+  return {
+    ...value,
+    queries: value.queries.map((group) => ({
+      ...group,
+      results: (group.results ?? []).slice(0, resultsPerQuery).map((item) => {
+        if (typeof item?.snippet !== "string") return item;
+        if (snippetChars === 0) {
+          const { snippet: _snippet, ...metadata } = item;
+          return metadata;
+        }
+        return { ...item, snippet: safePrefix(item.snippet, snippetChars) };
+      }),
+    })),
+  };
+}
+
+function limitFetchMetadata(value: { provider?: string; results: any[] }, maxChars: number) {
+  return {
+    ...value,
+    results: value.results.map((item: any) => {
+      if (typeof item.content !== "string") return limitStrings(item, maxChars);
+      const content = item.content;
+      return { ...(limitStrings(item, maxChars) as Record<string, unknown>), content };
+    }),
+  };
+}
+
+function fetchResultWithContentLimit(value: { provider?: string; results: any[] }, maxChars: number) {
+  return {
+    ...value,
+    results: value.results.map((item: any) => {
+      if (typeof item.content !== "string" || !item.range) return item;
+      const content = safePrefix(item.content, maxChars);
+      const returned = content.length;
+      const hasNext = item.range.offset + returned < item.range.total;
+      return {
+        ...item,
+        content,
+        range: {
+          ...item.range,
+          returned,
+          truncated: item.range.offset > 0 || hasNext,
+          hasNext,
+          nextOffset: hasNext ? item.range.offset + returned : undefined,
+        },
+      };
+    }),
+  };
+}
+
+function safePrefix(value: string, maxChars: number): string {
+  let end = Math.min(value.length, maxChars);
+  if (end > 0 && /[\uD800-\uDBFF]/.test(value[end - 1])) end--;
+  return value.slice(0, end);
+}
+
+function limitStrings(value: unknown, maxChars: number): unknown {
+  if (typeof value === "string") return safePrefix(value, maxChars);
+  if (Array.isArray(value)) return value.map((item) => limitStrings(item, maxChars));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, limitStrings(item, maxChars)]));
+  return value;
 }
 
 function parseInteger(value: unknown, defaultValue: number, name: string, min: number, max: number): number {
@@ -380,7 +570,7 @@ function providerScope(provider: FetchProviderName, config?: any): string {
     firecrawl: config?.apiKeys?.firecrawl,
   };
   const key = keyMap[provider];
-  return key ? `key:${String(key).slice(0, 8)}` : "default";
+  return key ? `key:${createHash("sha256").update(String(key)).digest("hex")}` : "default";
 }
 
 function assertProviderUnchanged(tool: string, startup: string, runtime: string) {
@@ -449,7 +639,6 @@ function fetchDetails(value: any) {
       format: r.format,
       cached: r.cached,
       refreshed: r.refreshed,
-      cacheKey: r.cacheKey,
       range: r.range,
       error: r.error,
     })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-kit",
-  "version": "0.2.2",
+  "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": "^25.9.3",
-    "tsx": "^4.22.4",
-    "typebox": "^1.2.10",
-    "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"

package/src/config.ts

@@ -24,7 +24,12 @@ type PartialConfig = Partial<Omit<WebKitConfig, "apiKeys" | "markdownNew">> & {
   markdownNew?: Partial<WebKitConfig["markdownNew"]>;
 };
 
-export function resolveConfig(flags: { providerSearch?: unknown; providerFetch?: unknown } = {}, cwd = process.cwd(), env = process.env): WebKitConfig {
+export function resolveConfig(
+  flags: { providerSearch?: unknown; providerFetch?: unknown } = {},
+  cwd = process.cwd(),
+  env = process.env,
+  options: { includeProject?: boolean } = {},
+): WebKitConfig {
   let cfg = DEFAULT_CONFIG;
   cfg = merge(cfg, {
     provider_search: env.PI_WEB_KIT_PROVIDER_SEARCH as SearchProviderName | undefined,
@@ -38,9 +43,11 @@ export function resolveConfig(flags: { providerSearch?: unknown; providerFetch?:
     },
   });
   const home = env.HOME ?? homedir();
-  for (const path of [join(home, ".pi/agent/pi-web-kit.json"), join(cwd, ".pi-web-kit.json")]) {
-    const fileConfig = readConfigFile(path);
-    if (fileConfig) cfg = merge(cfg, fileConfig);
+  const globalConfig = readConfigFile(join(home, ".pi/agent/pi-web-kit.json"));
+  if (globalConfig) cfg = merge(cfg, globalConfig);
+  if (options.includeProject !== false) {
+    const projectConfig = readConfigFile(join(cwd, ".pi-web-kit.json"));
+    if (projectConfig) cfg = merge(cfg, projectConfig);
   }
   cfg = merge(cfg, {
     provider_search: flags.providerSearch as SearchProviderName | undefined,

package/src/providers/fallback.ts

@@ -69,8 +69,12 @@ export function mapFetchResults(requested: string[], fetched: WebFetchResult): M
     const index = remaining.findIndex((item) => urlsMatch(item.url, url));
     if (index >= 0) out.set(url, remaining.splice(index, 1)[0]);
   }
-  // providers may not echo back the canonical URL; fall back to positional match
-  requested.forEach((url, index) => { if (!out.has(url) && fetched.results?.[index]) out.set(url, fetched.results[index]); });
+  // Providers may not echo the requested URL. Assign each unmatched result at
+  // most once, after exact canonical matches have consumed their results.
+  for (const url of requested) {
+    if (out.has(url) || remaining.length === 0) continue;
+    out.set(url, remaining.shift()!);
+  }
   return out;
 }