@fradser/pi-context 0.5.1 → 0.6.1

package/README.md

@@ -1,91 +1,51 @@
-# Context Pi Package
+# @fradser/pi-context
 
-**Version:** 0.5.0
+`@fradser/pi-context` exposes one tool: `context_get`.
 
-Retrieve code context for any repo, library, or natural-language query via 5 methods: DeepWiki, Context7, Exa, git clone, and web search+fetch.
-
-The package does **not** ship a skill. Native tool guidance is injected into the system prompt, and the `/context` command loads the full workflow into the current turn.
+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 npm:@fradser/pi-context
-# or from this repository:
-pi install /path/to/pi-packages/packages/context
 ```
 
 ## Usage
 
-Run `/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
-/context React 19 server actions error handling
-/context facebook/react
-/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 command reads dependency manifests in the current directory (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`) and uses detected dependencies as targets.
-
-The full workflow (target classification, per-method process, fallbacks, selection guide) lives in `references/workflow.md` and is injected into the turn when `/context` runs. Lightweight tool-selection guidance is always present in the system prompt.
-
-## 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` |
+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.
 
-All three retrieval tools are registered by this package's root extension entry (`index.ts`) and call the public REST APIs directly — no MCP servers needed.
+## Child-process constraints
 
-## Methods (summary)
+The child runs as:
 
-1. **DeepWiki** — AI-generated repo docs via `context_deepwiki` (`mode: structure | contents | ask`).
-2. **Context7** — up-to-date library docs via `context_context7` (`query` + optional `topic`).
-3. **Exa** — web/code search via `context_exa` (`query` + optional `numResults`, requires `EXA_API_KEY`).
-4. **Git clone** — `git clone --depth=1` to `/tmp`, `read` key files, clean up.
-5. **Web search+fetch** — `bash` + `curl` against official docs, GitHub issues, changelogs.
-
-If a native tool is unavailable or errors, fall back to clone/web. The `/context` workflow reference contains the full selection matrix and per-method process.
+```text
+pi --print --mode json --no-session -ne -ns -np -nc --no-themes --tools read,bash
+```
 
-## Optional manual brief
+The child runs in the caller's working directory through pi-kit's minimal `runPiWorker` mode: `-ne -ns -np -nc --no-themes` disables extension, skill, prompt-template, context-file, and theme discovery, while `--tools read,bash` exposes only the two required tools. It has no sandbox, timeout, or display truncation; `bash` remains technically able to write because there is no OS sandbox, so the bundled worker prompt requires no modifications. If line-level evidence from a public repository is necessary, it may use `git clone --depth=1` under `/tmp` with removal after inspection. It must not run package-management, deployment, or interactive commands. The shared worker fails closed if its bounded stdout, stderr, or JSONL line limits are exceeded.
 
-`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 `/context` command for the executable workflow.
+A package-local typed builder reads the bundled Markdown as a reference protocol and builds a task-specific context-review prompt containing the caller working directory, complete research request, reference protocol, and completion contract. The Markdown file itself is never used as an execution identity. Startup renders `[context] research started · <research query>`, using the normalized concrete query that produced the prompt; the row remains width-bounded and does not expose the resource path. While the async child runs, the transcript keeps only that started row with no duplicate progress row; live progress shows in the researcher widget above the editor. The widget shows neutral live research activity. The child always runs with `--no-session`, so separate invocations retain no memory or agent-teams state. A successful empty answer is retried exactly once with a stronger completion requirement that does not rely on hidden reasoning or prior tool output. Results enter the main session untruncated and render as a compact, expandable `[context] researched` lifecycle row.
 
 ## Structure
 
-```
+```text
 context/
-├── index.ts                     # Package-root extension entry point
-├── extensions/
-│   ├── context-tools.ts         # Native pi tools: context_deepwiki / context_context7 / context_exa
-│   └── context-command.ts       # /context command + system-prompt guidance
-├── references/
-│   └── workflow.md              # Full workflow injected by /context
-├── agents/
-│   └── context-researcher.md    # Isolated research brief (manual)
-└── README.md
+├── index.ts
+├── extensions/context-tools.ts
+├── extensions/context-command.ts
+├── references/workflow.md
+├── extensions/context-prompt.ts
+└── prompts/context-research.md
 ```
 
-## Prerequisites
-
-- Pi with extensions + custom tools
-- Network access for external lookups
-- `EXA_API_KEY` for the Exa method (optional for the other four)
-
-## Best Practices
-
-- **Local first**: check local context (package.json, imports) before external lookups.
-- **Combine methods**: DeepWiki / clone for architecture, Context7 for API surface, Exa / web for community patterns.
-- **Verify sources**: cross-reference fetched content against actual code.
-- **Clean up**: remove `/tmp` clones when finished.
-
 ## License
 
 MIT
-
-## Author
-
-Frad LEE (fradser@gmail.com)

package/extensions/context-command.ts

@@ -1,121 +1,15 @@
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-const PKG_DIR =
-  typeof __dirname === "string"
-    ? __dirname
-    : dirname(fileURLToPath(import.meta.url));
-
-const WORKFLOW_PATH = join(PKG_DIR, "..", "references", "workflow.md");
-
-const METHOD_FLAG = "--method=";
-const ALL_METHODS = ["deepwiki", "context7", "exa", "clone", "web", "all"] as const;
-const MANIFEST_FILES = ["package.json", "pyproject.toml", "go.mod", "Cargo.toml"];
-
 const CONTEXT_GUIDANCE = `
-## Context retrieval
+## Isolated research
 
-- Use \`context_deepwiki\` for public GitHub repo architecture and DeepWiki Q&A.
-- Use \`context_context7\` for up-to-date library/API docs (optionally focused by topic).
-- Use \`context_exa\` for web/code search when EXA_API_KEY is set; otherwise fall back to \`bash\` + \`curl\`.
-- Use \`git clone --depth=1\` to /tmp plus \`read\`/\`bash\` for private repos or deep inspection; always clean up.
-- Prefer small intermediate summaries over dumping raw API payloads into the conversation.
-- The \`/context <targets...> [--method=...]\` command loads the full workflow when the user asks to research or understand code.
+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 Pi process with a read/bash allowlist, disabled extension discovery, and prompt-level no-modification guidance; research stays out of the main session. The child may inspect public repositories with a depth-1 temporary clone under /tmp.
 `;
 
-interface ParsedArgs {
-  targets: string[];
-  methods: string[];
-}
-
-function parseArgs(raw: string): ParsedArgs {
-  const targets: string[] = [];
-  let methods: string[] = ["all"];
-  const tokens = raw.match(/(?:[^\s"]+|"[^"]*")+/g) ?? [];
-  for (const token of tokens) {
-    if (token.startsWith(METHOD_FLAG)) {
-      methods = token
-        .slice(METHOD_FLAG.length)
-        .split(",")
-        .map((m) => m.trim().toLowerCase())
-        .filter((m) => (ALL_METHODS as readonly string[]).includes(m));
-      if (methods.length === 0) methods = ["all"];
-      continue;
-    }
-    targets.push(token.replace(/^"|"$/g, ""));
-  }
-  return { targets, methods };
-}
-
-function detectDependencies(cwd: string): string[] {
-  const deps = new Set<string>();
-  for (const file of MANIFEST_FILES) {
-    try {
-      const text = readFileSync(join(cwd, file), "utf8");
-      if (file === "package.json") {
-        const json = JSON.parse(text) as {
-          dependencies?: Record<string, string>;
-          devDependencies?: Record<string, string>;
-        };
-        for (const name of Object.keys(json.dependencies ?? {})) deps.add(name);
-        for (const name of Object.keys(json.devDependencies ?? {})) deps.add(name);
-      } else if (file === "pyproject.toml") {
-        for (const match of text.matchAll(/^\s*"([A-Za-z0-9_.-]+)"\s*[>=<~!]/gm)) {
-          deps.add(match[1]);
-        }
-      } else if (file === "go.mod") {
-        for (const match of text.matchAll(/^\s*([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\s+v/gm)) {
-          deps.add(match[1]);
-        }
-      } else if (file === "Cargo.toml") {
-        for (const match of text.matchAll(/^([A-Za-z0-9_-]+)\s*=\s*"[^"]+"/gm)) {
-          deps.add(match[1]);
-        }
-      }
-    } catch {
-      // Missing or unreadable manifest — skip.
-    }
-  }
-  return [...deps];
-}
-
-function loadWorkflow(): string {
-  return readFileSync(WORKFLOW_PATH, "utf8");
-}
-
-function buildUserPrompt(args: ParsedArgs, cwd: string): string {
-  const workflow = loadWorkflow();
-  const targets = args.targets.length > 0 ? args.targets : detectDependencies(cwd);
-  const header = [
-    "Run the /context workflow.",
-    "",
-    `Targets: ${targets.length > 0 ? targets.join(", ") : "(none provided and no dependencies detected in cwd)"}`,
-    `Allowed methods: ${args.methods.join(",")}`,
-    "",
-    "---",
-    "",
-  ].join("\n");
-  return header + workflow;
-}
-
-export function registerContextCommand(pi: ExtensionAPI): void {
+export function registerContextGuidance(pi: ExtensionAPI): void {
   pi.on("before_agent_start", async (event) => ({
     systemPrompt: event.systemPrompt + CONTEXT_GUIDANCE,
   }));
-
-  pi.registerCommand("context", {
-    description:
-      "Retrieve code context for repos, libraries, or a natural-language question via DeepWiki, Context7, Exa, clone, or web.",
-    handler: async (rawArgs, ctx) => {
-      const args = parseArgs(rawArgs.trim());
-      const prompt = buildUserPrompt(args, ctx.cwd);
-      pi.sendUserMessage(prompt, { deliverAs: "followUp" });
-    },
-  });
 }
 
-export default function register(pi: ExtensionAPI): void {
-  registerContextCommand(pi);
-}
+export default registerContextGuidance;

package/extensions/context-prompt.ts

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+
+export interface ContextResearchPromptBindings {
+  userResearchRequest: string;
+  workingDirectory: string;
+}
+
+const CONTEXT_REVIEW_COMPLETION = [
+  "Return one self-contained review of the requested context.",
+  "State the conclusion, cite concrete evidence, and distinguish observed facts from uncertainty.",
+  "Finish with a textual final answer rather than ending after a tool call.",
+].join(" ");
+
+const CONTEXT_RESEARCH_TEMPLATE_URL = new URL("../prompts/context-research.md", import.meta.url);
+const PLACEHOLDER_PATTERN = /\{\{([A-Z][A-Z0-9_]*)\}\}/g;
+const PLACEHOLDER_TOKEN_PATTERN = /\{\{[^{}]+\}\}/g;
+const REQUIRED_PLACEHOLDERS = ["USER_RESEARCH_REQUEST"] as const;
+
+function templatePlaceholders(template: string): string[] {
+  return [...template.matchAll(PLACEHOLDER_PATTERN)].map((match) => match[1]);
+}
+
+function placeholderTokens(template: string): string[] {
+  return template.match(PLACEHOLDER_TOKEN_PATTERN) ?? [];
+}
+
+export function validateContextPromptTemplate(template: string): void {
+  const placeholders = templatePlaceholders(template);
+  const allowedTokens = new Set(REQUIRED_PLACEHOLDERS.map((placeholder) => `{{${placeholder}}}`));
+  const unknown = [...new Set(placeholderTokens(template).filter((token) => !allowedTokens.has(token)))];
+  if (unknown.length > 0) {
+    throw new Error(`Context prompt has unknown placeholder(s): ${unknown.join(", ")}`);
+  }
+  const missing = REQUIRED_PLACEHOLDERS.filter((placeholder) => !placeholders.includes(placeholder));
+  if (missing.length > 0) {
+    throw new Error(`Context prompt has missing placeholder(s): ${missing.join(", ")}`);
+  }
+}
+
+export function renderContextPromptTemplate(
+  template: string,
+  bindings: ContextResearchPromptBindings,
+): string {
+  validateContextPromptTemplate(template);
+  const rendered = template.replace(
+    "{{USER_RESEARCH_REQUEST}}",
+    () => bindings.userResearchRequest,
+  );
+  const bindingTokens = new Set(placeholderTokens(bindings.userResearchRequest));
+  const unexpected = placeholderTokens(rendered).filter((token) => !bindingTokens.has(token));
+  if (unexpected.length > 0) {
+    throw new Error(`Context prompt has unresolved placeholder(s): ${[...new Set(unexpected)].join(", ")}`);
+  }
+  return rendered;
+}
+
+const CONTEXT_RESEARCH_TEMPLATE = readFileSync(CONTEXT_RESEARCH_TEMPLATE_URL, "utf8").trim();
+
+export function buildContextResearchPrompt(bindings: ContextResearchPromptBindings): string {
+  const protocol = renderContextPromptTemplate(CONTEXT_RESEARCH_TEMPLATE, bindings);
+  return [
+    "# Context Review",
+    "",
+    "## Current Research Task",
+    `Working directory: ${bindings.workingDirectory}`,
+    "",
+    bindings.userResearchRequest,
+    "",
+    "## Reference Protocol",
+    protocol,
+    "",
+    "## Completion Contract",
+    CONTEXT_REVIEW_COMPLETION,
+  ].join("\n");
+}

package/extensions/context-tools.ts

@@ -1,277 +1,231 @@
-/**
- * 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 { getMarkdownTheme, keyHint, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type Component, Markdown, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import {
+  createLiveActivityWidget,
+  createStaticToolLifecycleResultRenderer,
+  eventToolLifecycle,
+  runPiWorker,
+  type PiLiveWidgetContext,
+  type PiWorkerProgressUpdate,
+} from "@fradser/pi-kit";
 import { Type } from "typebox";
+import { buildContextResearchPrompt } from "./context-prompt.ts";
+
+const RESEARCH_TOOLS = ["read", "bash"];
+const FINAL_ANSWER_RETRY_INSTRUCTION = `
 
-const MAX_CHARS = 60_000;
-const TIMEOUT_MS = 30_000;
-const DEEPWIKI_MCP = "https://mcp.deepwiki.com/mcp";
+Completion requirement: the previous attempt produced no textual final answer. Complete the original research request now without relying on hidden reasoning, transient tool output, or state from the prior attempt; repeat any inspection needed to support the answer. Your final assistant message must be a self-contained plain-text answer with the conclusion and concrete evidence. Do not finish immediately after a tool call.`;
 
 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 ChildResult {
+  text: string;
+  stderr: string;
+  exitCode: number;
+  cancelled: boolean;
 }
 
-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 ResearchAttemptResult extends ChildResult {
+  retried: boolean;
 }
 
-function requestSignal(signal: AbortSignal | undefined): AbortSignal {
-	const timeout = AbortSignal.timeout(TIMEOUT_MS);
-	return signal ? AbortSignal.any([signal, timeout]) : timeout;
-}
+type ResearchRunner = (
+  query: string,
+  signal: AbortSignal | undefined,
+  onUpdate: ((update: PiWorkerProgressUpdate) => void) | undefined,
+  finalAnswerRetry: boolean,
+) => Promise<ChildResult>;
 
-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 textResult(text: string, details: Record<string, unknown> = {}): ToolTextResult {
+  return { content: [{ type: "text", text }], details };
 }
 
-/**
- * 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);
+export function formatResearchSubject(query: unknown): string {
+  if (typeof query !== "string") return "context request";
+  return query.replace(/\s+/g, " ").trim() || "context request";
 }
 
-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)" }),
-	),
-});
+function renderContextCall(
+  query: unknown,
+  theme: { fg(color: string, text: string): string; bold(text: string): string },
+): Component {
+  return {
+    render: (width) => {
+      if (width <= 0) return [];
+      const prefix = theme.fg("customMessageLabel", theme.bold("[context]"));
+      const title = `research started · ${formatResearchSubject(query)}`;
+      return new Text(`${prefix} ${title}`, 0, 0).render(width)
+        .map((line) => truncateToWidth(line, width, "")).concat("");
+    },
+    invalidate: () => {},
+  };
+}
 
-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 }),
-	),
-});
+function resultText(result: ToolTextResult): string {
+  return result.content.find((part) => part.type === "text")?.text ?? "";
+}
 
-export function registerContextTools(pi: ExtensionAPI): void {
-	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",
+export function buildResearchPrompt(query: string, finalAnswerRetry = false): string {
+  const prompt = buildContextResearchPrompt({
+    userResearchRequest: query,
+    workingDirectory: process.cwd(),
+  });
+  return finalAnswerRetry ? `${prompt}${FINAL_ANSWER_RETRY_INSTRUCTION}` : prompt;
+}
 
-		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));
-		},
-	});
+/** Minimal structural view of the tool-execution context: only what the research widget needs. */
+export type ResearchWidgetContext = PiLiveWidgetContext;
 
-	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",
+interface ActiveResearch {
+  token: number;
+  ctx: ResearchWidgetContext | undefined;
+  activity?: string;
+}
 
-		async execute(_toolCallId, params, signal) {
-			const headers: Record<string, string> = {};
-			if (process.env.CONTEXT7_API_KEY) {
-				headers.Authorization = `Bearer ${process.env.CONTEXT7_API_KEY}`;
-			}
+let researchToken = 0;
+let activeResearch: ActiveResearch | undefined;
+const researchWidget = createLiveActivityWidget({
+  key: "context-research",
+  placement: "aboveEditor",
+  fit: truncateToWidth,
+  formatIdentity: (identity, theme) => theme.fg("success", theme.bold(identity)),
+  formatActivity: (activity, theme) => new Markdown(
+    activity, 0, 0, getMarkdownTheme(), { color: (text) => theme.fg("accent", text) },
+  ).render(Math.max(1, visibleWidth(activity))).map((line) => line.trim()).filter(Boolean).join(" "),
+});
 
-			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)}`);
-			}
+/** Show the running-research status above the editor; returns a token for updates/clear. */
+export function startResearchWidget(ctx: ResearchWidgetContext | undefined): number {
+  const token = ++researchToken;
+  activeResearch = { token, ctx };
+  researchWidget.update(ctx, [{ id: String(token), identity: "researcher" }]);
+  return token;
+}
 
-			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}"`);
-			}
+/** Refresh the live activity line; stale tokens are ignored. */
+export function updateResearchWidget(token: number, activity: string | undefined): void {
+  if (activeResearch?.token !== token) return;
+  if (activity) activeResearch.activity = activity;
+  researchWidget.update(activeResearch.ctx, [{
+    id: String(token),
+    identity: "researcher",
+    activity: activeResearch.activity,
+  }]);
+}
 
-			// 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)}`,
-			);
-		},
-	});
+/** Remove the status widget; stale tokens are ignored. */
+export function clearResearchWidget(ctx: ResearchWidgetContext | undefined, token: number): void {
+  if (activeResearch?.token !== token) return;
+  activeResearch = undefined;
+  researchWidget.clear(ctx);
+}
 
