@fradser/pi-context 0.5.0 → 0.6.0

package/README.md

@@ -1,187 +1,54 @@
-# Code Context Pi Package
+# Context Pi Package
 
-**Version:** 0.4.1
+**Version:** 0.5.1
 
-Retrieve code context for any repo, library, or natural-language query via 5 methods: DeepWiki, Context7, Exa, git clone, and web search+fetch.
+`@fradser/pi-context` exposes one tool: `context_get`.
+
+It starts an independent Pi child process for repository, library, codebase, and technical-topic research. This isolates exploratory tool calls from the main session while returning a concise, evidence-based result.
 
 ## Installation
 
 ```bash
-pi install /path/to/pi-packages/packages/code-context
+pi install npm:@fradser/pi-context
+# or from this repository:
+pi install /path/to/pi-packages/packages/context
 ```
 
-Run `/skill:get-context <query…>` for the executable Pi workflow.
-
-## Runtime requirements
-
-| Method | Availability | Notes |
-|--------|--------------|-------|
-| DeepWiki | Always (native tool `context_deepwiki`) | No API key required |
-| Context7 | Always (native tool `context_context7`) | Optional `CONTEXT7_API_KEY` (Bearer) for per-key quota |
-| Exa | Native tool `context_exa` | Requires `EXA_API_KEY` env var |
-| Git clone | Always | Pi `bash` + `read` |
-| Web fetch | Always | `curl`/HTTP via `bash` |
-
-All three retrieval tools are registered by this package's extension (`extensions/context-tools.ts`) and call the public REST APIs directly — no MCP servers needed.
-
-## Overview
-
-Code Context accepts **arbitrary input** — a natural-language question, a repo slug, a library name, or several of these at once — and routes each target to the right method(s). It prefers intermediate summaries so the main conversation stays clean, returning only synthesized summaries.
-
-## Methods
-
-### 1. DeepWiki (AI-powered repo documentation)
-
-Best for: Public GitHub repositories requiring architecture overview, component explanations, or high-level understanding.
-
-**Tool:** `context_deepwiki` — `owner`/`repo` + `mode: structure | contents | ask`
-
-**Process:**
-1. `context_deepwiki` with `mode: "structure"` (e.g. owner=`facebook`, repo=`react`)
-2. `context_deepwiki` with `mode: "contents"` for full wiki text, or `mode: "ask"` + `question` for targeted Q&A
-
-**Strengths:** Zero setup, instant AI-summarized documentation.
-
-**Limitations:** Only works for public GitHub repos; coverage varies by popularity.
-
----
-
-### 2. Context7 (library documentation)
-
-Best for: Getting up-to-date API docs, usage examples, and version-specific documentation for npm/pip packages.
-
-**Tool:** `context_context7` — `query` + optional `topic`
-
-**Process:**
-1. `context_context7` with the library name (e.g. `"react"`, `"fastapi"`)
-2. Pass a `topic` (e.g. `"auth"`, `"ssr"`) for focused snippets; include the version in the query when given (`react@18`)
-
-**Strengths:** Always current docs, supports version pinning, covers thousands of libraries.
-
-**Limitations:** Requires the library to be indexed; less useful for internal packages.
-
----
-
-### 3. Exa Code Search (web-wide code examples)
-
-Best for: Finding real-world usage patterns, StackOverflow answers, GitHub Gist examples.
-
-**Tool:** `context_exa` — `query` + optional `numResults` (requires `EXA_API_KEY`)
-
-**Query tips:**
-- Include language: `"TypeScript React"`
-- Include version: `"Next.js 14 app router"`
-- Use exact identifiers: `"useServerAction"`
-- Add pattern type: `"example"`, `"error handling"`
-
-**Strengths:** Finds diverse real-world examples beyond official docs.
-
-**Limitations:** Results may be outdated; verify publication dates.
-
----
-
-### 4. Git Clone (direct code inspection)
-
-Best for: Private repositories, detailed implementation review, or when other methods lack depth.
-
-**Process:**
-1. `git clone <repo-url> /tmp/<repo-name> --depth=1`
-2. Read key files: entry points, configuration, core modules
-3. Use bash find/grep and Pi `read` to analyze structure and patterns
-4. Clean up: `rm -rf /tmp/<repo-name>`
-
-**Strengths:** Full code access, works with private repos.
-
-**Limitations:** Requires network/disk space; slow for large repos.
-
----
-
-### 5. Web Search + Fetch (post-clone enrichment)
-
-Best for: Enriching clone findings with changelogs, issue discussions, migration guides.
-
-**Tools:** web search via `curl`/HTTP, HTTP fetch via `curl`
-
-**When to use:** After completing Method 4. Gives you the *why* and *what changed*.
-
-**Query patterns:**
-- Changelogs: `"<repo> CHANGELOG v<version>"`
-- Design rationale: `"<repo> <concept> why OR rationale site:github.com"`
-- Migration: `"<repo> migrate from <old> to <new>"`
-
-**Strengths:** Surfaces context never in source code.
-
-**Limitations:** Results may be stale; always validate against actual code.
-
----
-
 ## Usage
 
