@mario-gc/pi-context7 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mario
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @mario-gc/pi-context7
+
+Context7 integration for pi coding agent. Fetch up-to-date library documentation and code examples directly from Context7.
+
+## Installation
+
+**Global install (npm):**
+```bash
+pi install npm:@mario-gc/pi-context7
+```
+
+**Global install (GitHub):**
+```bash
+pi install git:github.com/mario-gc/pi-context7
+```
+
+**Project install (adds to `.pi/settings.json`):**
+```bash
+pi install -l npm:@mario-gc/pi-context7
+pi install -l git:github.com/mario-gc/pi-context7
+```
+
+**Local development:**
+```bash
+pi -e ./extensions/context7.ts
+```
+
+## Usage
+
+This package provides two tools for the agent:
+
+1. **context7_search_library** — Search Context7 for libraries by name. Resolves a library name to a Context7 library ID.
+2. **context7_get_context** — Get up-to-date documentation context and code examples for a library from Context7.
+
+Workflow: search for a library → get documentation context for code examples and API reference.
+
+### Skill
+
+A companion skill (`context7`) is also available. Use `/skill:context7` to load it.
+
+## API Key Setup
+
+Context7 uses an API key for authenticated access (higher rate limits). Unauthenticated requests work but have stricter rate limits.
+
+**Environment variable:**
+```bash
+export CONTEXT7_API_KEY=ctx7sk-your-api-key-here
+```
+
+**Auth file** (`~/.pi/agent/auth.json`):
+```json
+{
+  "context7": {
+    "apiKey": "ctx7sk-your-api-key-here"
+  }
+}
+```
+
+Generate an API key at [https://context7.com/dashboard](https://context7.com/dashboard).
+
+## Cache
+
+Responses are cached locally for performance and offline resilience.
+
+**Cache location:** `~/.pi/agent/cache/context7/`
+
+- Search results cached for 7 days
+- Documentation context cached for 3 days
+
+**Offline mode:** Set `PI_OFFLINE=1` to use cached results only:
+```bash
+PI_OFFLINE=1 pi -e ./extensions/context7.ts
+```
+
+**Cache TTL override:** Set `CONTEXT7_CACHE_TTL` in minutes:
+```bash
+CONTEXT7_CACHE_TTL=60 pi -e ./extensions/context7.ts
+```
+
+## License
+
+MIT

package/extensions/cache.ts

@@ -0,0 +1,597 @@
+/**
+ * Context7 Cache Layer
+ *
+ * A BM25-backed semantic cache for Context7 API responses. Stores search results
+ * and documentation context on disk, retrieves them by exact MD5 match or BM25
+ * semantic similarity. Parallel-safe with zero runtime dependencies.
+ *
+ * On-disk structure:
+ *   ~/.pi/agent/cache/context7/
+ *   ├── libraries/            # Cached search response files (hash.json)
+ *   ├── libraries.json        # Manifest for search cache
+ *   ├── contexts/             # Cached context response files (hash.json)
+ *   └── contexts.json         # Manifest for context cache
+ *
+ * @module extensions/cache
+ */
+
+import { mkdir, readFile, writeFile, rename, readdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CACHE_ROOT = join(homedir(), ".pi", "agent", "cache", "context7");
+
+/** Subdirectory name for each endpoint. */
+const DIR_NAMES: Record<string, string> = {
+  search: "libraries",
+  context: "contexts",
+};
+
+/** Default TTLs in seconds. */
+const DEFAULT_TTL: Record<string, number> = {
+  search: 604_800,  // 7 days
+  context: 259_200, // 3 days
+};
+
+const MAX_CACHE_SIZE = 52_428_800; // 50 MB in bytes
+
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+const BM25_CONSTANT_IDF = 1.5;
+
+const BM25_THRESHOLD_ONLINE = 0.7;
+const BM25_THRESHOLD_OFFLINE = 0.5;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CacheEntry {
+  response: unknown;
+  cachedAt: number; // Unix timestamp ms
+  ttl: number;      // Seconds
+}
+
+export interface CacheResult {
+  data: unknown;
+  source: "exact" | "bm25" | "stale" | null;
+  entry?: CacheEntry;
+}
+
+interface ManifestEntry {
+  scope: Record<string, string>;
+  query: string;
+  hash: string;
+  cachedAt: number;
+  ttl: number;
+  size: number;
+}
+
+interface Manifest {
+  entries: ManifestEntry[];
+}
+
+export interface CacheModule {
+  init(): Promise<void>;
+  get(
+    endpoint: "search" | "context",
+    scope: Record<string, string>,
+    params: Record<string, string | boolean | undefined>,
+  ): Promise<CacheResult>;
+  set(
+    endpoint: "search" | "context",
+    scope: Record<string, string>,
+    params: Record<string, string | boolean | undefined>,
+    data: unknown,
+  ): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+
+let initialized = false;
+const manifests: Record<string, Manifest> = {
+  search: { entries: [] },
+  context: { entries: [] },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Check whether the agent is in offline mode. */
+function isOffline(): boolean {
+  const v = process.env.PI_OFFLINE ?? process.env.CONTEXT7_OFFLINE;
+  return v === "true" || v === "1";
+}
+
+/** Return the effective TTL (seconds) for the given endpoint. */
+function getTTL(endpoint: "search" | "context"): number {
+  const env = process.env.CONTEXT7_CACHE_TTL;
+  if (env) {
+    const minutes = parseInt(env, 10);
+    if (!isNaN(minutes) && minutes > 0) return minutes * 60;
+  }
+  return DEFAULT_TTL[endpoint];
+}
+
+/**
+ * Compute an MD5 hash from canonical params.
+ *
+ * Sorts keys alphabetically, omits `undefined` values, JSON-stringifies,
+ * then returns the MD5 hex digest.
+ */
+function computeHash(params: Record<string, string | boolean | undefined>): string {
+  const canonical: Record<string, string | boolean> = {};
+  for (const key of Object.keys(params).sort()) {
+    if (params[key] !== undefined) {
+      canonical[key] = params[key] as string | boolean;
+    }
+  }
+  return createHash("md5").update(JSON.stringify(canonical)).digest("hex");
+}
+
+/**
+ * Extract the natural-language query text from params for BM25 matching.
+ *
+ * Looks for common keys (`query`, `q`) and returns the first non-empty string found.
+ */
+function extractQueryText(params: Record<string, string | boolean | undefined>): string {
+  for (const key of ["query", "q"]) {
+    const val = params[key];
+    if (typeof val === "string" && val.trim().length > 0) return val.trim();
+  }
+  return "";
+}
+
+/**
+ * Tokenize text for BM25 scoring.
+ *
+ * Lowercases, splits on non-alphanumeric characters, filters empty tokens.
+ */
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 1);
+}
+
+/**
+ * Compute BM25 score for a single query/document pair.
+ *
+ * Implements the simplified BM25 formula described in the spec.
+ */
+function bm25Score(queryTokens: string[], docTokens: string[], avgDocLen: number): number {
+  const docLen = docTokens.length;
+  const avgLen = avgDocLen > 0 ? avgDocLen : 1;
+
+  let score = 0;
+  for (const term of queryTokens) {
+    const freq = docTokens.filter((t) => t === term).length;
+    if (freq > 0) {
+      const tf =
+        (freq * (BM25_K1 + 1)) /
+        (freq + BM25_K1 * (1 - BM25_B + BM25_B * (docLen / avgLen)));
+      score += tf * BM25_CONSTANT_IDF;
+    }
+  }
+  return score;
+}
+
+/**
+ * Run BM25 against a list of manifest entries and return the best match.
+ *
+ * @returns The best matching entry, or null if none reach the threshold.
+ */
+function bm25Find(query: string, entries: ManifestEntry[], threshold: number): ManifestEntry | null {
+  const queryTokens = tokenize(query);
+  if (queryTokens.length === 0) return null;
+
+  const docTokenLists = entries.map((e) => tokenize(e.query));
+  const avgDocLen =
+    docTokenLists.reduce((sum, t) => sum + t.length, 0) / Math.max(entries.length, 1);
+
+  let bestScore = 0;
+  let bestEntry: ManifestEntry | null = null;
+
+  for (let i = 0; i < entries.length; i++) {
+    const score = bm25Score(queryTokens, docTokenLists[i], avgDocLen);
+    if (score > bestScore) {
+      bestScore = score;
+      bestEntry = entries[i];
+    }
+  }
+
+  return bestScore >= threshold ? bestEntry : null;
+}
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+function getEndpointDir(endpoint: "search" | "context"): string {
+  return join(CACHE_ROOT, DIR_NAMES[endpoint]);
+}
+
+function getManifestPath(endpoint: "search" | "context"): string {
+  return join(CACHE_ROOT, `${DIR_NAMES[endpoint]}.json`);
+}
+
+function getManifestTempPath(endpoint: "search" | "context"): string {
+  return join(CACHE_ROOT, `${DIR_NAMES[endpoint]}.json.tmp`);
+}
+
+function getEntryPath(endpoint: "search" | "context", hash: string): string {
+  return join(getEndpointDir(endpoint), `${hash}.json`);
+}
+
+function getEntryTempPath(endpoint: "search" | "context", hash: string): string {
+  return join(getEndpointDir(endpoint), `${hash}.json.tmp`);
+}
+
+// ---------------------------------------------------------------------------
+// Manifest persistence
+// ---------------------------------------------------------------------------
+
+async function writeManifest(endpoint: "search" | "context"): Promise<void> {
+  const tmpPath = getManifestTempPath(endpoint);
+  const finalPath = getManifestPath(endpoint);
+  await writeFile(tmpPath, JSON.stringify(manifests[endpoint]), "utf-8");
+  await rename(tmpPath, finalPath);
+}
+
+// ---------------------------------------------------------------------------
+// Task 4: Eviction
+// ---------------------------------------------------------------------------
+
+/**
+ * Check total cache size across both manifests and evict oldest entries
+ * if the total exceeds 50 MB.
+ */
+async function evictIfNeeded(): Promise<void> {
+  type TaggedEntry = { entry: ManifestEntry; endpoint: "search" | "context" };
+
+  let totalSize = 0;
+  const allEntries: TaggedEntry[] = [];
+
+  for (const endpoint of ["search", "context"] as const) {
+    for (const e of manifests[endpoint].entries) {
+      totalSize += e.size;
+      allEntries.push({ entry: e, endpoint });
+    }
+  }
+
+  if (totalSize <= MAX_CACHE_SIZE) return;
+
+  // Sort oldest-first
+  allEntries.sort((a, b) => a.entry.cachedAt - b.entry.cachedAt);
+
+  let currentSize = totalSize;
+  let evictedCount = 0;
+
+  for (const { entry, endpoint } of allEntries) {
+    if (currentSize <= MAX_CACHE_SIZE) break;
+
+    // Delete the cached response file
+    const filePath = getEntryPath(endpoint, entry.hash);
+    try {
+      await unlink(filePath);
+    } catch {
+      // File may already be gone — that's fine
+    }
+
+    // Remove from in-memory manifest
+    const idx = manifests[endpoint].entries.findIndex((e) => e.hash === entry.hash);
+    if (idx !== -1) {
+      manifests[endpoint].entries.splice(idx, 1);
+    }
+
+    currentSize -= entry.size;
+    evictedCount++;
+  }
+
+  // Persist updated manifests atomically
+  for (const endpoint of ["search", "context"] as const) {
+    await writeManifest(endpoint);
+  }
+
+  const freedMB = ((totalSize - currentSize) / 1024 / 1024).toFixed(1);
+  console.log(`[cache] Evicted ${evictedCount} entries (${freedMB} MB freed)`);
+}
+
+// ---------------------------------------------------------------------------
+// Task 1: Init, Manifest Loading, Exact Match
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize the cache layer.
+ *
+ * 1. Create directories (`libraries/`, `contexts/`)
+ * 2. Load manifests into memory (or initialize as empty)
+ * 3. Clean stale `.tmp` files
+ * 4. Run eviction check
+ */
+async function init(): Promise<void> {
+  if (initialized) return;
+
+  // 1. Ensure directories exist
+  await mkdir(join(CACHE_ROOT, "libraries"), { recursive: true });
+  await mkdir(join(CACHE_ROOT, "contexts"), { recursive: true });
+
+  // 2. Load manifests
+  for (const endpoint of ["search", "context"] as const) {
+    const mPath = getManifestPath(endpoint);
+    try {
+      const content = await readFile(mPath, "utf-8");
+      const parsed: Manifest = JSON.parse(content);
+      manifests[endpoint] = {
+        entries: Array.isArray(parsed.entries) ? parsed.entries : [],
+      };
+    } catch {
+      manifests[endpoint] = { entries: [] };
+    }
+  }
+
+  // 3. Clean stale .tmp files from both directories and root
+  for (const endpoint of ["search", "context"] as const) {
+    const dir = getEndpointDir(endpoint);
+    try {
+      const files = await readdir(dir);
+      for (const file of files) {
+        if (file.endsWith(".tmp")) {
+          try {
+            await unlink(join(dir, file));
+          } catch {
+            // Race with another init() — ignore
+          }
+        }
+      }
+    } catch {
+      // Directory may not exist yet
+    }
+  }
+
+  // Also clean manifest .tmp files from the root cache dir
+  try {
+    const rootFiles = await readdir(CACHE_ROOT);
+    for (const file of rootFiles) {
+      if (file.endsWith(".tmp")) {
+        try {
+          await unlink(join(CACHE_ROOT, file));
+        } catch {
+          // ignore
+        }
+      }
+    }
+  } catch {
+    // Root may not exist
+  }
+
+  // 4. Eviction check
+  await evictIfNeeded();
+
+  initialized = true;
+}
+
+/**
+ * Read a cached entry from disk by hash.
+ */
+async function readCacheEntry(endpoint: "search" | "context", hash: string): Promise<CacheEntry | null> {
+  const filePath = getEntryPath(endpoint, hash);
+  try {
+    const content = await readFile(filePath, "utf-8");
+    return JSON.parse(content) as CacheEntry;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Task 2: BM25 Semantic Lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempt a BM25 semantic lookup against manifest entries filtered by scope.
+ *
+ * - **search** endpoint: filters by `scope.libraryName`
+ * - **context** endpoint: filters by `scope.libraryId`
+ *
+ * @param excludeHash - If provided, this entry is excluded from candidates.
+ *   Used when the exact match was found (but stale) to avoid BM25 returning
+ *   the same entry we already know is stale.
+ */
+async function tryBm25(
+  endpoint: "search" | "context",
+  scope: Record<string, string>,
+  params: Record<string, string | boolean | undefined>,
+  threshold: number,
+  excludeHash?: string,
+): Promise<CacheResult | null> {
+  const query = extractQueryText(params);
+  if (!query) return null;
+
+  // Filter manifest entries by scope
+  let candidates = manifests[endpoint].entries;
+
+  if (endpoint === "search") {
+    // Only match entries for the same library
+    if (scope.libraryName) {
+      candidates = candidates.filter((e) => e.scope.libraryName === scope.libraryName);
+    }
+  } else {
+    // Only match entries for the same library/document
+    if (scope.libraryId) {
+      candidates = candidates.filter((e) => e.scope.libraryId === scope.libraryId);
+    }
+  }
+
+  // Exclude the stale-exact-match entry so BM25 finds a *different* cached query
+  if (excludeHash) {
+    candidates = candidates.filter((e) => e.hash !== excludeHash);
+  }
+
+  if (candidates.length === 0) return null;
+
+  const match = bm25Find(query, candidates, threshold);
+  if (!match) return null;
+
+  // Read the matched entry's cached data from disk
+  const entry = await readCacheEntry(endpoint, match.hash);
+  if (!entry) return null;
+
+  return { data: entry.response, source: "bm25" };
+}
+
+// ---------------------------------------------------------------------------
+// Task 5: Offline Mode
+// ---------------------------------------------------------------------------
+
+/**
+ * Retrieve a cached response.
+ *
+ * Flow:
+ * 1. Compute canonical hash → try exact match
+ * 2. If exact fresh → return `source:"exact"`
+ * 3. If exact stale (online) → run BM25; fall back to stale if BM25 fails
+ * 4. If exact stale (offline) → return `source:"stale"` directly
+ * 5. If exact not found → run BM25 with appropriate threshold
+ * 6. If nothing matches → return `source:null`
+ */
+async function get(
+  endpoint: "search" | "context",
+  scope: Record<string, string>,
+  params: Record<string, string | boolean | undefined>,
+): Promise<CacheResult> {
+  await init();
+
+  const hash = computeHash(params);
+  const offline = isOffline();
+  const threshold = offline ? BM25_THRESHOLD_OFFLINE : BM25_THRESHOLD_ONLINE;
+
+  // 1. Try exact match
+  const entry = await readCacheEntry(endpoint, hash);
+
+  if (entry) {
+    const isFresh = entry.cachedAt + entry.ttl * 1000 > Date.now();
+
+    if (isFresh) {
+      // Fresh exact match → return immediately
+      return { data: entry.response, source: "exact" };
+    }
+
+    // Stale exact match
+    if (offline) {
+      // Offline: return stale data directly — caller prepends [cached, may be outdated]
+      return { data: entry.response, source: "stale" };
+    }
+
+    // Online: try BM25 first (maybe a similar query was cached more recently)
+    // Pass the current hash so BM25 skips the same stale entry.
+    const bm25Result = await tryBm25(endpoint, scope, params, threshold, hash);
+    if (bm25Result) {
+      return bm25Result;
+    }
+
+    // No BM25 match either — fall back to the stale exact match
+    return { data: entry.response, source: "stale" };
+  }
+
+  // 2. No exact match → try BM25 semantic lookup
+  const bm25Result = await tryBm25(endpoint, scope, params, threshold);
+  if (bm25Result) {
+    return bm25Result;
+  }
+
+  // 3. Nothing cached
+  return { data: null, source: null };
+}
+
+// ---------------------------------------------------------------------------
+// Task 3: Atomic Writes
+// ---------------------------------------------------------------------------
+
+/**
+ * Store a response in the cache atomically.
+ *
+ * 1. Compute hash from canonical params
+ * 2. Write `{ response, cachedAt, ttl }` to `<hash>.json.tmp`
+ * 3. `rename()` → `<hash>.json` (atomic on same filesystem)
+ * 4. Update in-memory manifest with size tracking
+ * 5. Write manifest to `<endpoint>.json.tmp` → `rename()` to `<endpoint>.json`
+ */
+async function set(
+  endpoint: "search" | "context",
+  scope: Record<string, string>,
+  params: Record<string, string | boolean | undefined>,
+  data: unknown,
+): Promise<void> {
+  await init();
+
+  const hash = computeHash(params);
+  const ttl = getTTL(endpoint);
+  const now = Date.now();
+
+  // Build the cache entry
+  const entry: CacheEntry = {
+    response: data,
+    cachedAt: now,
+    ttl,
+  };
+
+  // 1. Write entry file atomically
+  const tmpPath = getEntryTempPath(endpoint, hash);
+  const finalPath = getEntryPath(endpoint, hash);
+  await writeFile(tmpPath, JSON.stringify(entry), "utf-8");
+  await rename(tmpPath, finalPath);
+
+  // 2. Compute response size (in bytes) for eviction accounting
+  const size = Buffer.byteLength(JSON.stringify(data));
+  const query = extractQueryText(params);
+
+  // 3. Update in-memory manifest
+  const existingIdx = manifests[endpoint].entries.findIndex((e) => e.hash === hash);
+  const manifestEntry: ManifestEntry = {
+    scope: { ...scope },
+    query,
+    hash,
+    cachedAt: now,
+    ttl,
+    size,
+  };
+
+  if (existingIdx !== -1) {
+    // Update existing entry
+    manifests[endpoint].entries[existingIdx] = manifestEntry;
+  } else {
+    // Append new entry
+    manifests[endpoint].entries.push(manifestEntry);
+  }
+
+  // 4. Write manifest atomically
+  await writeManifest(endpoint);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new cache module instance.
+ *
+ * Usage:
+ * ```typescript
+ * import { createCache } from "./extensions/cache";
+ * const cache = createCache();
+ * await cache.init();
+ * const result = await cache.get("search", { libraryName: "react" }, { query: "useState" });
+ * ```
+ */
+export function createCache(): CacheModule {
+  return { init, get, set };
+}

package/extensions/context7.ts

@@ -0,0 +1,562 @@
+/**
+ * Context7 Extension for pi coding agent.
+ *
+ * Registers two tools backed by the cache layer from cache.ts:
+ * 1. context7_search_library — Search Context7 for libraries by name
+ * 2. context7_get_context — Get documentation context and code examples
+ *
+ * @module extensions/context7
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createCache, type CacheModule } from "./cache.js";
+
+export default function (pi: ExtensionAPI) {
+  let cache: CacheModule;
+  let apiKey: string | undefined;
+
+  // -----------------------------------------------------------------------
+  // API Key Resolution
+  // -----------------------------------------------------------------------
+
+  function resolveApiKey(): string | undefined {
+    if (process.env.CONTEXT7_API_KEY) return process.env.CONTEXT7_API_KEY;
+
+    try {
+      const authPath = join(homedir(), ".pi", "agent", "auth.json");
+      const auth = JSON.parse(readFileSync(authPath, "utf8"));
+      return auth?.context7?.apiKey;
+    } catch {
+      /* not found, unauthenticated */
+    }
+
+    return undefined;
+  }
+
+  // -----------------------------------------------------------------------
+  // Session Init
+  // -----------------------------------------------------------------------
+
+  pi.on("session_start", async (_event, ctx) => {
+    cache = await createCache();
+    apiKey = resolveApiKey();
+
+    if (!apiKey) {
+      ctx.ui.notify(
+        "Context7: no API key set. Rate limits apply. " +
+          "Set CONTEXT7_API_KEY for higher limits.",
+        "info",
+      );
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // Signal helper — race caller signal with timeout
+  // -----------------------------------------------------------------------
+
+  function createCombinedSignal(timeoutMs: number, signal?: AbortSignal): AbortSignal {
+    if (!signal) return AbortSignal.timeout(timeoutMs);
+
+    // AbortSignal.any is available in Node 20+
+    if (typeof AbortSignal.any === "function") {
+      return AbortSignal.any([AbortSignal.timeout(timeoutMs), signal]);
+    }
+
+    // Fallback: create a controller aborted by either signal
+    const controller = new AbortController();
+    const onAbort = () => {
+      try {
+        controller.abort();
+      } catch {
+        /* already aborted */
+      }
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    AbortSignal.timeout(timeoutMs).addEventListener("abort", onAbort, { once: true });
+    return controller.signal;
+  }
+
+  // -----------------------------------------------------------------------
+  // HTTP Client (Context7-specific)
+  // -----------------------------------------------------------------------
+
+  async function context7Fetch<T>(
+    endpoint: string,
+    params: Record<string, string | boolean | undefined>,
+    apiKey?: string,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    const url = new URL(`https://context7.com/api/v2/${endpoint}`);
+
+    for (const [key, value] of Object.entries(params)) {
+      if (value === undefined) continue;
+      url.searchParams.set(key, String(value));
+    }
+
+    const headers: Record<string, string> = {};
+    if (apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+
+    const maxRetries = 3;
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const combinedSignal = createCombinedSignal(10_000, signal);
+        const response = await fetch(url.toString(), { headers, signal: combinedSignal });
+
+        if (response.ok) {
+          return (await response.json()) as T;
+        }
+
+        // Try to parse structured error body
+        let apiMessage: string | undefined;
+        try {
+          const errorBody = await response.json();
+          if (errorBody?.message) apiMessage = errorBody.message;
+        } catch {
+          /* ignore parse errors */
+        }
+
+        // 401 — Invalid API key
+        if (response.status === 401) {
+          throw new Error(
+            "Context7 API error: Invalid API key. Generate one at " +
+              "https://context7.com/dashboard and set CONTEXT7_API_KEY.",
+          );
+        }
+
+        // 403 — Access denied
+        if (response.status === 403) {
+          throw new Error(
+            "Context7 API error: Access denied. Your plan may not include this library.",
+          );
+        }
+
+        // 404 — Not found
+        if (response.status === 404) {
+          throw new Error(
+            "Context7 API error: Library not found. Check the library ID.",
+          );
+        }
+
+        // 429 — Rate limited
+        if (response.status === 429) {
+          if (attempt < maxRetries) {
+            const retryAfter = response.headers.get("Retry-After");
+            const delayMs = retryAfter
+              ? parseInt(retryAfter, 10) * 1000
+              : Math.pow(2, attempt) * 1000;
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+            continue;
+          }
+          throw new Error(
+            "Context7 API error: Rate limit exceeded. Wait and retry, " +
+              "or set CONTEXT7_API_KEY for higher limits.",
+          );
+        }
+
+        // 5xx — Server error
+        if (response.status >= 500) {
+          throw new Error(
+            `Context7 API error: Server error (${response.status}). Try again later.`,
+          );
+        }
+
+        // Other 4xx
+        throw new Error(
+          apiMessage
+            ? `Context7 API error: ${apiMessage}`
+            : `Context7 API error: HTTP ${response.status}`,
+        );
+      } catch (err) {
+        const isContext7Error =
+          err instanceof Error && err.message.startsWith("Context7 API error");
+
+        if (isContext7Error) {
+          // These are already formatted — throw immediately
+          throw err;
+        }
+
+        // Network / timeout / other transient errors — retry with backoff
+        lastError = err instanceof Error ? err : new Error(String(err));
+
+        if (attempt < maxRetries) {
+          const delayMs = Math.pow(2, attempt) * 1000;
+          await new Promise((resolve) => setTimeout(resolve, delayMs));
+          continue;
+        }
+
+        throw new Error(
+          `Context7 API error: Network error after ${maxRetries + 1} attempts. ${lastError.message}`,
+        );
+      }
+    }
+
+    // Should not reach here, but satisfy TypeScript
+    throw lastError ?? new Error("Context7 API error: Request failed after retries.");
+  }
+
+  // -----------------------------------------------------------------------
+  // Tool: context7_search_library
+  // -----------------------------------------------------------------------
+
+  pi.registerTool({
+    name: "context7_search_library",
+    label: "Context7 Search Library",
+    description:
+      "Search Context7 for libraries by name. Returns matching libraries with IDs, descriptions, " +
+      "trust scores, and available versions. Use this first to resolve a library name to a " +
+      "Context7 library ID before calling context7_get_context.",
+    promptSnippet: "Search for libraries on Context7 by name (e.g., 'react', 'nextjs')",
+    parameters: Type.Object({
+      libraryName: Type.String({
+        description:
+          "Library name to search for (e.g., 'react', 'nextjs', 'express', 'prisma')",
+      }),
+      query: Type.String({
+        description:
+          "The user's full question or task — used for intelligent relevance ranking. " +
+          "Be specific. Good: 'How to set up JWT auth in Express middleware', Bad: 'auth'",
+      }),
+      fast: Type.Optional(
+        Type.Boolean({
+          description:
+            "When true, skip LLM reranking for faster but less accurate results",
+          default: false,
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      try {
+        const currentApiKey = apiKey;
+
+        // Build params for fetch + cache
+        const fetchParams: Record<string, string | boolean | undefined> = {
+          libraryName: params.libraryName,
+          query: params.query,
+        };
+        if (params.fast) fetchParams.fast = true;
+
+        // Try cache first
+        const cached = await cache.get(
+          "search",
+          { libraryName: params.libraryName },
+          fetchParams,
+        );
+
+        let results: unknown[];
+        let cacheNote = "";
+
+        if (cached.source !== null) {
+          // Cache hit
+          results = ((cached.data as { results?: unknown[] })?.results ?? []) as unknown[];
+          if (cached.source === "exact") {
+            cacheNote = "\n[cache hit]";
+          } else if (cached.source === "bm25") {
+            cacheNote = "\n[semantic cache match]";
+          } else if (cached.source === "stale") {
+            cacheNote = "\n[cached, may be outdated]";
+          }
+        } else {
+          // Cache miss — fetch from API
+          const raw = await context7Fetch<{ results: unknown[] }>(
+            "libs/search",
+            fetchParams,
+            currentApiKey,
+            signal,
+          );
+          results = raw.results ?? [];
+          // Store in cache (fire-and-forget)
+          cache.set("search", { libraryName: params.libraryName }, fetchParams, raw).catch(() => {});
+          cacheNote = "\n[fetched from API]";
+        }
+
+        if (results.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No libraries found for '${params.libraryName}'. Try a different name or be more specific.`,
+              },
+            ],
+            details: { results: [] },
+          };
+        }
+
+        // Format output
+        const lines: string[] = [
+          `Found ${results.length} libraries for "${params.libraryName}":`,
+        ];
+
+        for (let i = 0; i < results.length; i++) {
+          const lib = results[i] as Record<string, unknown>;
+          const idx = i + 1;
+          const id = lib.id ?? "";
+          const title = lib.title ?? lib.name ?? "Unknown";
+          const description = lib.description ?? "";
+          const versions = Array.isArray(lib.versions)
+            ? (lib.versions as string[]).join(", ")
+            : "";
+          const trust = lib.trustScore ?? lib.trust_score ?? "?";
+          const bench = lib.benchmarkScore ?? lib.benchmark_score ?? "?";
+          const stars = lib.stars ?? lib.githubStars ?? lib.github_stars ?? "?";
+
+          lines.push("");
+          lines.push(`${idx}. ${title} — ${id}`);
+          lines.push(`   ${description}`);
+          if (versions) lines.push(`   Versions: ${versions}`);
+          lines.push(`   Trust: ${trust}/10 · Benchmark: ${bench}/100 · ⭐ ${stars}`);
+        }
+
+        lines.push("");
+        lines.push(
+          "Use the library ID (e.g., " +
+            (results[0] as Record<string, unknown>)?.id +
+            ") with context7_get_context.",
+        );
+        if (cacheNote) lines.push(cacheNote);
+
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+          details: { results },
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: message }],
+          details: { error: message },
+        };
+      }
+    },
+  });
+
+  // -----------------------------------------------------------------------
+  // Tool: context7_get_context
+  // -----------------------------------------------------------------------
+
+  pi.registerTool({
+    name: "context7_get_context",
+    label: "Context7 Get Context",
+    description:
+      "Get up-to-date documentation context and code examples for a library from Context7. " +
+      "Requires a libraryId from context7_search_library (format: /owner/repo or /owner/repo@version). " +
+      "Always prefer Context7 over training data for library-specific questions.",
+    promptSnippet: "Retrieve documentation and code examples for a Context7 library ID",
+    promptGuidelines: [
+      "Use context7_get_context for library documentation instead of relying on training data. Training data may be outdated.",
+      "When context7_get_context returns insufficient results, retry with researchMode: true for a deeper search.",
+      "Always run context7_search_library first to resolve library names to Context7 IDs before calling context7_get_context.",
+    ],
+    parameters: Type.Object({
+      libraryId: Type.String({
+        description:
+          "Context7 library ID in format /owner/repo or /owner/repo@version " +
+          "(e.g., '/facebook/react', '/vercel/next.js@v15.1.8')",
+      }),
+      query: Type.String({
+        description:
+          "The specific question or task. Be specific and include relevant details. " +
+          "Good: 'How to set up JWT authentication in Express middleware', Bad: 'auth'",
+      }),
+      type: Type.Optional(
+        StringEnum(["json", "txt"] as const, {
+          description:
+            "Response format. 'json' returns structured snippets, 'txt' returns raw text.",
+          default: "json",
+        }),
+      ),
+      researchMode: Type.Optional(
+        Type.Boolean({
+          description:
+            "When true, use deeper agentic research (sandboxed agents, live web search). " +
+            "Slower but higher quality. Use as retry if default results are insufficient.",
+          default: false,
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      try {
+        // 1. Validate libraryId format: /owner/repo or /owner/repo@version or /owner/repo/version
+        const libIdRegex = /^\/[^/]+\/[^/]+([/@][^/]+)?$/;
+        if (!libIdRegex.test(params.libraryId)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Invalid libraryId format. Expected /owner/repo or /owner/repo@version",
+              },
+            ],
+            details: { error: "Invalid libraryId format" },
+          };
+        }
+
+        const currentApiKey = apiKey;
+        const responseType = params.type ?? "json";
+
+        const fetchParams: Record<string, string | boolean | undefined> = {
+          libraryId: params.libraryId,
+          query: params.query,
+          type: responseType,
+        };
+        if (params.researchMode) fetchParams.researchMode = true;
+
+        // Try cache
+        const cached = await cache.get(
+          "context",
+          { libraryId: params.libraryId },
+          fetchParams,
+        );
+
+        let data: Record<string, unknown>;
+        let cacheNote = "";
+
+        if (cached.source !== null) {
+          // Cache hit
+          data = cached.data as Record<string, unknown>;
+          if (cached.source === "exact") {
+            cacheNote = "\n[cache hit]";
+          } else if (cached.source === "bm25") {
+            cacheNote = "\n[semantic cache match]";
+          } else if (cached.source === "stale") {
+            cacheNote = "\n[cached, may be outdated]";
+          }
+        } else {
+          // Cache miss — fetch from API
+          data = await context7Fetch<Record<string, unknown>>(
+            "context",
+            fetchParams,
+            currentApiKey,
+            signal,
+          );
+          // Store in cache (fire-and-forget)
+          cache
+            .set("context", { libraryId: params.libraryId }, fetchParams, data)
+            .catch(() => {});
+          cacheNote = "\n[fetched from API]";
+        }
+
+        // Format output
+        const outputLines: string[] = [];
+        outputLines.push(`## Context7 Documentation for ${params.libraryId}`);
+        outputLines.push("");
+
+        if (responseType === "txt") {
+          // Raw text mode
+          const textContent =
+            (data?.text as string) ??
+            (data?.content as string) ??
+            JSON.stringify(data, null, 2);
+          outputLines.push(String(textContent));
+        } else {
+          // Structured JSON mode
+          const codeSnippets = data?.codeSnippets as
+            | Array<Record<string, unknown>>
+            | undefined;
+          if (codeSnippets && codeSnippets.length > 0) {
+            outputLines.push("### Code Snippets");
+            outputLines.push("");
+
+            for (const snippet of codeSnippets) {
+              // Use codeTitle/codeDescription from the API, with fallbacks
+              const snippetTitle = (snippet.codeTitle ?? snippet.title ?? "Code Example") as string;
+              const snippetDesc = snippet.codeDescription as string | undefined;
+
+              // Use codeLanguage from the API, with fallback
+              const snippetLang = (snippet.codeLanguage ?? snippet.language ?? snippet.lang ?? "typescript") as string;
+
+              // codeList is an array of { language, code } from the API
+              const codeList = (snippet.codeList ?? []) as Array<Record<string, unknown>>;
+
+              // Source URL from the API (codeId) with fallbacks
+              const sourceUrl = (snippet.codeId ?? snippet.source ?? snippet.pageTitle) as string | undefined;
+
+              if (codeList.length > 0) {
+                // Each codeList item gets its own code block
+                outputLines.push(`**${snippetTitle}**`);
+                if (snippetDesc) outputLines.push(`> ${snippetDesc}`);
+                outputLines.push("");
+
+                for (const item of codeList) {
+                  const itemLang = (item.language ?? snippetLang) as string;
+                  const itemCode = (item.code ?? "") as string;
+                  if (itemCode) {
+                    outputLines.push("```" + itemLang);
+                    outputLines.push(String(itemCode).trimEnd());
+                    outputLines.push("```");
+                  }
+                }
+
+                if (sourceUrl) outputLines.push(`Source: ${sourceUrl}`);
+                outputLines.push("");
+              } else {
+                // Fallback: try top-level code property (alternate format)
+                const legacyCode = (snippet.code ?? snippet.content ?? "") as string;
+                if (legacyCode) {
+                  outputLines.push(`**${snippetTitle}** (${snippetLang})`);
+                  if (snippetDesc) outputLines.push(`> ${snippetDesc}`);
+                  outputLines.push("```" + snippetLang);
+                  outputLines.push(String(legacyCode).trimEnd());
+                  outputLines.push("```");
+                  if (sourceUrl) outputLines.push(`Source: ${sourceUrl}`);
+                  outputLines.push("");
+                }
+              }
+            }
+          }
+
+          // Info / Documentation snippets
+          const infoSnippets = data?.infoSnippets as
+            | Array<Record<string, unknown>>
+            | undefined;
+          if (infoSnippets && infoSnippets.length > 0) {
+            outputLines.push("### Documentation");
+            outputLines.push("");
+
+            for (const snippet of infoSnippets) {
+              const title = snippet.title ?? "Info";
+              const snippetText =
+                (snippet.content as string) ??
+                (snippet.text as string) ??
+                (snippet.description as string) ??
+                "";
+              outputLines.push(`**${title}** — ${snippetText}`);
+              outputLines.push("");
+            }
+          }
+
+          // Research mode note
+          if (params.researchMode) {
+            outputLines.push("[Research mode — deeper analysis]");
+            outputLines.push("");
+          }
+        }
+
+        if (cacheNote) outputLines.push(cacheNote);
+
+        const formatted = outputLines.join("\n").trim();
+
+        return {
+          content: [{ type: "text", text: formatted || "No context data returned." }],
+          details: {
+            codeSnippets: (data?.codeSnippets as unknown) ?? [],
+            infoSnippets: (data?.infoSnippets as unknown) ?? [],
+            rules: (data?.rules as unknown) ?? [],
+          },
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: message }],
+          details: { error: message },
+        };
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mario-gc/pi-context7",
+  "version": "0.1.1",
+  "description": "Context7 integration for pi coding agent — fetch up-to-date library documentation and code examples",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "context7",
+    "documentation",
+    "api-reference"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/context7.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "files": [
+    "extensions/",
+    "skills/",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@mariozechner/pi-ai": "^0.73.0",
+    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "@types/node": "^25.6.0",
+    "typebox": "^1.1.37",
+    "typescript": "^6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mario-gc/pi-context7.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mario-gc/pi-context7/issues"
+  },
+  "homepage": "https://github.com/mario-gc/pi-context7#readme"
+}

package/skills/context7/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: context7
+description: >-
+  Fetches up-to-date documentation, API references, and code examples for any
+  library, framework, or tool via Context7. Use this skill when the user asks
+  about library setup, configuration, API syntax, version-specific behavior, or
+  needs code examples involving specific libraries (React, Next.js, Prisma,
+  Express, Tailwind, Supabase, etc.). Always prefer Context7 over training data
+  for library-specific questions — training data may be outdated. Do not use for
+  general programming questions, pure language syntax, or questions answerable
+  without library documentation.
+---
+
+# Context7 Documentation Lookup
+
+Retrieve current, version-specific documentation and code examples using Context7.
+
+## Workflow
+
+### Step 1: Resolve the Library
+
+Call `context7_search_library` with:
+
+- `libraryName`: The library extracted from the user's question (e.g., "react", "nextjs", "prisma")
+- `query`: The user's full question or task description — improves ranking
+- `fast`: Set to `true` only for latency-sensitive cases (trades accuracy)
+
+### Step 2: Select the Best Match
+
+From the results, choose based on:
+- Exact or closest name match to what the user asked for
+- Higher benchmark scores (out of 100) indicate better documentation quality
+- Higher trust scores (out of 10) indicate more authoritative sources
+- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs from the `versions` list
+
+### Step 3: Fetch Documentation
+
+Call `context7_get_context` with:
+
+- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)
+- `query`: The user's specific question — be descriptive
+- `type`: Use "json" for structured snippets (default), "txt" for plain text
+- `researchMode`: Only use this as a **retry** if the initial results are insufficient
+
+### Step 4: Use the Documentation
+
+Incorporate the fetched documentation into your response:
+- Answer the user's question using current, accurate information
+- Include relevant code examples from the docs
+- Cite the library version when relevant
+- Reference the source page/breadcrumb when helpful (from `pageTitle` or `breadcrumb`)
+
+## Query Quality
+
+| Good | Bad |
+|------|-----|
+| "How to set up JWT authentication in Express middleware" | "auth" |
+| "React useEffect cleanup function with async operations" | "hooks" |
+| "Prisma one-to-many relation with cascade delete" | "relations" |
+
+Pass the user's intent and relevant details — single-word queries return generic results.
+
+## Version Awareness
+
+When users mention specific versions:
+- Use version-specific library IDs from the search results: `/vercel/next.js@v15.1.8`
+- Both `@` and `/` separators work: `/vercel/next.js/v15.1.8`
+- If the exact version isn't available, pick the closest match
+
+## Retry Strategy
+
+If `context7_get_context` returns insufficient or irrelevant results:
+1. Retry with `researchMode: true` — this uses deeper agentic search
+2. If still insufficient, consider refining the query with more specific terms
+3. Do not silently fall back to training data without telling the user
+
+## Guidelines
+
+- Always run `context7_search_library` before `context7_get_context` — you need a valid library ID
+- Pass the user's full question as `query` for better relevance
+- Prefer official/primary packages over community forks when multiple matches exist
+- If you encounter rate limits or quota errors, inform the user they can set `CONTEXT7_API_KEY` for higher limits. API keys are available at https://context7.com/dashboard.
+- Results are cached locally for reuse — similar queries may hit the cache automatically