@zhalker/gentle-shell-codegraph-subagents 0.1.0 → 0.2.0

package/src/prefetch.ts

@@ -1,142 +1,167 @@
-import { spawn } from "node:child_process";
-import { join } from "node:path";
-import { CODEGRAPH_MCP_TOOL } from "./agents.ts";
-
-export const PREFETCH_TIMEOUT_MS = 20_000;
-export const PREFETCH_MAX_CHARS = 12_000;
-export const QUERY_MAX_CHARS = 300;
-const READ_LIMIT_BYTES = 200_000;
-
-const REQUESTED_TOOLS_ENV = "GENTLE_PI_AGENTS_REQUESTED_TOOLS";
-const CHILD_ENV = "GENTLE_PI_AGENTS_CHILD";
-const WRITING_TOOLS = ["bash", "edit", "write", "bash_background"];
-
-/**
- * gentle-pi gives a subagent child no env var with the agent's name, only its tool list.
- * The explorer is the one child that reads only and holds the CodeGraph MCP tool.
- */
-export function isExplorerChild(env: Record<string, string | undefined>): boolean {
-	if (env[CHILD_ENV] !== "1") return false;
-	const tools = (env[REQUESTED_TOOLS_ENV] ?? "").split(",").map((tool) => tool.trim());
-	return tools.includes(CODEGRAPH_MCP_TOOL) && !tools.some((tool) => WRITING_TOOLS.includes(tool));
-}
-
-/**
- * The task text becomes arguments of a command that Windows runs through cmd.exe, so only
- * letters, digits and a few harmless marks survive, and no word can look like an option.
- */
-export function sanitizeQuery(task: string): string {
-	const words = task
-		.replace(/[^\p{L}\p{N}_.,:/-]+/gu, " ")
-		.split(" ")
-		.map((word) => word.replace(/^-+/, ""))
-		.filter((word) => word.length > 0);
-	return words.join(" ").slice(0, QUERY_MAX_CHARS).trim();
-}
-
-export function boundOutput(text: string, max = PREFETCH_MAX_CHARS): string {
-	return text.length <= max ? text : `${text.slice(0, max)}\n\n[truncated: output cut at ${max} characters]`;
-}
-
-export interface RunOptions {
-	command: string;
-	args: string[];
-	cwd: string;
-	timeoutMs: number;
-	maxBytes: number;
-	/** Windows needs a shell to run the .cmd shim that npm installs for codegraph. */
-	shell?: boolean;
-}
-
-function killTree(pid: number | undefined, child: { kill(): boolean }): void {
-	if (process.platform === "win32" && pid !== undefined) {
-		try {
-			spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" }).on("error", () => {});
-			return;
-		} catch { /* fall through */ }
-	}
-	try { child.kill(); } catch { /* already gone */ }
-}
-
-/** Output of a command that exits 0 and prints something; undefined for anything else. Never rejects. */
-export function runCommand(options: RunOptions): Promise<string | undefined> {
-	return new Promise((resolve) => {
-		let settled = false;
-		const finish = (value: string | undefined) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			resolve(value);
-		};
-		let child;
-		try {
-			child = options.shell
-				? spawn([options.command, ...options.args].join(" "), { cwd: options.cwd, shell: true, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] })
-				: spawn(options.command, options.args, { cwd: options.cwd, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
-		} catch {
-			resolve(undefined);
-			return;
-		}
-		const timer = setTimeout(() => {
-			killTree(child.pid, child);
-			finish(undefined);
-		}, options.timeoutMs);
-		const chunks: Buffer[] = [];
-		let size = 0;
-		child.stdout?.on("data", (chunk: Buffer) => {
-			size += chunk.length;
-			if (size > options.maxBytes) {
-				killTree(child.pid, child);
-				finish(Buffer.concat(chunks).toString("utf8").slice(0, options.maxBytes));
-				return;
-			}
-			chunks.push(chunk);
-		});
-		child.on("error", () => finish(undefined));
-		child.on("close", (code) => {
-			const text = Buffer.concat(chunks).toString("utf8");
-			finish(code === 0 && text.trim().length > 0 ? text : undefined);
-		});
-	});
-}
-
-/** The CLI's explore output is the same as the codegraph_explore MCP tool. */
-export function exploreWithCodegraph(query: string, cwd: string): Promise<string | undefined> {
-	const windows = process.platform === "win32";
-	return runCommand({
-		command: "codegraph",
-		args: windows ? ["explore", ...query.split(" ")] : ["explore", query],
-		cwd,
-		timeoutMs: PREFETCH_TIMEOUT_MS,
-		maxBytes: READ_LIMIT_BYTES,
-		shell: windows,
-	});
-}
-
-export interface PrefetchInput {
-	env: Record<string, string | undefined>;
-	prompt: string | undefined;
-	cwd: string;
-	exists(path: string): boolean;
-	explore(query: string, cwd: string): Promise<string | undefined>;
-}
-
-/** Text to hand to the explorer before its first step; undefined means the run goes on untouched. */
-export async function prefetchForExplorer(input: PrefetchInput): Promise<string | undefined> {
-	try {
-		if (!isExplorerChild(input.env) || input.prompt === undefined) return undefined;
-		const query = sanitizeQuery(input.prompt);
-		if (query.length === 0) return undefined;
-		if (!input.exists(join(input.cwd, ".codegraph"))) return undefined;
-		const output = await input.explore(query, input.cwd);
-		if (output === undefined || output.trim().length === 0) return undefined;
-		return [
-			"CodeGraph pre-fetch for your task, run for you before your first step with `codegraph explore` (bounded in size and time).",
-			`Use it as a starting point and call ${CODEGRAPH_MCP_TOOL} when you need more.`,
-			"",
-			boundOutput(output.trim()),
-		].join("\n");
-	} catch {
-		return undefined;
-	}
-}
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { CODEGRAPH_MCP_TOOL } from "./agents.ts";
+import type { DaemonExploreResult } from "./daemonclient.ts";
+
+export const PREFETCH_TIMEOUT_MS = 20_000;
+export const PREFETCH_MAX_CHARS = 12_000;
+export const QUERY_MAX_CHARS = 300;
+const READ_LIMIT_BYTES = 200_000;
+
+const REQUESTED_TOOLS_ENV = "GENTLE_PI_AGENTS_REQUESTED_TOOLS";
+const CHILD_ENV = "GENTLE_PI_AGENTS_CHILD";
+const WRITING_TOOLS = ["bash", "edit", "write", "bash_background"];
+
+/**
+ * gentle-pi gives a subagent child no env var with the agent's name, only its tool list.
+ * The explorer is the one child that reads only and holds the CodeGraph MCP tool.
+ */
+export function isExplorerChild(env: Record<string, string | undefined>): boolean {
+	if (env[CHILD_ENV] !== "1") return false;
+	const tools = (env[REQUESTED_TOOLS_ENV] ?? "").split(",").map((tool) => tool.trim());
+	return tools.includes(CODEGRAPH_MCP_TOOL) && !tools.some((tool) => WRITING_TOOLS.includes(tool));
+}
+
+/**
+ * The task text becomes arguments of a command that Windows runs through cmd.exe, so only
+ * letters, digits and a few harmless marks survive, and no word can look like an option.
+ */
+export function sanitizeQuery(task: string): string {
+	const words = task
+		.replace(/[^\p{L}\p{N}_.,:/-]+/gu, " ")
+		.split(" ")
+		.map((word) => word.replace(/^-+/, ""))
+		.filter((word) => word.length > 0);
+	return words.join(" ").slice(0, QUERY_MAX_CHARS).trim();
+}
+
+export function boundOutput(text: string, max = PREFETCH_MAX_CHARS): string {
+	return text.length <= max ? text : `${text.slice(0, max)}\n\n[truncated: output cut at ${max} characters]`;
+}
+
+export interface RunOptions {
+	command: string;
+	args: string[];
+	cwd: string;
+	timeoutMs: number;
+	maxBytes: number;
+	/** Windows needs a shell to run the .cmd shim that npm installs for codegraph. */
+	shell?: boolean;
+}
+
+export function killTree(pid: number | undefined, child: { kill(): boolean }): void {
+	if (process.platform === "win32" && pid !== undefined) {
+		try {
+			spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" }).on("error", () => {});
+			return;
+		} catch { /* fall through */ }
+	}
+	try { child.kill(); } catch { /* already gone */ }
+}
+
+/** Output of a command that exits 0 and prints something; undefined for anything else. Never rejects. */
+export function runCommand(options: RunOptions): Promise<string | undefined> {
+	return new Promise((resolve) => {
+		let settled = false;
+		const finish = (value: string | undefined) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(value);
+		};
+		let child;
+		try {
+			child = options.shell
+				? spawn([options.command, ...options.args].join(" "), { cwd: options.cwd, shell: true, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] })
+				: spawn(options.command, options.args, { cwd: options.cwd, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+		} catch {
+			resolve(undefined);
+			return;
+		}
+		const timer = setTimeout(() => {
+			killTree(child.pid, child);
+			finish(undefined);
+		}, options.timeoutMs);
+		const chunks: Buffer[] = [];
+		let size = 0;
+		child.stdout?.on("data", (chunk: Buffer) => {
+			size += chunk.length;
+			if (size > options.maxBytes) {
+				killTree(child.pid, child);
+				finish(Buffer.concat(chunks).toString("utf8").slice(0, options.maxBytes));
+				return;
+			}
+			chunks.push(chunk);
+		});
+		child.on("error", () => finish(undefined));
+		child.on("close", (code) => {
+			const text = Buffer.concat(chunks).toString("utf8");
+			finish(code === 0 && text.trim().length > 0 ? text : undefined);
+		});
+	});
+}
+
+/** The CLI's explore output is the same as the codegraph_explore MCP tool. */
+export function exploreWithCodegraph(query: string, cwd: string): Promise<string | undefined> {
+	const windows = process.platform === "win32";
+	return runCommand({
+		command: "codegraph",
+		args: windows ? ["explore", ...query.split(" ")] : ["explore", query],
+		cwd,
+		timeoutMs: PREFETCH_TIMEOUT_MS,
+		maxBytes: READ_LIMIT_BYTES,
+		shell: windows,
+	});
+}
+
+export interface DaemonFirstDeps {
+	daemon(query: string, cwd: string): Promise<DaemonExploreResult>;
+	cli(query: string, cwd: string): Promise<string | undefined>;
+}
+
+/**
+ * Asks the project daemon first; only when there is no usable one does the CLI answer, as it always did.
+ * A daemon that was there but too slow is not retried through the CLI, which would be slower still.
+ */
+export async function exploreDaemonFirst(query: string, cwd: string, deps: DaemonFirstDeps): Promise<string | undefined> {
+	try {
+		const result = await deps.daemon(query, cwd);
+		if (result.status === "ok") return result.text;
+		if (result.status === "timeout") return undefined;
+	} catch {
+		// Anything unexpected in the daemon path means the CLI takes over.
+	}
+	return deps.cli(query, cwd);
+}
+
+export interface PrefetchInput {
+	env: Record<string, string | undefined>;
+	prompt: string | undefined;
+	cwd: string;
+	exists(path: string): boolean;
+	/** Whether another session is creating the index of this cwd; nothing may touch it meanwhile. */
+	initRunning?(cwd: string): boolean;
+	explore(query: string, cwd: string): Promise<string | undefined>;
+}
+
+/** Text to hand to the explorer before its first step; undefined means the run goes on untouched. */
+export async function prefetchForExplorer(input: PrefetchInput): Promise<string | undefined> {
+	try {
+		if (!isExplorerChild(input.env) || input.prompt === undefined) return undefined;
+		const query = sanitizeQuery(input.prompt);
+		if (query.length === 0) return undefined;
+		if (!input.exists(join(input.cwd, ".codegraph"))) return undefined;
+		// A daemon or CLI call while an init builds the index can hang that init for good, so this waits for the next run.
+		if (input.initRunning?.(input.cwd)) return undefined;
+		const output = await input.explore(query, input.cwd);
+		if (output === undefined || output.trim().length === 0) return undefined;
+		return [
+			"CodeGraph pre-fetch for your task, run for you before your first step with `codegraph explore` (bounded in size and time).",
+			`Use it as a starting point and call ${CODEGRAPH_MCP_TOOL} when you need more.`,
+			"",
+			boundOutput(output.trim()),
+		].join("\n");
+	} catch {
+		return undefined;
+	}
+}