-### Pi skill: get-context
-
-Run `/skill:get-context` followed by a natural-language question, repository slug, library name, or several targets. For example:
+Use natural language to ask Pi for research or external context:
 
 ```text
-/skill:get-context React 19 server actions error handling
-/skill:get-context facebook/react
-/skill:get-context facebook/react zustand --method=deepwiki,context7
+Research how facebook/react implements server actions.
+Compare the current React Router and Next.js data-loading guidance.
+Investigate https://github.com/owner/repo and explain its architecture.
 ```
 
-`--method=` accepts `deepwiki,context7,exa,clone,web,all` (comma-separated). With no target, the skill reads dependency manifests in the current directory. It classifies each target and routes it through the allowed methods, noting gaps when a permitted method cannot cover it.
+Pi recognizes these requests and invokes `context_get` automatically. Users do not need to type `context_get` or use a slash command directly; it is an internal native tool with one `query` parameter containing the context request.
 
-### Optional manual brief
+## Child-process constraints
 
-`agents/context-researcher.md` is an optional manual prompt brief for an isolated research pass. Pi does not load it as an invocable agent; use the `get-context` skill for the executable workflow.
+The child runs as:
 
-The package's internal method-selection guidance is loaded by the `get-context` workflow.
+```text
+pi --print --mode json --no-session --tools read,bash --exclude-tools edit,write
+```
 
-## Method Selection Guide
+The child starts in a unique temporary working directory under `/tmp`. It is instructed to use only read-only investigation. If line-level evidence from a public repository is necessary, it may run `git clone --depth=1` in that directory, inspect the clone, and removes the entire temporary directory before completing. It must not modify the caller's working directory or run package-management, deployment, or interactive commands.
 
-| Scenario | Primary | Fallback |
-|----------|---------|----------|
-| "How does X library work?" | Context7 | DeepWiki |
-| "Understand Y repo architecture" | DeepWiki | Git Clone |
-| "Find examples of Z pattern" | Exa | Context7 |
-| "Inspect private/internal repo" | Git Clone | - |
-| "What changed in v3?" | Context7 | Exa |
-| "How are modules connected?" | DeepWiki | Git Clone |
-| "Why was this design decision?" | Git Clone → Web Search | DeepWiki |
-| "Compare X vs Y" (natural-language) | Exa + Context7 | Web Search |
-| "Best practice for Z" (natural-language) | Web Search | Exa |
+Results are bounded before entering the main session and render as compact, expandable context lifecycle rows.
 
 ## Structure
 
-```
-code-context/
-├── extensions/
-│   └── context-tools.ts         # Native pi tools: context_deepwiki / context_context7 / context_exa
-├── agents/
-│   └── context-researcher.md    # Isolated research agent brief
-├── skills/
-│   ├── code-context/            # Knowledge skill (internal)
-│   │   └── SKILL.md            # Method selection guide
-│   └── get-context/             # User-invocable command
-│       └── SKILL.md            # Command workflow
-└── README.md
+```text
+context/
+├── index.ts
+├── extensions/context-tools.ts
+├── extensions/context-command.ts
+├── references/workflow.md
+└── agents/context-researcher.md
 ```
 
-## Prerequisites
-
-- Pi 0.84+ (extensions + custom tools)
-- Network access for external lookups
-- `EXA_API_KEY` for the Exa method (optional for the other four)
-
-## Best Practices
-
-- **Local first**: Always check local context (package.json, imports) before external lookups
-- **Isolated execution**: External lookups run in agent context to keep main conversation clean
-- **Combine methods**: For comprehensive context, use DeepWiki → Context7 → Exa → Clone
-- **Verify sources**: Cross-reference fetched content against actual code
-
 ## License
 
 MIT
-
-## Author
-
-Frad LEE (fradser@gmail.com)

package/agents/context-researcher.md

@@ -1,36 +1,3 @@
----
-name: context-researcher
-description: Research a library, repository, or code pattern without polluting the main conversation. Uses the native context_deepwiki/context_context7/context_exa tools when applicable, otherwise git clone + HTTP fetch via Pi bash/read. Accepts natural-language queries, repo slugs, library names, or any combination.
----
+# Context researcher
 
-# Context researcher (optional agent brief)
-
-Pi does not load Claude Code agent files automatically. Treat this file as a **prompt brief** when you want an isolated research pass. Prefer `/skill:get-context` or `/skill:code-context` for the executable workflow.
-
-## Runtime requirements
-
-| Method | Requirement |
-|--------|-------------|
-| DeepWiki | Native `context_deepwiki` tool |
-| Context7 | Native `context_context7` tool |
-| Exa | Native `context_exa` tool (+ optional `EXA_API_KEY`) |
-| Git clone | `git` + Pi `bash` / `read` (always) |
-| Web | `curl` or host HTTP via Pi `bash` (always) |
-
-If a native context tool is unavailable or fails, skip that method, use clone + web, and report which methods ran and why the fallback was needed.
-
-## Process
-
-1. **Parse the request** — targets and optional `--method=` list (see `/skill:get-context`).
-2. **Classify** each target (repo / library / natural-language).
-3. **Select methods** per `/skill:code-context` selection guide.
-4. **Execute with Pi tools** — use the applicable native context tools (`context_deepwiki`, `context_context7`, `context_exa`) plus `bash` and `read`. Summarize intermediates; do not dump raw payloads.
-5. **Return** a concise architecture/API/examples summary only.
-
-## Output format
-
-- Target classification
-- Methods used (and skipped, with reason)
-- Key findings (bullets)
-- Copyable snippets only when necessary
-- Open questions / confidence notes
+`context_get` is the package's sole Pi tool. It delegates a research request to a fresh read-only Pi process with only `read` and `bash` available. The child may make a depth-1 clone of a public repository in a unique `/tmp` directory when source inspection is needed, then must remove that directory before completing.

package/extensions/context-command.ts

@@ -0,0 +1,15 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const CONTEXT_GUIDANCE = `
+## Isolated research
+
+When the user asks to research, investigate, compare, or understand an external repository, library, codebase, or current technical topic, call \`context_get\`. It starts a separate read-only Pi process and keeps research work out of the main session. The child may inspect public repositories with a depth-1 temporary clone under /tmp.
+`;
+
+export function registerContextGuidance(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", async (event) => ({
+    systemPrompt: event.systemPrompt + CONTEXT_GUIDANCE,
+  }));
+}
+
+export default registerContextGuidance;