-	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",
+export function runResearchChild(
+  query: string,
+  signal?: AbortSignal,
+  onUpdate?: (update: PiWorkerProgressUpdate) => void,
+  finalAnswerRetry = false,
+): Promise<ChildResult> {
+  let cancelled = signal?.aborted ?? false;
+  const onAbort = () => { cancelled = true; };
+  if (!signal?.aborted) signal?.addEventListener("abort", onAbort, { once: true });
+  return runPiWorker({
+    prompt: buildResearchPrompt(query, finalAnswerRetry),
+    cwd: process.cwd(),
+    tools: RESEARCH_TOOLS,
+    minimal: true,
+    signal,
+    onUpdate,
+  }).then((result) => {
+    signal?.removeEventListener("abort", onAbort);
+    return { text: result.text.trim(), stderr: result.stderr.trim(), exitCode: result.exitCode, cancelled };
+  });
+}
 
-		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 async function runResearchWithFinalAnswerRetry(
+  query: string,
+  signal?: AbortSignal,
+  onUpdate?: (update: PiWorkerProgressUpdate) => void,
+  runner: ResearchRunner = runResearchChild,
+): Promise<ResearchAttemptResult> {
+  const first = await runner(query, signal, onUpdate, false);
+  if (first.cancelled || first.exitCode !== 0 || first.text) return { ...first, retried: false };
+  const retry = await runner(query, signal, onUpdate, true);
+  return { ...retry, retried: true };
+}
 
