@juanhuttemann/pi-deep-research 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Huttemann
+
+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

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# @juanhuttemann/pi-deep-research
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fact-checked, cited web research inside [Pi](https://pi.dev). The extension
+runs [deep-research](https://github.com/juanhuttemann/deep-research)
+(`drsh`): it plans sub-topics, searches them in parallel, analyzes the
+evidence, and checks every claim against the text of the pages it fetched.
+Pi's own model answers the model calls, through Pi's sign-in.
+
+![A deep_research run in Pi: sub-agents searching, with the pages and sources so far](https://raw.githubusercontent.com/juanhuttemann/deep-research/main/docs/images/pi-research.png)
+
+## Install
+
+`drsh` must be installed (0.30.0 or newer):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/juanhuttemann/deep-research/main/scripts/install.sh | bash
+```
+
+Then:
+
+```sh
+pi install npm:@juanhuttemann/pi-deep-research
+```
+
+From a clone, `pi install ./integrations/pi`. For one session,
+`pi -e ./integrations/pi/src/index.ts`.
+
+drsh's search and scraper settings still apply. SearXNG works with no
+setup, while Exa, Tavily and Firecrawl use their keys from `drsh setup`.
+`/research-doctor` checks them.
+
+## What it adds
+
+- **`deep_research` tool.** Ask Pi to research something.
+  - While the run goes, the call shows the phase, each sub-agent, the
+    searches, pages and sources so far, and the model's reasoning.
+  - When it ends, the call shows the confidence, the fact-check's verdicts,
+    the claims it did not confirm, and the report's path.
+  - Esc stops a run. It keeps a checkpoint, and resuming from it skips the
+    searches already done.
+  - When the question leaves something open, the clarifying questions open
+    as Pi dialogs. In print or JSON mode they go back to the model, which
+    asks you.
+  - Every run setting drsh has is a tool parameter: depth (instant, quick,
+    standard, deep), sub-topics, pages per topic, follow-ups, format,
+    words, tables and clarify. `domains`, `trace` and `review_plan`
+    (review and edit the plan before any search) are parameters too. The
+    settings come from `drsh settings`, so a new setting in drsh appears
+    here with no update.
+- **`research_ask` tool.** Answers a follow-up question from the pages a
+  run already fetched, without searching again. The answer is not
+  fact-checked.
+- **`/research [--topics 3 --follow-ups off --domains a,b …] question`**
+  runs a research yourself.
+  - With no flags it opens the settings screen first.
+  - You answer the clarifying questions and review the plan, then the run
+    starts and the agent reports what it found.
+  - `/research-stop` ends the run.
+- **`/research-model`** picks the model research runs use:
+  - Pi's current model, the default.
+  - Another of Pi's models, for example a cheaper one for the many calls a
+    run makes.
+  - drsh's own configured model.
+- **`/research-doctor`** checks the model (through Pi), search and the
+  scraper.
+
+Each run's files (`.md`, `.pdf`, `.json`, checkpoint) go in
+`~/.cache/deep-research-pi/runs/` (`$DEEP_RESEARCH_PI_RUNS` to change it),
+never into your project. `DRSH_BIN` points to a `drsh` that is not on
+`PATH`.
+
+## How the model is reached
+
+For each call, the extension starts an HTTP endpoint on `127.0.0.1` that
+speaks the OpenAI chat-completions API. The endpoint accepts only a random
+token, given to drsh as its API key, and closes when the call ends.
+
+drsh runs with `OPENAI_BASE_URL` pointed at that endpoint, and each request
+it sends is answered by `ctx.modelRegistry.streamSimple`. Streamed
+reasoning, JSON mode, tool calls (for `research_ask`) and usage all pass
+through. The run's usage is added to the tool result, so Pi's session
+totals count it.
+
+## Development
+
+```sh
+npm ci
+npm run typecheck
+DRSH_BIN=/path/to/drsh npm test   # bridge tests run that drsh offline
+```
+
+From the repo root, `make pi` builds drsh from the tree and runs all three.

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@juanhuttemann/pi-deep-research",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Fact-checked, cited web research inside Pi: runs the deep-research CLI (drsh) on Pi's own model, with live progress, clarifying questions and plan review",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "research",
+    "web-search",
+    "fact-check",
+    "citations"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/juanhuttemann/deep-research/tree/main/integrations/pi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juanhuttemann/deep-research.git",
+    "directory": "integrations/pi"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/juanhuttemann/deep-research/main/docs/images/pi-research.png"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import jiti/register --test --test-reporter=spec \"test/*.test.ts\""
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "1.4.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
+    "@types/node": "^22.19.0",
+    "jiti": "2.7.0",
+    "typebox": "1.3.27",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/args.ts

@@ -0,0 +1,81 @@
+// The drsh command lines a research call runs. The mutual exclusions are the
+// CLI's (internal/cli/cli.go): --resume and --plan carry their own question
+// and settings, so they take none of the others.
+
+import { settingArg, type Setting } from "./settings.ts";
+import type { Question } from "./events.ts";
+
+export interface Answer {
+	question: string;
+	answer: string;
+}
+
+// Clarified is the --answers JSON: the questions asked and the reader's
+// answers, as ui.ParseAnswers reads it.
+export interface Clarified {
+	questions: Question[];
+	answers: Answer[];
+}
+
+export interface NewRun {
+	question: string;
+	values: Record<string, string>;
+	domains?: string[];
+	answers?: Clarified;
+	trace?: boolean;
+}
+
+export type Stage = "clarify" | "plan" | "run";
+
+function common(reports: string): string[] {
+	return ["--jsonl", `--reports=${reports}`];
+}
+
+function settingArgs(settings: Setting[], values: Record<string, string>): string[] {
+	const out: string[] = [];
+	for (const s of settings) {
+		const v = values[s.key];
+		if (v !== undefined) {
+			out.push(settingArg(s, v));
+		}
+	}
+	for (const k of Object.keys(values)) {
+		if (!settings.some((s) => s.key === k)) {
+			throw new Error(`unknown setting ${JSON.stringify(k)}`);
+		}
+	}
+	return out;
+}
+
+// newRunArgs is a question's command line at one stage: the clarifying
+// questions only, the plan only, or the whole run.
+export function newRunArgs(settings: Setting[], r: NewRun, reports: string, stage: Stage): string[] {
+	// --prompt=: a question that starts with "-" is still the value.
+	const args = [...common(reports), `--prompt=${r.question}`, ...settingArgs(settings, r.values)];
+	if (r.domains?.length) {
+		args.push(`--domains=${r.domains.join(",")}`);
+	}
+	if (stage === "clarify") {
+		args.push("--clarify-only");
+		return args;
+	}
+	if (r.answers) {
+		args.push(`--answers=${JSON.stringify(r.answers)}`);
+	}
+	if (stage === "plan") {
+		args.push("--plan-only");
+	} else if (r.trace) {
+		args.push("--trace");
+	}
+	return args;
+}
+
+// planRunArgs runs a plan written by --plan-only, edited or not.
+export function planRunArgs(planFile: string, reports: string, trace?: boolean): string[] {
+	return [...common(reports), `--plan=${planFile}`, ...(trace ? ["--trace"] : [])];
+}
+
+// resumeArgs continues a run from its checkpoint.
+export function resumeArgs(checkpoint: string, reports: string): string[] {
+	return [...common(reports), `--resume=${checkpoint}`];
+}

package/src/bridge.ts

@@ -0,0 +1,210 @@
+// The local endpoint drsh calls instead of a provider: OpenAI's chat
+// completions over HTTP on 127.0.0.1, answered by Pi's own model layer with
+// Pi's sign-in. drsh needs no model setup of its own, any provider Pi
+// reaches works (OAuth subscriptions included), and the run's usage is
+// counted in Pi's session.
+//
+// One bridge serves one drsh process. It listens on a random loopback port
+// and answers only requests carrying its random token, which drsh is given
+// as its API key.
+
+import { randomBytes } from "node:crypto";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { Api, AssistantMessageEvent, Context, Model, SimpleStreamOptions, Usage } from "@earendil-works/pi-ai";
+import {
+	addUsage,
+	completion,
+	errorBody,
+	errorStatus,
+	streamChunks,
+	toContext,
+	withJSONMode,
+	zeroUsage,
+	type ChatRequest,
+	type StreamState,
+} from "./openai-map.ts";
+
+// StreamFn is ctx.modelRegistry.streamSimple: a provider-neutral call with
+// auth resolved by Pi.
+export type StreamFn = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AsyncIterable<AssistantMessageEvent>;
+
+export interface Bridge {
+	// baseURL is what drsh takes as OPENAI_BASE_URL.
+	baseURL: string;
+	token: string;
+	// modelName is what drsh takes as OPENAI_MODEL and what each answer
+	// names as the model that served it.
+	modelName: string;
+	usage: Usage;
+	calls: number;
+	// env is drsh's environment for the bridge: the endpoint, the token as
+	// its key, the model, and the OpenAI-compatible transport over whatever
+	// provider the user saved with drsh setup.
+	env: Record<string, string>;
+	close(): Promise<void>;
+}
+
+// maxBody bounds a request body. drsh's largest prompt (the fact-check with
+// every quoted page) is a few MB.
+const maxBody = 64 << 20;
+
+function sendJSON(res: ServerResponse, status: number, body: unknown): void {
+	res.writeHead(status, { "content-type": "application/json" });
+	res.end(JSON.stringify(body));
+}
+
+// fail reports a failed call: with its status before anything streamed, else
+// as an error event. openai-go ends a stream that closes without [DONE] as
+// a success, so an answer cut off by a provider failure would otherwise
+// reach drsh as a complete, truncated one.
+function fail(res: ServerResponse, message: string, status: number): void {
+	if (!res.headersSent) {
+		sendJSON(res, status, errorBody(message, status));
+		return;
+	}
+	res.end(`data: ${JSON.stringify(errorBody(message, status))}\n\n`);
+}
+
+async function readBody(req: IncomingMessage): Promise<string> {
+	const parts: Buffer[] = [];
+	let n = 0;
+	for await (const c of req) {
+		n += (c as Buffer).length;
+		if (n > maxBody) throw new Error("request body too large");
+		parts.push(c as Buffer);
+	}
+	return Buffer.concat(parts).toString("utf8");
+}
+
+export async function startBridge(o: { model: Model<Api>; stream: StreamFn; signal?: AbortSignal }): Promise<Bridge> {
+	const token = randomBytes(24).toString("hex");
+	const modelName = `${o.model.provider}/${o.model.id}`;
+	const usage = zeroUsage();
+	const bridge = { token, modelName, usage, calls: 0 } as Bridge;
+
+	const chat = async (req: IncomingMessage, res: ServerResponse) => {
+		let body: ChatRequest;
+		try {
+			body = JSON.parse(await readBody(req)) as ChatRequest;
+		} catch (err) {
+			sendJSON(res, 400, errorBody(`bad request: ${(err as Error).message}`, 400));
+			return;
+		}
+		const { context, options } = toContext(body, o.model);
+		const abort = new AbortController();
+		// The client hanging up (drsh's per-call timeout, or the run
+		// cancelled) ends the provider call too.
+		res.on("close", () => {
+			if (!res.writableFinished) abort.abort();
+		});
+		const outer = () => abort.abort();
+		o.signal?.addEventListener("abort", outer, { once: true });
+		bridge.calls++;
+		const stream = o.stream(o.model, context, {
+			signal: abort.signal,
+			reasoning: options.reasoning,
+			toolChoice: options.toolChoice,
+			maxTokens: options.maxTokens,
+			temperature: options.temperature,
+			onPayload: options.json ? (p, m) => withJSONMode(p, m) : undefined,
+		});
+		const state: StreamState = {
+			id: `chatcmpl-${randomBytes(8).toString("hex")}`,
+			model: modelName,
+			created: Math.floor(Date.now() / 1000),
+			toolIndex: 0,
+			includeUsage: body.stream_options?.include_usage === true,
+		};
+		try {
+			const final = body.stream ? await streamTo(res, stream, state) : await collect(stream);
+			if (final?.type === "error") {
+				const msg = final.error.errorMessage || final.reason;
+				fail(res, msg, errorStatus(msg));
+				return;
+			}
+			if (final?.type === "done") {
+				addUsage(usage, final.message.usage);
+				if (!body.stream) sendJSON(res, 200, completion(final.message, state.id, modelName));
+			}
+			// A stream that stopped with neither an answer nor a failure
+			// still has to end, or drsh waits out its timeout on it.
+			if (!res.writableEnded) fail(res, "the model ended without an answer", 502);
+		} finally {
+			o.signal?.removeEventListener("abort", outer);
+		}
+	};
+
+	const server = createServer((req, res) => {
+		if (req.headers.authorization !== `Bearer ${token}`) {
+			sendJSON(res, 401, errorBody("this endpoint serves only the drsh run it was started for", 401));
+			return;
+		}
+		const path = (req.url ?? "").split("?")[0].replace(/\/+$/, "");
+		if (req.method === "GET" && (path === "/v1/models" || path === "/models")) {
+			sendJSON(res, 200, { object: "list", data: [{ id: modelName, object: "model", owned_by: o.model.provider }] });
+			return;
+		}
+		if (req.method === "POST" && (path === "/v1/chat/completions" || path === "/chat/completions")) {
+			chat(req, res).catch((err: Error) => {
+				if (!res.writableEnded) fail(res, err.message, errorStatus(err.message));
+			});
+			return;
+		}
+		sendJSON(res, 404, errorBody(`no route ${req.method} ${path}`, 404));
+	});
+	await new Promise<void>((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", () => resolve());
+	});
+	const { port } = server.address() as AddressInfo;
+	bridge.baseURL = `http://127.0.0.1:${port}/v1`;
+	bridge.env = {
+		OPENAI_BASE_URL: bridge.baseURL,
+		OPENAI_API_KEY: token,
+		OPENAI_MODEL: modelName,
+		DEEP_RESEARCH_PROVIDER: "openai",
+	};
+	bridge.close = () =>
+		new Promise<void>((resolve) => {
+			server.closeAllConnections();
+			server.close(() => resolve());
+		});
+	return bridge;
+}
+
+type Final = Extract<AssistantMessageEvent, { type: "done" } | { type: "error" }>;
+
+async function collect(stream: AsyncIterable<AssistantMessageEvent>): Promise<Final | undefined> {
+	let final: Final | undefined;
+	for await (const e of stream) {
+		if (e.type === "done" || e.type === "error") final = e;
+	}
+	return final;
+}
+
+// streamTo writes the answer as server-sent events. Headers wait for the
+// first event that is not a failure: a provider that refuses the call
+// (a bad key, a rate limit) does so before anything streams, and is then
+// answered with the status drsh's retry logic reads.
+async function streamTo(res: ServerResponse, stream: AsyncIterable<AssistantMessageEvent>, s: StreamState): Promise<Final | undefined> {
+	let final: Final | undefined;
+	for await (const e of stream) {
+		if (e.type === "error") {
+			final = e;
+			break;
+		}
+		if (!res.headersSent) {
+			res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" });
+		}
+		for (const c of streamChunks(s, e)) {
+			res.write(`data: ${JSON.stringify(c)}\n\n`);
+		}
+		if (e.type === "done") {
+			final = e;
+			res.end("data: [DONE]\n\n");
+		}
+	}
+	return final;
+}
+

package/src/events.ts

@@ -0,0 +1,171 @@
+// The --jsonl event stream drsh writes, and the run state the progress view
+// is drawn from. The field names mirror ui.Event in internal/ui/events.go; a
+// Go test decodes test/fixtures/*.jsonl into that struct with unknown fields
+// refused, so a renamed field fails there before it silently reads as empty
+// here.
+
+export interface Question {
+	id: string;
+	text: string;
+	options?: string[];
+}
+
+export interface DomainCheck {
+	domain: string;
+	status: string;
+	pages?: number;
+	detail?: string;
+}
+
+export interface DrshEvent {
+	type: string;
+	time?: string;
+	phase?: string;
+	detail?: string;
+	query?: string;
+	terms?: string[];
+	url?: string;
+	domain?: string;
+	source_title?: string;
+	source_url?: string;
+	status?: string;
+	code?: string;
+	tokens?: number;
+	sources?: number;
+	sub_id?: string;
+	sub_name?: string;
+	sub_state?: string;
+	progress?: number;
+	line?: string;
+	part?: string;
+	transient?: boolean;
+	artifacts?: string[];
+	checkpoint?: string;
+	plan?: unknown;
+	questions?: Question[];
+	check?: DomainCheck;
+}
+
+export interface SubAgent {
+	id: string;
+	name: string;
+	state: string;
+	progress: number;
+	line: string;
+}
+
+// RunState is what the live view shows. It is a tool result's details, so it
+// holds plain JSON only.
+export interface RunState {
+	phase: string;
+	phaseDetail: string;
+	subagents: SubAgent[];
+	searches: number;
+	reads: number;
+	sources: number;
+	tokens: number;
+	// status is the latest transient line: which model is asked, a retry.
+	status: string;
+	// thinking is the tail of the reasoning streaming now, for a model that
+	// thinks for minutes before its first word.
+	thinking: string;
+	errors: string[];
+	domains: DomainCheck[];
+}
+
+export function initialState(): RunState {
+	return {
+		phase: "",
+		phaseDetail: "",
+		subagents: [],
+		searches: 0,
+		reads: 0,
+		sources: 0,
+		tokens: 0,
+		status: "",
+		thinking: "",
+		errors: [],
+		domains: [],
+	};
+}
+
+// thinkingTail bounds the reasoning kept: the view shows a line or two of it.
+const thinkingTail = 240;
+
+// maxErrors bounds the non-fatal errors kept for the view; the full list is
+// in the run's timeline.
+const maxErrors = 5;
+
+export function parseLine(line: string): DrshEvent | undefined {
+	const s = line.trim();
+	if (!s.startsWith("{")) {
+		return undefined;
+	}
+	try {
+		const e = JSON.parse(s) as DrshEvent;
+		return typeof e.type === "string" ? e : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function subagent(s: RunState, e: DrshEvent): void {
+	if (!e.sub_id) {
+		return;
+	}
+	let a = s.subagents.find((x) => x.id === e.sub_id);
+	if (!a) {
+		a = { id: e.sub_id, name: e.sub_name ?? e.sub_id, state: "queued", progress: 0, line: "" };
+		s.subagents.push(a);
+	}
+	if (e.sub_name) a.name = e.sub_name;
+	if (e.sub_state) a.state = e.sub_state;
+	if (e.progress) a.progress = e.progress;
+	if (e.line) a.line = e.line;
+}
+
+// reduce folds one event into the state, in place, and returns it.
+export function reduce(s: RunState, e: DrshEvent): RunState {
+	switch (e.type) {
+		case "phase":
+			s.phase = e.phase ?? s.phase;
+			s.phaseDetail = e.detail ?? "";
+			s.thinking = "";
+			break;
+		case "subagent":
+			subagent(s, e);
+			break;
+		case "search":
+			s.searches++;
+			subagent(s, e);
+			break;
+		case "read":
+			s.reads++;
+			break;
+		case "report":
+			s.phase = e.phase || "Report";
+			s.phaseDetail = e.detail ?? "";
+			s.thinking = "";
+			if (e.sources) s.sources = e.sources;
+			break;
+		case "citation":
+		case "token":
+			if (e.sources) s.sources = e.sources;
+			if (e.tokens) s.tokens = e.tokens;
+			break;
+		case "info":
+			if (e.transient && e.detail) s.status = e.detail.split("\n")[0];
+			break;
+		case "thinking":
+			s.thinking = (e.status === "start" ? "" : s.thinking) + (e.detail ?? "");
+			s.thinking = s.thinking.slice(-thinkingTail);
+			break;
+		case "error":
+			if (e.detail) s.errors = [...s.errors, e.detail].slice(-maxErrors);
+			break;
+		case "source":
+			if (e.check) s.domains.push(e.check);
+			break;
+	}
+	return s;
+}