package/extensions/context-tools.ts

@@ -1,275 +1,228 @@
-/**
- * Native pi tools for DeepWiki / Context7 / Exa retrieval.
- *
- * Replaces the package's `.mcp.json` (MCP servers). pi has no built-in MCP
- * support (docs/usage.md), so these tools call the public REST APIs directly:
- *   - context_deepwiki  → https://mcp.deepwiki.com/mcp (DeepWiki's public JSON-RPC/SSE API)
- *   - context_context7  → https://context7.com/api/v1/{search,docs}
- *   - context_exa       → https://api.exa.ai/search  (needs EXA_API_KEY)
- *
- * Pure HTTP tools — available in interactive and non-interactive runs alike.
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { truncateHead, DEFAULT_MAX_LINES } from "@earendil-works/pi-coding-agent";
-import { StringEnum } from "@earendil-works/pi-ai";
+import type { ChildProcess } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_MAX_LINES, truncateHead, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import {
+  createToolLifecycleResultRenderer,
+  eventToolLifecycle,
+  resolvePiCli,
+  spawnPiChild,
+  terminateChildProcess,
+} from "@fradser/pi-kit";
 import { Type } from "typebox";
 
+const READ_ONLY_TOOLS = ["read", "bash"];
+const EXCLUDED_TOOLS = ["edit", "write"];
 const MAX_CHARS = 60_000;
-const TIMEOUT_MS = 30_000;
-const DEEPWIKI_MCP = "https://mcp.deepwiki.com/mcp";
+const CHILD_TIMEOUT_MS = 180_000;
 
 interface ToolTextResult {
-	content: [{ type: "text"; text: string }];
-	details: Record<string, unknown>;
+  content: [{ type: "text"; text: string }];
+  details: Record<string, unknown>;
 }
 
-function textResult(text: string, details: Record<string, unknown> = {}): ToolTextResult {
-	return { content: [{ type: "text", text }], details };
+interface ToolResultForRendering {
+  content: unknown;
+  details?: unknown;
 }
 
-function truncate(text: string): string {
-	if (text.length <= MAX_CHARS) return text;
-	const result = truncateHead(text, { maxLines: DEFAULT_MAX_LINES, maxBytes: MAX_CHARS });
-	return `${result.content}\n\n…[truncated ${text.length - MAX_CHARS} chars]`;
+interface ChildResult {
+  text: string;
+  stderr: string;
+  exitCode: number;
+  cancelled: boolean;
+  timedOut: boolean;
 }
 
-function requestSignal(signal: AbortSignal | undefined): AbortSignal {
-	const timeout = AbortSignal.timeout(TIMEOUT_MS);
-	return signal ? AbortSignal.any([signal, timeout]) : timeout;
+function textResult(text: string, details: Record<string, unknown> = {}): ToolTextResult {
+  return { content: [{ type: "text", text }], details };
 }
 
-async function httpJson(
-	url: string,
-	init: RequestInit = {},
-	signal: AbortSignal | undefined,
-): Promise<{ ok: boolean; status: number; body: string }> {
-	const res = await fetch(url, { ...init, signal: requestSignal(signal) });
-	const body = await res.text();
-	return { ok: res.ok, status: res.status, body };
+function emptyToolCall(): Text {
+  return new Text("", 0, 0);
 }
 
-/**
- * DeepWiki's public API is a JSON-RPC-over-HTTP/SSE endpoint (mcp.deepwiki.com).
- * Call a tool directly — no MCP client or sidecar process needed.
- */
-async function deepwikiCall(
-	tool: string,
-	args: Record<string, unknown>,
-	signal: AbortSignal | undefined,
-): Promise<string> {
-	const res = await fetch(DEEPWIKI_MCP, {
-		method: "POST",
-		headers: {
-			"Content-Type": "application/json",
-			Accept: "application/json, text/event-stream",
-		},
-		body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: tool, arguments: args } }),
-		signal: requestSignal(signal),
-	});
-	const body = await res.text();
-	if (!res.ok) throw new Error(`DeepWiki HTTP ${res.status}: ${body.slice(0, 200)}`);
-
-	// SSE frames: `event: message` + one or more `data:` lines, blank-line terminated.
-	// Join multiline payloads, keep the last frame with data.
-	let payload: string | null = null;
-	let currentData: string[] = [];
-	for (const raw of body.split("\n")) {
-		const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
-		if (line === "") {
-			if (currentData.length > 0) payload = currentData.join("\n");
-			currentData = [];
-			continue;
-		}
-		if (line.startsWith(":")) continue; // SSE comment
-		if (line.startsWith("data:")) {
-			currentData.push(line.slice(5).replace(/^ /, ""));
-		}
-	}
-	if (currentData.length > 0) payload = currentData.join("\n");
-	if (payload === null) throw new Error("DeepWiki: no data frame in response");
-
-	const data = JSON.parse(payload);
-	if (data.error) throw new Error(`DeepWiki: ${data.error.message ?? JSON.stringify(data.error)}`);
-	const content = data.result?.content;
-	if (Array.isArray(content)) {
-		return content.map((c) => (typeof c?.text === "string" ? c.text : JSON.stringify(c))).join("\n");
-	}
-	return JSON.stringify(data.result ?? data);
+function compactSubject(value: unknown): string {
+  const normalized = String(value ?? "research").replace(/\s+/g, " ").trim();
+  return normalized.length <= 120 ? normalized : `${normalized.slice(0, 117)}...`;
 }
 