-			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 prompt-constrained Pi child process. The child has read and bash available and can inspect or temporarily clone public repositories under /tmp.",
+    promptSnippet: "Research independently in a prompt-constrained Pi child 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 Pi process with a read/bash allowlist and prompt-level no-modification guidance.",
+    ],
+    parameters: ResearchParams,
+    executionMode: "sequential",
+    renderShell: "self",
+    renderCall(args, theme, _context) {
+      return renderContextCall(args.query, theme);
+    },
+    renderResult(result, options, theme, context) {
+      // While the async child is still running, live progress already shows
+      // in the `researcher` widget above the editor, so a partial result
+      // renders no transcript row: the `research started` call row stays the
+      // single visible row until the settled `[context] researched` result.
+      if (options.isPartial) {
+        return { render: () => [] as string[], invalidate: () => {} };
+      }
+      const query = (context.args as { query?: string })?.query;
+      const subject = formatResearchSubject(query);
+      const text = resultText(result as ToolTextResult);
+      const details = text.split("\n").map((line) => line.trim()).filter(Boolean);
+      const spec = eventToolLifecycle("context", subject, {
+        label: "researched",
+        details,
+        detailLimit: "all",
+      });
+      return createStaticToolLifecycleResultRenderer({
+        createSpec: () => spec,
+        expandHint: keyHint("app.tools.expand", "to expand"),
+        fit: truncateToWidth,
+        visibleWidth,
+        wrapDetail: (line, width) => wrapTextWithAnsi(line, Math.max(1, width)),
+      })(result as ToolTextResult, options, theme, context);
+    },
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const widget = startResearchWidget(ctx as ResearchWidgetContext | undefined);
+      try {
+        const child = await runResearchWithFinalAnswerRetry(params.query, signal, (progress) => {
+          updateResearchWidget(widget, progress.activity);
+          onUpdate?.(textResult(progress.activity ?? "Working...", {
+            operation: "context-review",
+          }));
+        });
+        if (child.cancelled) throw new Error("Isolated Pi research was cancelled");
+        if (child.exitCode !== 0) {
+          const phase = child.retried ? " retry" : "";
+          throw new Error(`Isolated Pi research${phase} failed (exit ${child.exitCode}): ${child.stderr.slice(0, 400)}`);
+        }
+        if (!child.text) throw new Error("Isolated Pi research returned no answer after retry");
+        return textResult(child.text, {
+          exitCode: child.exitCode,
+          operation: "context-review",
+          ...(child.retried ? { retried: true } : {}),
+        });
+      } finally {
+        clearResearchWidget(ctx as ResearchWidgetContext | undefined, widget);
+      }
+    },
+  });
 }
 
 export default registerContextTools;