package/src/skill-reminder.ts

@@ -0,0 +1,33 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const WORKER_MARKER = "<!-- codegraph-workflow:worker -->";
+export const SKILL_REMINDER_TYPE = "codegraph-workflow-reminder";
+
+interface LoadedSkill {
+	name: string;
+	filePath: string;
+	disableModelInvocation?: boolean;
+}
+
+function normalizedPath(path: string): string {
+	let result: string;
+	try { result = realpathSync(path); } catch { result = resolve(path); }
+	return process.platform === "win32" ? result.toLowerCase() : result;
+}
+
+/** Only refer to the packaged skill when Pi actually selected it, not a same-named user skill. */
+export function chooseSkillReminder(input: {
+	expectedPath: string;
+	skills: LoadedSkill[];
+	child: boolean;
+	systemPrompt: string;
+	alreadySent: boolean;
+	isUserPrompt: boolean;
+}): string | undefined {
+	if (!input.isUserPrompt || input.alreadySent) return undefined;
+	if (input.child && !input.systemPrompt.includes(WORKER_MARKER)) return undefined;
+	const skill = input.skills.find((entry) => entry.name === "codegraph-workflow");
+	if (!skill || skill.disableModelInvocation || normalizedPath(skill.filePath) !== normalizedPath(input.expectedPath)) return undefined;
+	return `For applicable code tasks, read and follow the codegraph-workflow skill at ${skill.filePath}.`;
+}