-const DeepWikiParams = Type.Object({
-	owner: Type.String({ description: "GitHub owner, e.g. 'facebook'" }),
-	repo: Type.String({ description: "GitHub repository name, e.g. 'react'" }),
-	mode: StringEnum(["structure", "contents", "ask"], {
-		description: "structure = table of contents; contents = full wiki text; ask = targeted Q&A",
-	}),
-	question: Type.Optional(
-		Type.String({ description: "Required when mode is 'ask'; the question about the repository" }),
-	),
-});
-const Context7Params = Type.Object({
-	query: Type.String({ description: "Library name to find docs for, e.g. 'fastapi' or 'react'" }),
-	topic: Type.Optional(
-		Type.String({ description: "Optional topic focus, e.g. 'auth' or 'ssr' (best results with a topic)" }),
-	),
-});
-
-const ExaParams = Type.Object({
-	query: Type.String({ description: "Precise natural-language or code query" }),
-	numResults: Type.Optional(
-		Type.Number({ description: "Number of results (default 5)", default: 5 }),
-	),
-});
-
-export default function (pi: ExtensionAPI) {
-	pi.registerTool({
-		name: "context_deepwiki",
-		label: "DeepWiki repo docs",
-		description:
-			"Fetch AI-generated documentation for a public GitHub repository from DeepWiki. " +
-			"mode=structure returns the table of contents; mode=contents returns the full wiki text; " +
-			"mode=ask answers a specific question with sources. No API key required.",
-		promptSnippet: "Look up AI-generated documentation for a public GitHub repo from DeepWiki",
-		promptGuidelines: [
-			"Use context_deepwiki to fetch structured repo documentation via DeepWiki instead of cloning when you only need a high-level understanding.",
-		],
-		parameters: DeepWikiParams,
-		executionMode: "sequential",
-
-		async execute(_toolCallId, params, signal) {
-			const repo = `${params.owner}/${params.repo}`;
-			if (params.mode === "ask") {
-				if (!params.question) {
-					return textResult("context_deepwiki: mode 'ask' requires a question");
-				}
-				const answer = await deepwikiCall("ask_question", { repoName: repo, question: params.question }, signal);
-				return textResult(truncate(answer));
-			}
-			const tool = params.mode === "structure" ? "read_wiki_structure" : "read_wiki_contents";
-			const out = await deepwikiCall(tool, { repoName: repo }, signal);
-			return textResult(truncate(out));
-		},
-	});
-
-	pi.registerTool({
-		name: "context_context7",
-		label: "Context7 library docs",
-		description:
-			"Fetch up-to-date, version-aware documentation snippets for a library from Context7. " +
-			"Searches the library, then retrieves markdown docs (optionally focused on a topic). " +
-			"Anonymous usage is rate-limited; set CONTEXT7_API_KEY (Authorization: Bearer) for per-key quota.",
-		promptSnippet: "Look up version-aware library documentation from Context7",
-		promptGuidelines: [
-			"Use context_context7 to look up library docs instead of guessing APIs from memory. Anonymous usage is rate-limited; set CONTEXT7_API_KEY for higher quota.",
-		],
-		parameters: Context7Params,
-		executionMode: "sequential",
-
-		async execute(_toolCallId, params, signal) {
-			const headers: Record<string, string> = {};
-			if (process.env.CONTEXT7_API_KEY) {
-				headers.Authorization = `Bearer ${process.env.CONTEXT7_API_KEY}`;
-			}
+function truncate(text: string): string {
+  if (text.length <= MAX_CHARS) return text;
+  const result = truncateHead(text, { maxLines: DEFAULT_MAX_LINES, maxBytes: MAX_CHARS });
+  return `${result.content}\n\n…[truncated ${text.length - MAX_CHARS} chars]`;
+}
 
-			const { ok, status, body } = await httpJson(
-				`https://context7.com/api/v1/search?query=${encodeURIComponent(params.query)}`,
-				{ headers },
-				signal,
-			);
-			if (!ok) {
-				if (status === 401 || status === 403) {
-					return textResult(
-						`Context7 search needs an API key (HTTP ${status}). Set CONTEXT7_API_KEY ` +
-							`(Authorization: Bearer) or fall back to web/clone methods.`,
-					);
-				}
-				throw new Error(`Context7 search failed (HTTP ${status}): ${body.slice(0, 400)}`);
-			}
+function renderContextResult(
+  result: ToolResultForRendering,
+  options: { expanded?: boolean },
+  theme: { fg(color: string, text: string): string; bg(color: string, text: string): string; bold(text: string): string },
+  context: { isError?: boolean },
+  subject: string,
+) {
+  return createToolLifecycleResultRenderer<ToolResultForRendering, Text>({
+    createSpec: (_result, _text, details) => eventToolLifecycle("context", subject, {
+      label: "researched",
+      details,
+      detailLimit: 50,
+    }),
+    expandHint: "ctrl+o to expand",
+    fit: truncateToWidth,
+    visibleWidth,
+    renderError: (line, errorTheme) => new Text(errorTheme.fg("error", line), 0, 0),
+  })(result, options, theme, context);
+}
 
-			let data: { results?: Array<{ id?: unknown }> };
-			try {
-				data = JSON.parse(body);
-			} catch {
-				throw new Error(`Context7 search: unexpected response: ${body.slice(0, 400)}`);
-			}
-			const results = Array.isArray(data.results) ? data.results : [];
-			if (results.length === 0) {
-				return textResult(`Context7: no library found for "${params.query}"`);
-			}
-			const libraryId = typeof results[0]?.id === "string" ? results[0].id : "";
-			if (!libraryId) {
-				return textResult(`Context7: search returned no usable library id for "${params.query}"`);
-			}
+export function buildResearchPrompt(query: string): string {
+  return [
+    "Research the user's request independently and return a concise, evidence-based answer.",
+    "You are in a child Pi process. Use only read and bash; never edit or write files.",
+    "For public repository line-level evidence, you may run git clone --depth=1 into a unique /tmp directory, inspect it, and remove it before answering.",
+    "Never modify the caller's working directory. Do not use package managers, deployment commands, or interactive commands.",
+    "Cite concrete source URLs, repository paths, or documentation names when available.",
+    "Keep raw findings compact and synthesize the answer rather than dumping large payloads.",
+    "",
+    "User research request:",
+    query,
+  ].join("\n");
+}
 
-			// v1 doc ids look like "/owner/repo" — strip the leading slash for the path.
-			const path = libraryId.startsWith("/") ? libraryId.slice(1) : libraryId;
-			const topic = params.topic ? `&topic=${encodeURIComponent(params.topic)}` : "";
-			const docUrl = `https://context7.com/api/v1/${path}?type=txt${topic}`;
-			const doc = await httpJson(docUrl, { headers }, signal);
-			if (!doc.ok) {
-				throw new Error(`Context7 docs failed (HTTP ${doc.status}): ${doc.body.slice(0, 400)}`);
-			}
-			return textResult(
-				`Context7 docs for "${params.query}" (${libraryId})${params.topic ? `, topic ${params.topic}` : ""}:\n\n${truncate(doc.body)}`,
-			);
-		},
-	});
+function parseChildOutput(stdout: string): string {
+  let text = "";
+  for (const line of stdout.split("\n")) {
+    try {
+      const event = JSON.parse(line) as { type?: string; message?: { role?: string; content?: Array<{ type?: string; text?: string }> } };
+      if (event.type !== "message_end" || event.message?.role !== "assistant") continue;
+      const candidate = (event.message.content ?? [])
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("");
+      if (candidate.trim()) text = candidate;
+    } catch {
+      // JSON mode may include non-event output; it is not part of the result.
+    }
+  }
+  return text.trim();
+}
 
-	pi.registerTool({
-		name: "context_exa",
-		label: "Exa web/code search",
-		description:
-			"Search the web for real-world code patterns, comparisons, and up-to-date information via Exa. " +
-			"Requires the EXA_API_KEY environment variable. Returns titles, URLs, and text snippets.",
-		promptSnippet: "Search the web for real-world code patterns, comparisons, and up-to-date information via Exa",
-		promptGuidelines: [
-			"Use context_exa to search the web when you need current information, code patterns, or comparisons. Requires EXA_API_KEY to be set.",
-		],
-		parameters: ExaParams,
-		executionMode: "sequential",
+function sandboxProfile(researchDirectory: string): string {
+  const temporaryDirectory = researchDirectory.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  return [
+    "(version 1)",
+    "(deny default)",
+    "(allow process*)",
+    "(allow sysctl-read)",
+    "(allow file-read*)",
+    `(allow file-write* (subpath \"${temporaryDirectory}\"))`,
+    "(allow network*)",
+  ].join("\n");
+}
 
-		async execute(_toolCallId, params, signal) {
-			const apiKey = process.env.EXA_API_KEY;
-			if (!apiKey) {
-				return textResult(
-					"context_exa: EXA_API_KEY is not set. Set EXA_API_KEY to enable Exa search, " +
-						"or fall back to web search via curl / GitHub search.",
-				);
-			}
+export function runResearchChild(query: string, signal?: AbortSignal): Promise<ChildResult> {
+  const cli = resolvePiCli();
+  const researchDirectory = realpathSync(mkdtempSync(join(tmpdir(), "pi-context-")));
+  const piArgs = [
+    ...cli.args,
+    "--print",
+    "--mode",
+    "json",
+    "--no-session",
+    "--tools",
+    READ_ONLY_TOOLS.join(","),
+    "--exclude-tools",
+    EXCLUDED_TOOLS.join(","),
+    buildResearchPrompt(query),
+  ];
+
+  const sandboxed = process.platform === "darwin";
+  const command = sandboxed ? "sandbox-exec" : cli.command;
+  const args = sandboxed ? ["-p", sandboxProfile(researchDirectory), cli.command, ...piArgs] : piArgs;
+
+  return new Promise((resolve, reject) => {
+    let child: ChildProcess;
+    let settled = false;
+    try {
+      child = spawnPiChild(command, args, { cwd: researchDirectory, env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error) {
+      rmSync(researchDirectory, { recursive: true, force: true });
+      reject(error);
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let termination: Promise<boolean> | undefined;
+    let timedOut = false;
+    let cancelled = false;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      termination ??= terminateChildProcess(child);
+    }, CHILD_TIMEOUT_MS);
+    timeout.unref?.();
+    const abort = () => {
+      cancelled = true;
+      termination ??= terminateChildProcess(child);
+    };
+    if (signal?.aborted) abort();
+    else signal?.addEventListener("abort", abort, { once: true });
+
+    child.stdout?.on("data", (chunk: Buffer) => { stdout += chunk.toString(); });
+    child.stderr?.on("data", (chunk: Buffer) => { stderr += chunk.toString(); });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", abort);
+      clearTimeout(timeout);
+      rmSync(researchDirectory, { recursive: true, force: true });
+      reject(error);
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", abort);
+      clearTimeout(timeout);
+      rmSync(researchDirectory, { recursive: true, force: true });
+      resolve({ text: parseChildOutput(stdout), stderr: stderr.trim(), exitCode: code ?? 1, cancelled, timedOut });
+    });
+  });
+}
 
-			const numResults = Math.max(1, Math.min(10, Math.floor(params.numResults ?? 5)));
-			const { ok, status, body } = await httpJson(
-				"https://api.exa.ai/search",
-				{
-					method: "POST",
-					headers: {
-						"Content-Type": "application/json",
-						"x-api-key": apiKey,
-					},
-					body: JSON.stringify({ query: params.query, numResults, contents: { text: true } }),
-				},
-				signal,
-			);
-			if (!ok) throw new Error(`Exa search failed (HTTP ${status}): ${body.slice(0, 400)}`);
+const ResearchParams = Type.Object({
+  query: Type.String({ description: "Research request: repository, library, codebase question, or current technical topic." }),
+});
 
-			let data: { results?: Array<{ title?: string; url?: string; text?: string }> };
-			try {
-				data = JSON.parse(body);
-			} catch {
-				throw new Error(`Exa search: unexpected response: ${body.slice(0, 400)}`);
-			}
-			const results = Array.isArray(data.results) ? data.results : [];
-			if (results.length === 0) {
-				return textResult(`Exa: no results for "${params.query}"`);
-			}
-			const lines = results.map((r, i) => {
-				const title = r.title || r.url || "(untitled)";
-				const url = r.url || "";
-				const text = typeof r.text === "string" ? r.text.slice(0, 1200) : "";
-				return `${i + 1}. ${title}\n   ${url}\n${text ? `   ${text}` : ""}`;
-			});
-			return textResult(truncate(lines.join("\n\n")));
-		},
-	});
+export function registerContextTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "context_get",
+    label: "Isolated Pi research",
+    description: "Research a repository, library, codebase, or technical topic in an independent read-only Pi child process. The child can inspect and temporarily clone public repositories under /tmp.",
+    promptSnippet: "Research independently in a read-only child Pi process",
+    promptGuidelines: [
+      "Use context_get when the user needs external context for a repository, library, codebase, or current technical topic. It retrieves that context in an isolated read-only Pi process.",
+    ],
+    parameters: ResearchParams,
+    executionMode: "sequential",
+    renderShell: "self",
+    renderCall: emptyToolCall,
+    renderResult(result, options, theme, context) {
+      const params = context.args as { query?: string };
+      return renderContextResult(result, options, theme, context, compactSubject(params.query));
+    },
+    async execute(_toolCallId, params, signal) {
+      const child = await runResearchChild(params.query, signal);
+      if (child.cancelled) throw new Error("Isolated Pi research was cancelled");
+      if (child.timedOut) throw new Error("Isolated Pi research timed out");
+      if (child.exitCode !== 0) {
+        throw new Error(`Isolated Pi research failed (exit ${child.exitCode}): ${child.stderr.slice(0, 400)}`);
+      }
+      if (!child.text) {
+        throw new Error("Isolated Pi research returned no answer");
+      }
+      return textResult(truncate(child.text), { exitCode: child.exitCode });
+    },
+  });
 }