package/index.ts

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

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@fradser/pi-context",
-  "version": "0.5.1",
-  "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.1",
+  "description": "Retrieve context for repositories, libraries, and technical questions with one native tool that launches an isolated prompt-constrained Pi research child.",
   "keywords": [
     "pi-package",
     "code-context",
-    "deepwiki",
-    "context7",
-    "exa"
+    "isolated-research",
+    "prompt-constrained"
   ],
   "author": "Frad LEE <fradser@gmail.com>",
   "license": "MIT",
@@ -22,7 +21,7 @@
     "index.ts",
     "extensions",
     "references",
-    "agents",
+    "prompts",
     "README.md"
   ],
   "pi": {
@@ -31,8 +30,12 @@
     ]
   },
   "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/prompts/context-research.md

@@ -0,0 +1,10 @@
+You are the stateless one-shot research worker bundled with @fradser/pi-context and invoked by its context_get tool.
+
+Research the supplied request independently and return a concise, evidence-based answer. You have read and bash available. Treat the caller's working directory as read-only: never edit or write files. Bash can technically write, so this boundary is enforced by your instructions rather than an OS sandbox.
+
+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:
+{{USER_RESEARCH_REQUEST}}

package/references/workflow.md

@@ -1,108 +1,7 @@
-# context workflow
+# Isolated context research workflow
 
