@zhalker/gentle-shell-codegraph-subagents 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhalker
+
+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,46 @@
-# Temporary Holding Version
+# @zhalker/gentle-shell-codegraph-subagents
 
-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.
+Pi package that keeps CodeGraph reachable from gentle-shell subagents. On every session start it checks the global agent definitions and `mcp.json` and fixes what gentle-ai or the gentle-pi package left behind. Nothing is rewritten when everything is already right.
+
+> **This package edits files in your Pi configuration.** On every session start it rewrites the agent definitions in `~/.pi/agent/agents/` and `~/.pi/agent/subagents/` and the `codegraph` entry in `~/.pi/agent/mcp.json`. It keeps a one-time backup of each file it changes as `<file>.pre-codegraph-subagents.bak`. Read "What it does" before installing, and see "Uninstall" to go back.
+
+Upstream issue: Gentleman-Programming/gentle-shell#2804. License: MIT.
+
+## What it does
+
+In `~/.pi/agent/agents/` and `~/.pi/agent/subagents/` (or `$PI_CODING_AGENT_DIR`):
+
+- Removes the blocks gentle-ai writes between `<!-- gentle-ai:pi-codegraph-tool -->` / `<!-- gentle-ai:pi-codegraph-guidance -->` and `<!-- /gentle-ai:pi-codegraph -->`.
+- Removes the dead `mcp` entry (the retired `pi-mcp-adapter` proxy) and the `"*": false` entry from every `tools:` list.
+- Adds `mcp__codegraph__codegraph_explore` to `gentle-ai-explore`, `gentle-ai-verify`, `gentle-ai-worker`, `jd-fix-agent`, `jd-judge-a` and `jd-judge-b`, removes the `codegraph` extension tool from `gentle-ai-explore`, and rewrites that agent's own CodeGraph instructions to use the MCP tool.
+- Leaves the `review-*` agents without CodeGraph.
+
+In `mcp.json`: sets `"exposure": "direct"` on the `codegraph` server. Without it Pi never declares the server's tools to the model and the `tools:` entry above matches nothing.
+
+In a subagent that only reads and holds `mcp__codegraph__codegraph_explore` (the explorer), a `before_agent_start` hook also runs `codegraph explore <task>` once before the first model call and hands the output to the model as a message, bounded to 20 s and 12,000 characters. If the project has no `.codegraph/` index, the CLI is missing or fails, nothing is added and the run continues as before.
+
+Before the first change to a file it saves the original next to it as `<file>.pre-codegraph-subagents.bak`; later changes never overwrite that backup.
+
+## Install
+
+```
+pi install npm:@zhalker/gentle-shell-codegraph-subagents
+```
+
+Changes apply on the next session start. Reinstalling, or running `gentle-ai sync` again, is corrected the same way on the following start.
+
+## Uninstall
+
+Remove the package, then copy each `*.pre-codegraph-subagents.bak` over its original if you want the previous files back.
+
+## Known limits
+
+- Only the global agent directory is handled, not `<project>/.pi/agents/`.
+- The explorer prefetch is recognised by the child's tool set (read-only plus the CodeGraph MCP tool), because gentle-pi does not tell the child which agent it is.
+- The rewrite of the explorer's own instructions matches known sentences; if gentle-pi rewords them, they are left as they are.
+- The `codegraph` MCP server has to exist in `mcp.json`; the package never creates it.
+- Tested with Pi 1.4.0 and node 24.
+
+## Development
+
+`npm test` runs the unit tests with Node's built-in runner.

package/extensions/index.ts