+
+export default registerContextTools;

package/index.ts

@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import registerContextGuidance from "./extensions/context-command.ts";
+import registerContextTools from "./extensions/context-tools.ts";
+
+export default function contextExtension(pi: ExtensionAPI): void {
+  registerContextTools(pi);
+  registerContextGuidance(pi);
+}

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@fradser/pi-context",
-  "version": "0.5.0",
-  "description": "Retrieve code context for any repo, library, or natural-language query via DeepWiki, Context7, Exa, git clone, and web search+fetch. Native pi tools (context_deepwiki/context_context7/context_exa) call the public REST APIs directly — no MCP servers.",
+  "version": "0.6.0",
+  "description": "Retrieve context for repositories, libraries, and technical questions with one native tool that launches an isolated read-only Pi research child.",
   "keywords": [
     "pi-package",
     "code-context",
-    "deepwiki",
-    "context7",
-    "exa"
+    "isolated-research",
+    "read-only"
   ],
   "author": "Frad LEE <fradser@gmail.com>",
   "license": "MIT",
@@ -19,22 +18,24 @@
     "access": "public"
   },
   "files": [
-    "skills",
+    "index.ts",
     "extensions",
+    "references",
     "agents",
     "README.md"
   ],
   "pi": {
-    "skills": [
-      "./skills"
-    ],
     "extensions": [
-      "./extensions"
+      "./index.ts"
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
+  },
+  "dependencies": {
+    "@fradser/pi-kit": "0.4.2"
   }
-}
+}