package/src/warmup.ts

@@ -0,0 +1,86 @@
+import { spawn } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { NO_PROJECT_TEXT } from "./daemonclient.ts";
+
+/** A cold daemon on a network share can need over a minute for its first read. */
+export const WARMUP_TIMEOUT_MS = 120_000;
+/** Any query works: the point is that a read call makes the daemon open its database and start a worker. */
+export const WARMUP_QUERY = "main";
+/** The command line the warm-up runs; only tests ask for another one. */
+export const WARMUP_COMMAND = "codegraph serve --mcp";
+
+export interface ExploreOnceResult {
+	/** The server answered the explore call without an error. */
+	ok: boolean;
+	/** How long the explore call alone took. */
+	exploreMs: number;
+}
+
+/**
+ * Talks MCP to `codegraph serve --mcp` in `cwd`: initialize, one `codegraph_explore`, then closes stdin and
+ * lets the server go on its own. The project daemon is shared with the user's own sessions, so this never
+ * kills the process tree (that would take the daemon with it) and gives up waiting instead; it releases the
+ * server's stdout so a server that never leaves cannot keep the process alive. Never rejects.
+ */
+export function exploreOnce(cwd: string, query: string, timeoutMs: number, command: string = WARMUP_COMMAND): Promise<ExploreOnceResult> {
+	return new Promise((resolve) => {
+		let settled = false;
+		let exploreStart = 0;
+		const finish = (ok: boolean) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			try { child?.stdin?.end(); } catch { /* already closed */ }
+			// The server may never leave on its own: its piped stdout would keep the event loop of Pi alive.
+			try { child?.stdout?.destroy(); } catch { /* already gone */ }
+			child?.unref();
+			resolve({ ok, exploreMs: exploreStart === 0 ? 0 : Date.now() - exploreStart });
+		};
+		let child: ReturnType<typeof spawn> | undefined;
+		const timer = setTimeout(() => finish(false), timeoutMs);
+		try {
+			// Windows needs a shell for the .cmd shim; the default command line is fixed and nothing user-controlled goes into it.
+			child = spawn(command, { cwd, shell: true, windowsHide: true, stdio: ["pipe", "pipe", "ignore"] });
+		} catch {
+			finish(false);
+			return;
+		}
+		const send = (message: object) => child?.stdin?.write(JSON.stringify(message) + "\n");
+		let buffer = "";
+		child.stdout?.on("data", (chunk: Buffer) => {
+			buffer += chunk.toString("utf8");
+			let newline: number;
+			while ((newline = buffer.indexOf("\n")) >= 0) {
+				const line = buffer.slice(0, newline).trim();
+				buffer = buffer.slice(newline + 1);
+				if (line.length === 0) continue;
+				let message: { id?: number; error?: unknown; result?: { isError?: boolean; content?: { text?: string }[] } };
+				try { message = JSON.parse(line); } catch { continue; }
+				if (message.id === 1) {
+					send({ jsonrpc: "2.0", method: "notifications/initialized" });
+					exploreStart = Date.now();
+					send({ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "codegraph_explore", arguments: { query } } });
+				} else if (message.id === 2) {
+					// CodeGraph reports a crashed query worker with isError and a text, not with a JSON-RPC error.
+					const text = message.result?.content?.[0]?.text;
+					const failed = message.error !== undefined || message.result?.isError === true;
+					finish(!failed && typeof text === "string" && !text.startsWith(NO_PROJECT_TEXT));
+				}
+			}
+		});
+		child.on("error", () => finish(false));
+		child.on("close", () => finish(false));
+		child.stdin?.on("error", () => { /* the server exited first */ });
+		send({
+			jsonrpc: "2.0",
+			id: 1,
+			method: "initialize",
+			params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "gentle-shell-codegraph-subagents", version: "0" }, rootUri: pathToFileURL(cwd).href },
+		});
+	});
+}
+
+/** Makes the project's CodeGraph daemon open its database and start a read worker, so the next real call is fast. */
+export async function warmUpDaemon(cwd: string, timeoutMs: number = WARMUP_TIMEOUT_MS): Promise<boolean> {
+	return (await exploreOnce(cwd, WARMUP_QUERY, timeoutMs)).ok;
+}