-Retrieve code context for any repo, library, or natural-language code/technology question. Five methods are available; pick them per target. Prefer small intermediate summaries over dumping raw API payloads into the long-lived conversation.
+Use `context_get` for a repository, library, codebase, or technical research request. It launches a stateless one-shot Pi worker so exploratory work and its tool calls do not enter the main session.
 
-## Native tools
+A package-local typed builder reads the bundled Markdown as a reference protocol and constructs a task-specific context-review prompt from the current request and working directory, then adds an explicit completion contract. The transcript identifies that execution with the normalized concrete request (`[context] research started · <research query>`), never with the Markdown path; while the async child runs, no duplicate progress row is rendered and live progress shows only in the researcher widget. The child has a `read,bash` allowlist and no extension discovery. The prompt requires read-only behavior and forbids edits, writes, package-manager commands, deployment, and interactive commands; `bash` can technically write because the child has no OS sandbox. 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.
 
-| Method | Tool | Availability |
-|--------|------|--------------|
-| DeepWiki | `context_deepwiki` | always, no key |
-| Context7 | `context_context7` | always, optional `CONTEXT7_API_KEY` for higher quota |
-| Exa | `context_exa` | requires `EXA_API_KEY` |
-| Git clone | `bash` + `read` | always |
-| Web search+fetch | `bash` + `curl` | always |
-
-If a native tool is unavailable or errors (e.g. `EXA_API_KEY` unset), skip it and use the documented clone/web fallback. Report which methods ran. There are no Pi built-ins named `WebSearch`/`WebFetch`/`Task` — do not invent them.
-
-## Invocation
-
-`/context [targets...] [--method=a,b,...]`
-
-- `--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.
-- No targets: read dependency manifests in cwd (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`) and use detected dependencies as targets.
-
-Classify each target:
-
-- GitHub slug (`owner/repo`) or git URL → repo — DeepWiki (`context_deepwiki`), else clone.
-- Bare package name or `name@version` → library — Context7 (`context_context7`), else web + clone of docs repo when known.
-- Anything else → natural-language — Exa (`context_exa`) when `EXA_API_KEY` is set, else web search via `curl`.
-
-When `--method=` is passed, use the intersection of allowed and applicable methods. Empty intersection → skip and report.
-
-## Method 1: DeepWiki
-
-Best for: public GitHub repos needing an architecture overview quickly.
-
-1. `context_deepwiki` with `owner`/`repo` and `mode: "structure"` (e.g. `facebook` / `react`).
-2. `mode: "contents"` for the full wiki text, or `mode: "ask"` with `question` for targeted Q&A.
-3. Extract architecture summary and key relationships.
-
-Token isolation: structure → relevant pages → short architecture summary.
-Fallback on error: Method 4 (clone) + Method 5 (web) on GitHub docs/README.
-
-## Method 2: Context7
-
-Best for: up-to-date API docs and version-specific examples for packages/frameworks.
-
-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.
-
-Token isolation: resolve id → query → minimum viable API surface + examples.
-Fallback on error: official docs URLs via `curl`, or clone of the library repo docs.
-
-## Method 3: Exa
-
-Best for: real-world usage patterns and cross-web code examples.
-
-1. Call with a precise query (language/framework/version/identifiers).
-2. Prefer recent sources; dedupe near-identical snippets and mirrors.
-3. Return a short explanation with sources.
-
-Fallback when key missing / error: GitHub code search URLs / known docs via `curl`, or clone representative examples.
-
-## Method 4: Git clone
-
-Best for: private repos, deep implementation review, when other methods lack depth.
-
-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.
-4. Cleanup: `rm -rf /tmp/<repo-name>`.
-
-## Method 5: Web search + fetch
-
-Best for: rationale, changelogs, issues, migration guides.
-
-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>"`
-
-## 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.
-5. Return a synthesized summary only — drop raw bulk payloads.
+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/agents/context-researcher.md

@@ -1,36 +0,0 @@
----
-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 (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 the `/context` command 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 `/context`).
-2. **Classify** each target (repo / library / natural-language).
-3. **Select methods** per the `/context` workflow's 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