package/references/workflow.md

@@ -0,0 +1,7 @@
+# Isolated context research workflow
+
+Use `context_get` for a repository, library, codebase, or technical research request. It launches a separate Pi process so exploratory work and its tool calls do not enter the main session.
+
+The child is read-only: it can use `read` and `bash`, but never `edit` or `write`. For public repository evidence it may run `git clone --depth=1` into a unique directory under `/tmp`, inspect only the relevant files, cite the evidence in its answer, and remove the clone before it exits.
+
+The returned answer should synthesize findings, distinguish facts from uncertainty, and cite useful source URLs or repository paths. It must not modify the caller's working directory.

package/skills/code-context/SKILL.md

@@ -1,127 +0,0 @@
----
-name: code-context
-description: This skill should be used when the user asks to "understand a codebase", "get code context", "research a library", "explore a repository", "find code examples", "look up documentation", asks a natural-language code/technology question (e.g. "how does X work", "X vs Y", "best practice for Z"), or wants to understand how a specific project, library, or concept works before making changes.
-disable-model-invocation: true
----
-
-# Code Context Retrieval
-
-This skill provides 5 methods for retrieving code context. Select methods based on the target: public GitHub repos, library docs, code search, direct inspection, or post-clone web enrichment.
-
-## Pi tools and runtime
-
-Use Pi built-ins: `bash`, `read`, `edit` (rarely), `write` (rarely), plus this package's native tools from `extensions/context-tools.ts`.
-
-| Method | Runtime |
-|--------|---------|
-| DeepWiki | `context_deepwiki` tool (always available; no key) |
-| Context7 | `context_context7` tool (always available; optional `CONTEXT7_API_KEY` for higher quota) |
-| Exa | `context_exa` tool (requires `EXA_API_KEY` env) |
-| Git clone | `bash` + `read` (always available) |
-| Web search+fetch | `bash` + `curl` (or host HTTP) |
-
-If a tool reports an error (e.g. `EXA_API_KEY` unset), skip it and use clone/web fallbacks. Report which methods ran.
-
-## Token Isolation (Critical)
-
-Prefer small intermediate summaries over dumping entire API payloads into the long-lived conversation:
-
-- **DeepWiki**: structure → relevant pages → short architecture summary
-- **Context7**: resolve id → query → minimum viable API surface + examples
-- **Exa**: query → dedupe near-identical snippets → short explanation
-- **Git clone**: clone to `/tmp/`, read entry points, cleanup, return structure + patterns
-- **Web**: targeted queries, fetch high-signal URLs only, validate against code when possible
-
-## Method 1: DeepWiki (AI-powered repo documentation)
-
-Best for: public GitHub repos needing architecture overview quickly.
-
-**Tool**: `context_deepwiki` (native, always available)
-
-**Process**:
-1. `context_deepwiki` with `owner`/`repo` and `mode: "structure"` (e.g. `facebook` / `react`)
-2. `context_deepwiki` `mode: "contents"` for the full wiki text, or `mode: "ask"` with a `question` for targeted Q&A
-3. Extract architecture summary and key relationships
-
-**Fallback on error**: Method 4 (clone) + Method 5 (web) on GitHub docs/README.
-
-## Method 2: Context7 (library documentation)
-
-Best for: up-to-date API docs and version-specific examples for packages/frameworks.
-
-**Tool**: `context_context7` (native, always available)
-
-**Process**:
-1. `context_context7` with the library name as `query` (e.g. `fastapi`, `react`)
-2. Pass a `topic` (e.g. `auth`, `ssr`) for focused snippets; include the version in the query when given (`react@18`)
-3. Extract the minimum viable API surface + examples
-
-**Fallback on error**: official docs URLs via `curl`, or clone of the library repo docs.
-
-## Method 3: Exa Code Search
-
-Best for: real-world usage patterns and cross-web code examples.
-
-**Tool**: `context_exa` (native; requires `EXA_API_KEY`)
-
-**Process**:
-1. Call with a precise query (language/framework/version/identifiers)
-2. Prefer recent sources; dedupe mirrors
-
-**Fallback when key missing / error**: GitHub code search URLs / known docs via `curl`, or clone representative examples.
-
-## Method 4: Git Clone (direct code inspection)
-
-Best for: private repos, deep implementation review, when other methods lack depth.
-
-**Process**:
-1. `git clone <repo-url> /tmp/<repo-name> --depth=1`
-2. `read` key files: entry points, config, core modules
-3. Map structure with `bash` find/ls; search with `bash` grep or Pi search tools if available
-4. Cleanup: `rm -rf /tmp/<repo-name>`
-
-## Method 5: Web Search + Fetch
-
-Best for: rationale, changelogs, issues, migration guides.
-
-**Tools**: `bash` + `curl` (or host HTTP client). There are no Pi built-ins named web search via `curl`/HTTP / HTTP fetch via `curl`.
-
-**Process**:
-1. Derive version-anchored queries from the question or clone findings
-2. Fetch high-signal URLs (official docs, GitHub issues/PRs, changelogs)
-3. Extract only relevant sections; cross-check against cloned code when available
-4. Discard results older than ~2 years unless foundational
-
-**Query patterns**:
-- Changelogs: `"<repo> CHANGELOG v<version>"`
-- Rationale: `"<repo> <concept> why OR rationale site:github.com"`
-- Known issues: `"<repo> <symbol> issue OR bug site:github.com"`
-- Migration: `"<repo> migrate from <old> to <new>"`
-
-## Target Classification
-
-- **Repo target** — `owner/repo` or git URL → DeepWiki (`context_deepwiki`) or Git Clone
-- **Library target** — package name / `name@version` → Context7 (`context_context7`) else web/docs clone
-- **Natural-language target** — question/comparison → Exa (`context_exa`) and/or Web; Context7 if a library is named
-
-When caller passes `--method=`, use the intersection of allowed and applicable methods. Empty intersection → skip and report.
-
-## Method Selection Guide
-
-| Scenario | Primary | Fallback |
-|----------|---------|----------|
-| "How does X library work?" | Context7 | Web / clone |
-| "Architecture of Y repo" | DeepWiki | Git Clone |
-| "Examples of Z pattern" | Exa | Context7 / web |
-| "Private/internal repo" | Git Clone | — |
-| "What changed in v3?" | Context7 | Web |
-| "Why this design?" | Git Clone → Web | DeepWiki |
-| "Compare X vs Y" | Exa + Context7 | Web |
-| "Best practice for Z" | Web | Exa |
-
-## Combining Methods
-
-1. DeepWiki / clone for architecture
-2. Context7 for API surface
-3. Exa / web for community patterns
-4. Always prefer read-only operations; clean up `/tmp` clones