@@ -0,0 +1,38 @@
+import { existsSync } from "node:fs";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { applyCodegraphSubagents } from "../src/apply.ts";
+import { exploreWithCodegraph, prefetchForExplorer } from "../src/prefetch.ts";
+
+// Reapplied on every session start so a reinstall (pi install, gentle-shell install)
+// or a gentle-ai sync that rewrote the agent files is corrected on the next launch.
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		try {
+			const { changed, errors } = applyCodegraphSubagents(getAgentDir());
+			if (!ctx.hasUI) return;
+			if (changed.length > 0) ctx.ui.notify(`gentle-shell-codegraph-subagents: updated ${changed.length} file(s)`, "info");
+			if (errors.length > 0) ctx.ui.notify(`gentle-shell-codegraph-subagents: ${errors.length} file(s) skipped: ${errors[0]}`, "warning");
+		} catch {
+			// Never block a session over this.
+		}
+	});
+
+	// Only the explorer child: hand it `codegraph explore` for its task before its first model call.
+	// Without .codegraph, the CLI, or in time, the run goes on exactly as before.
+	pi.on("before_agent_start", async (event) => {
+		try {
+			const prompt = event.messageType === "user" ? event.prompt : undefined;
+			const content = await prefetchForExplorer({
+				env: process.env,
+				prompt,
+				cwd: process.cwd(),
+				exists: existsSync,
+				explore: exploreWithCodegraph,
+			});
+			if (content === undefined) return undefined;
+			return { message: { customType: "codegraph-prefetch", content, display: false } };
+		} catch {
+			return undefined;
+		}
+	});
+}

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "@zhalker/gentle-shell-codegraph-subagents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Pi package that keeps CodeGraph reachable from gentle-shell subagents: normalizes agent tool lists and the codegraph MCP exposure on every session start, and pre-fetches CodeGraph for the explorer.",
+  "license": "MIT",
+  "author": "zhalker",
+  "type": "module",
+  "keywords": ["pi-package", "pi", "codegraph", "subagents", "gentle-shell", "gentle-ai", "mcp"],
+  "files": ["extensions", "src", "README.md", "LICENSE"],
+  "pi": {
+    "extensions": ["./extensions/index.ts"]
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.ts\"",
+    "prepublishOnly": "npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/src/agents.ts

@@ -0,0 +1,111 @@
+export const CODEGRAPH_MCP_TOOL = "mcp__codegraph__codegraph_explore";
+
+const EXPLORER = "gentle-ai-explore";
+const AGENTS_WITH_MCP_TOOL = new Set([
+	"gentle-ai-explore",
+	"gentle-ai-verify",
+	"gentle-ai-worker",
+	"jd-fix-agent",
+	"jd-judge-a",
+	"jd-judge-b",
+]);
+
+const FRONTMATTER = /^(---\r?\n)([\s\S]*?)(\r?\n---)([\s\S]*)$/;
+const GENTLE_AI_BLOCK = /<!-- gentle-ai:pi-codegraph-(?:tool|guidance) -->[\s\S]*?<!-- \/gentle-ai:pi-codegraph -->/g;
+const MARKER = "\u0000";
+
+function unquote(value: string): string {
+	const v = value.trim();
+	return v.length >= 2 && (v[0] === '"' || v[0] === "'") && v[v.length - 1] === v[0] ? v.slice(1, -1) : v;
+}
+
+// The gentle-pi agent files ship a `- "*": false` list entry; Pi reads it as a tool named `*": false`.
+function isBrokenEntry(item: string): boolean {
+	return /\*["']?\s*:\s*false/.test(item);
+}
+
+const EXPLORER_STRUCTURAL_LINE = "- For structural questions, use the cwd-scoped `codegraph` tool";
+const EXPLORER_INDEX_LINE = "- `codegraph` may create or update only the current workspace `.codegraph/` index";
+const EXPLORER_READ_ONLY_PHRASE = "Other than the explicit `.codegraph/` index exception, read and search only.";
+
+// The explorer loses its `codegraph` extension tool, so the lines that tell it to use or initialize that tool would send it nowhere.
+function rewriteExplorerInstructions(body: string, eol: string): string {
+	if (!body.includes("codegraph")) return body;
+	const out: string[] = [];
+	for (const line of body.split(eol)) {
+		if (line.startsWith(EXPLORER_STRUCTURAL_LINE)) {
+			out.push(`- For structural questions, use the \`${CODEGRAPH_MCP_TOOL}\` tool before broad filesystem searches. It reads the existing \`.codegraph/\` index and cannot create one; when the project has none, use \`read\`, \`grep\`, and \`find\` and say so in the handoff.`);
+		} else if (line.startsWith(EXPLORER_INDEX_LINE)) {
+			continue;
+		} else {
+			out.push(line.replace(EXPLORER_READ_ONLY_PHRASE, "Read and search only."));
+		}
+	}
+	return out.join(eol);
+}
+
+function removeBlocks(body: string, eol: string): string {
+	if (!body.includes("gentle-ai:pi-codegraph")) return body;
+	const marked = body.replace(GENTLE_AI_BLOCK, MARKER);
+	return marked.replace(/\s*\u0000(?:\s*\u0000)*\s*/g, (match, offset: number) => {
+		if (offset === 0) return "";
+		return offset + match.length >= marked.length ? eol : eol + eol;
+	});
+}
+
+
+function editTools(front: string, eol: string): string {
+	const lines = front.split(/\r?\n/);
+	const nameLine = lines.find((line) => /^name:/.test(line));
+	const name = nameLine ? unquote(nameLine.slice("name:".length)) : "";
+	const at = lines.findIndex((line) => /^tools:/.test(line));
+	if (at === -1) return front;
+
+	const rest = lines[at].slice("tools:".length).trim();
+	let style: "bracket" | "csv" | "list";
+	let items: string[];
+	let consumed = 1;
+	let indent = "  ";
+	if (rest.startsWith("[")) {
+		style = "bracket";
+		items = rest.replace(/^\[/, "").replace(/\]$/, "").split(",").map((s) => s.trim()).filter(Boolean);
+	} else if (rest.length > 0) {
+		style = "csv";
+		items = rest.split(",").map((s) => s.trim()).filter(Boolean);
+	} else {
+		style = "list";
+		items = [];
+		for (let i = at + 1; i < lines.length; i++) {
+			const m = /^(\s*)-\s+(.*)$/.exec(lines[i]);
+			if (!m) break;
+			if (items.length === 0) indent = m[1];
+			items.push(m[2].trim());
+			consumed++;
+		}
+	}
+	if (items.length === 0) return front;
+
+	let next = items.filter((item) => unquote(item) !== "mcp" && !isBrokenEntry(item));
+	if (name === EXPLORER) next = next.filter((item) => unquote(item) !== "codegraph");
+	if (AGENTS_WITH_MCP_TOOL.has(name) && !next.some((item) => unquote(item) === CODEGRAPH_MCP_TOOL)) next.push(CODEGRAPH_MCP_TOOL);
+	// An empty list would hand the agent Pi's default tools; keep what was there instead.
+	if (next.length === 0 || next.join("\n") === items.join("\n")) return front;
+
+	const replacement =
+		style === "list" ? ["tools:", ...next.map((item) => `${indent}- ${item}`)]
+		: style === "bracket" ? [`tools: [${next.join(", ")}]`]
+		: [`tools: ${next.join(", ")}`];
+	return [...lines.slice(0, at), ...replacement, ...lines.slice(at + consumed)].join(eol);
+}
+
+/** Returns the agent definition with the CodeGraph wiring applied; identical text when nothing changes. */
+export function normalizeAgent(text: string): string {
+	const match = FRONTMATTER.exec(text);
+	if (!match) return text;
+	const [, open, front, close, body] = match;
+	const eol = text.includes("\r\n") ? "\r\n" : "\n";
+	const name = /^name:\s*(.+)$/m.exec(front)?.[1];
+	const cleaned = removeBlocks(body, eol);
+	const rewritten = name !== undefined && unquote(name) === EXPLORER ? rewriteExplorerInstructions(cleaned, eol) : cleaned;
+	return open + editTools(front, eol) + close + rewritten;
+}

package/src/apply.ts

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { normalizeAgent } from "./agents.ts";
+import { normalizeMcpConfig } from "./mcp.ts";
+
+export interface ApplyResult {
+	/** Files that were rewritten. */
+	changed: string[];
+	/** One message per file that could not be processed. */
+	errors: string[];
+}
+
+const BACKUP_SUFFIX = ".pre-codegraph-subagents.bak";
+
+// Write beside the target and rename, so a reader never sees a half-written file.
+function writeAtomic(file: string, text: string): void {
+	const temp = `${file}.${process.pid}.tmp`;
+	try {
+		writeFileSync(temp, text);
+		renameSync(temp, file);
+	} catch (error) {
+		try { unlinkSync(temp); } catch { /* nothing to clean */ }
+		throw error;
+	}
+}
+
+function rewrite(file: string, normalize: (text: string) => string, result: ApplyResult): void {
+	try {
+		const before = readFileSync(file, "utf8");
+		const after = normalize(before);
+		if (after === before) return;
+		const backup = file + BACKUP_SUFFIX;
+		if (!existsSync(backup)) writeFileSync(backup, before, { flag: "wx" });
+		writeAtomic(file, after);
+		result.changed.push(file);
+	} catch (error) {
+		result.errors.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/**
+ * Applies the CodeGraph wiring to the global agent definitions and to mcp.json
+ * under `agentDir`. Idempotent and never throws: failures are returned in `errors`.
+ */
+export function applyCodegraphSubagents(agentDir: string): ApplyResult {
+	const result: ApplyResult = { changed: [], errors: [] };
+	for (const folder of ["agents", "subagents"]) {
+		const dir = join(agentDir, folder);
+		let entries: string[];
+		try {
+			entries = readdirSync(dir).filter((entry) => entry.toLowerCase().endsWith(".md")).sort();
+		} catch {
+			continue;
+		}
+		for (const entry of entries) rewrite(join(dir, entry), normalizeAgent, result);
+	}
+	const mcp = join(agentDir, "mcp.json");
+	if (existsSync(mcp)) rewrite(mcp, normalizeMcpConfig, result);
+	return result;
+}

package/src/mcp.ts

@@ -0,0 +1,25 @@
+/**
+ * Pi declares MCP tools to the model only for servers with `exposure: "direct"`;
+ * the default, `codemode`, makes them reachable from scripts but never callable
+ * as a tool, so an agent `tools:` entry like `mcp__codegraph__*` would match nothing.
+ * Returns the config with the codegraph server set to `direct`; identical text when nothing changes.
+ */
+export function normalizeMcpConfig(text: string): string {
+	let config: unknown;
+	try {
+		config = JSON.parse(text);
+	} catch {
+		return text;
+	}
+	if (typeof config !== "object" || config === null || Array.isArray(config)) return text;
+	const servers = (config as { mcpServers?: unknown }).mcpServers;
+	if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return text;
+	const server = (servers as Record<string, unknown>).codegraph;
+	if (typeof server !== "object" || server === null || Array.isArray(server)) return text;
+	const entry = server as Record<string, unknown>;
+	if (entry.enabled === false || entry.exposure === "direct") return text;
+
+	entry.exposure = "direct";
+	const indent = /^([ \t]+)"/m.exec(text)?.[1] ?? "  ";
+	return JSON.stringify(config, null, indent) + "\n";
+}

package/src/prefetch.ts

@@ -0,0 +1,142 @@
+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;
+	}
+}