@juanhuttemann/pi-deep-research 0.1.0 → 0.1.2

package/README.md

@@ -6,6 +6,8 @@ runs [deep-research](https://github.com/juanhuttemann/deep-research)
 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):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juanhuttemann/pi-deep-research",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -26,7 +26,8 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/juanhuttemann/deep-research/main/docs/images/pi-research.png"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/index.ts

@@ -120,7 +120,10 @@ export default function deepResearch(pi: ExtensionAPI) {
 	let settings: Setting[] = [];
 	let loadError = "";
 	let choice: ModelChoice = { kind: "pi" };
-	let lastRun: RunRecord | undefined;
+	// lastReport is the last run that wrote a .json, what research_ask reads
+	// by default: a run stopped or failed after it leaves none, and must not
+	// hide the one before.
+	let lastReport: RunRecord | undefined;
 	let commandRun: AbortController | undefined;
 
 	async function loadSettings(): Promise<Setting[]> {
@@ -132,6 +135,10 @@ export default function deepResearch(pi: ExtensionAPI) {
 			}
 			settings = parseSettings(r.stdout);
 			loadError = "";
+			// Wherever drsh first answers (the session's start, /research,
+			// /research-doctor, the stand-in), the real tools replace the
+			// stand-in: drsh installed mid-session is usable from then on.
+			registerTools(settings);
 		} catch (err) {
 			const e = err as NodeJS.ErrnoException;
 			loadError = e.code === "ENOENT" ? `drsh was not found (${bin}).\n${installHelp}` : e.message;
@@ -189,7 +196,7 @@ export default function deepResearch(pi: ExtensionAPI) {
 
 	function remember(rec: RunRecord | undefined): void {
 		if (!rec) return;
-		lastRun = rec;
+		if (rec.json) lastReport = rec;
 		pi.appendEntry(runEntry, rec);
 	}
 
@@ -388,9 +395,9 @@ export default function deepResearch(pi: ExtensionAPI) {
 				model: Type.Optional(Type.String({ description: "provider/id of a Pi model to answer with; default as for deep_research." })),
 			}),
 			async execute(_id, params, signal, _onUpdate, ctx) {
-				const runFile = params.run || lastRun?.json;
+				const runFile = params.run || lastReport?.json;
 				if (!runFile) {
-					throw new Error("no research run in this session yet: pass run with a run's .json path, or run deep_research first");
+					throw new Error("no research run in this session has written a report yet: pass run with a run's .json path, or run deep_research first");
 				}
 				const { model, label } = resolveModel(ctx, params.model);
 				const { value: r, bridge } = await withEndpoint(ctx, model, signal, (env) =>
@@ -422,8 +429,7 @@ export default function deepResearch(pi: ExtensionAPI) {
 			description: "Fact-checked, cited web research with the deep-research CLI (drsh). Unavailable until drsh is installed.",
 			parameters: Type.Object({ question: Type.Optional(Type.String()) }),
 			async execute() {
-				const s = await loadSettings();
-				registerTools(s);
+				await loadSettings();
 				throw new Error("drsh is available now; call deep_research again");
 			},
 		});
@@ -431,14 +437,14 @@ export default function deepResearch(pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		choice = { kind: "pi" };
-		lastRun = undefined;
+		lastReport = undefined;
 		for (const e of ctx.sessionManager.getBranch()) {
 			if (e.type !== "custom") continue;
 			if (e.customType === modelEntry && e.data) choice = e.data as ModelChoice;
-			if (e.customType === runEntry && e.data) lastRun = e.data as RunRecord;
+			if (e.customType === runEntry && (e.data as RunRecord | undefined)?.json) lastReport = e.data as RunRecord;
 		}
 		try {
-			registerTools(await loadSettings());
+			await loadSettings();
 		} catch {
 			registerStandIn();
 		}
@@ -581,6 +587,10 @@ export default function deepResearch(pi: ExtensionAPI) {
 				return;
 			}
 			ctx.ui.setStatus("deep-research", "checking drsh…");
+			// The check a user runs after installing drsh: loading its settings
+			// brings in the real tools. A drsh that cannot load them is
+			// reported by the doctor run below.
+			await ensureSettings().catch(() => undefined);
 			try {
 				const { value: r } = await withEndpoint(ctx, model, undefined, (env) => runPlain(bin, ["doctor"], { env }));
 				const verdict = r.code === 0 ? "drsh doctor: ready" : "drsh doctor: something is broken (✗ lines)";

package/src/research.ts

@@ -4,7 +4,7 @@
 // to ask (clarify off, instant), so this knows no setting by name.
 
 import { existsSync } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { newRunArgs, planRunArgs, resumeArgs, type Answer, type NewRun } from "./args.ts";
 import { initialState, reduce, type Question } from "./events.ts";
@@ -150,14 +150,46 @@ async function readJSON(path: string | undefined): Promise<unknown> {
 	}
 }
 
+// checkpointLeft is the checkpoint a run that ended with no done line left
+// on disk. drsh saves it after each step, as <reports>/*.partial.json, and
+// names it only in the done line, which a killed run never writes: on
+// Windows, where stopping a child process kills it outright, that is every
+// stopped run. Each run has a reports directory of its own, so a checkpoint
+// there is this run's; a resumed run saves to the checkpoint it resumed. A
+// file that is not one drsh can resume from (no question or no plan, as
+// replay.Load refuses) is not offered.
+async function checkpointLeft(c: Call): Promise<string | undefined> {
+	let candidates: string[];
+	if (c.req.kind === "resume") {
+		candidates = [c.req.checkpoint];
+	} else {
+		const names = await readdir(c.reports).catch(() => [] as string[]);
+		candidates = names.filter((n) => n.endsWith(".partial.json")).map((n) => join(c.reports, n));
+	}
+	const valid: { path: string; mtime: number }[] = [];
+	for (const path of candidates) {
+		if (resumable(await readJSON(path))) {
+			valid.push({ path, mtime: (await stat(path)).mtimeMs });
+		}
+	}
+	return valid.sort((a, b) => b.mtime - a.mtime)[0]?.path;
+}
+
+function resumable(raw: unknown): boolean {
+	const t = raw as { question?: unknown; plan?: unknown } | null | undefined;
+	return typeof t?.question === "string" && t.question.trim() !== "" && Array.isArray(t.plan) && t.plan.length > 0;
+}
+
 // outcome reads what a run's done line says it wrote.
-async function outcome(r: JsonlResult, model?: string): Promise<{ o: Outcome; isError: boolean }> {
+async function outcome(c: Call, r: JsonlResult): Promise<{ o: Outcome; isError: boolean }> {
+	const model = c.model;
 	if (!r.done) {
 		const status = r.aborted ? "cancelled" : "failed";
 		const detail = r.aborted
 			? "the run was stopped before it could end cleanly"
 			: `drsh exited (code ${r.code}) without a done line, so it was killed or crashed${r.stderr ? `: ${r.stderr.trim().slice(-1500)}` : ""}`;
-		return { o: { status, detail, artifacts: [], model }, isError: !r.aborted };
+		const checkpoint = await checkpointLeft(c);
+		return { o: { status, detail, artifacts: [], model, checkpoint }, isError: !r.aborted };
 	}
 	const artifacts = r.done.artifacts ?? [];
 	const md = artifacts.find((p) => p.endsWith(".md"));
@@ -210,6 +242,6 @@ export async function research(c: Call): Promise<Result> {
 	details.state = initialState();
 	c.hooks.update(details);
 	const r = await stage(c, details, args);
-	const { o, isError } = await outcome(r, c.model);
+	const { o, isError } = await outcome(c, r);
 	return { text: content(o), isError, ...finish(details, o, details.question) };
 }

package/src/settings.ts

@@ -144,7 +144,10 @@ export function parseCommandArgs(settings: Setting[], input: string): CommandArg
 			rest.push(w);
 			continue;
 		}
-		let [name, v] = w.slice(2).split("=", 2) as [string, string | undefined];
+		// Split at the first "=" only: a value may hold one.
+		const eq = w.indexOf("=");
+		const name = eq < 0 ? w.slice(2) : w.slice(2, eq);
+		let v: string | undefined = eq < 0 ? undefined : w.slice(eq + 1);
 		if (v === undefined) {
 			v = words[++i];
 			if (v === undefined) {
@@ -175,7 +178,8 @@ export interface Completion {
 	description?: string;
 }
 
-// completions offers the option names, then a named option's choices.
+// completions offers the option names, then a named option's choices; an
+// option is named by its key or its CLI flag, as parseCommandArgs reads it.
 export function completions(settings: Setting[], prefix: string): Completion[] {
 	const words = prefix.split(/\s+/);
 	const last = words[words.length - 1] ?? "";
@@ -183,7 +187,7 @@ export function completions(settings: Setting[], prefix: string): Completion[] {
 	const head = before ? `${before} ` : "";
 	const prev = words[words.length - 2] ?? "";
 	if (prev.startsWith("--")) {
-		const s = settings.find((x) => x.key === prev.slice(2));
+		const s = settings.find((x) => x.key === prev.slice(2) || x.flag === prev.slice(2));
 		if (s) {
 			return s.choices
 				.filter((o) => o.label.startsWith(last))