package/skills/get-context/SKILL.md

@@ -1,38 +0,0 @@
----
-name: get-context
-description: Execute this when the user requests code context for a repository, library, or any natural-language code/technology question using DeepWiki, Context7, Exa, git clone, and/or web search+fetch.
----
-
-# get-context
-
-Run the full code-context workflow using Pi tools. Prefer keeping heavy lookups out of a single giant turn when possible — summarize intermediate results.
-
-## Pi tools and runtime
-
-| Capability | How |
-|------------|-----|
-| Clone / local files | `bash` (`git clone`), `read`, `bash` (find/grep) |
-| Web fetch | `bash` with `curl -fsSL` (or available HTTP client) |
-| DeepWiki / Context7 / Exa | Native tools from this package's `extensions/context-tools.ts`: `context_deepwiki`, `context_context7`, `context_exa` (Exa needs `EXA_API_KEY`) |
-
-If a native tool is unavailable (e.g. `EXA_API_KEY` unset), fall back to clone + web fetch methods from `/skill:code-context`.
-
-## Invocation args
-
-When invoked as `/skill:get-context <args>`, the text after the skill block is the user-provided arguments. Pi does not expand `$ARGUMENTS` placeholders inside skill bodies; use the trailing invocation text.
-
-1. Split into positional targets and optional `--method=` flag.
-   - `--method=` accepts a comma-separated list from `deepwiki,context7,exa,clone,web,all`. Default: `all`.
-   - Quoted strings are one target.
-   - Multiple positional tokens are multiple targets.
-2. Classify each target:
-   - GitHub slug (`owner/repo`) or git URL → repo (DeepWiki via `context_deepwiki`, else clone).
-   - Bare package name or `name@version` → library (Context7 via `context_context7`, else web + clone of docs repo when known).
-   - Anything else → natural-language (Exa via `context_exa` when `EXA_API_KEY` is set, else web search via `curl` to searchable sources / known docs URLs).
-3. Empty input: read dependency manifests in cwd (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`) and use detected dependencies as targets.
-
-## Execute
-
-1. Load and follow `/skill:code-context` (or `read` that skill file) for method selection and process detail.
-2. Run methods with Pi tools as above; do not invent Claude-only tools (`Task`, `WebSearch`, `WebFetch`).
-3. Return a synthesized summary only — drop raw bulk payloads.