pi-plans 0.2.0 → 0.3.1

package/tools/code-graph.ts

@@ -0,0 +1,277 @@
+/**
+ * Agent-facing graph tool. Eagerly avoids importing node:sqlite or the
+ * parsers at module load; both are loaded on first action call.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+	loadGraphRuntime,
+	describeRuntimeIssues,
+	type RuntimeStatus,
+} from "../src/code-graph/runtime.ts";
+import { resolveCanonicalWorktree } from "../src/code-graph/paths.ts";
+import type { WorktreePaths } from "../src/code-graph/paths.ts";
+import { Store } from "../src/code-graph/store.ts";
+import { makeBackend } from "../src/code-graph/parsers/javascript.ts";
+import { PythonBackend } from "../src/code-graph/parsers/python.ts";
+import type { ParserBackend } from "../src/code-graph/parser.ts";
+import { hashText } from "../src/code-graph/parser.ts";
+import type { Language } from "../src/code-graph/types.ts";
+import { screeningQuery } from "../src/code-graph/screening.ts";
+import { deleteFile, listPending, updateFile, updateFunction } from "../src/code-graph/mutations.ts";
+import { applyGraphCore } from "../src/code-graph/commands.ts";
+import { normalizeWorkdir } from "../src/state.ts";
+
+const CodeGraphParams = Type.Object({
+	action: StringEnum(
+		[
+			"status",
+			"screening",
+			"get-function",
+			"update-function",
+			"update-file",
+			"delete-file",
+			"list-pending",
+			"reindex",
+			"manifest",
+			"apply",
+		] as const,
+		{ description: "Code graph action to perform" },
+	),
+	workdir: Type.Optional(Type.String({ description: "Target workspace directory" })),
+	language: Type.Optional(StringEnum(["javascript", "typescript", "tsx", "python"] as const)),
+	functionName: Type.Optional(Type.String()),
+	fileDir: Type.Optional(Type.String({ description: "File directory (POSIX, '.' for root)" })),
+	fileName: Type.Optional(Type.String({ description: "File name without directory" })),
+	fullCode: Type.Optional(Type.String({ description: "New function body text for update-function" })),
+	text: Type.Optional(Type.String({ description: "New whole-file text for update-file" })),
+	limit: Type.Optional(Type.Number()),
+});
+
+export type CodeGraphContext = Parameters<Parameters<ExtensionAPI["registerTool"]>[0]["execute"]>[4];
+
+export interface RuntimeCacheEntry {
+	runtime: Awaited<ReturnType<typeof loadGraphRuntime>>["runtime"];
+	parsers: Record<Language, ParserBackend>;
+	paths: WorktreePaths;
+	store: Store;
+}
+
+let runtimeCache: RuntimeCacheEntry | null = null;
+
+export async function ensureRuntime(workdir: string, ctx: CodeGraphContext): Promise<{ entry: RuntimeCacheEntry; status: RuntimeStatus } | null> {
+	const { runtime, status } = await loadGraphRuntime();
+	if (status.issues.length > 0 && !status.sqliteAvailable && !status.parserAvailable) {
+		ctx.ui?.notify?.(`code-graph unavailable: ${describeRuntimeIssues(status).join("; ")}`, "warning");
+		return null;
+	}
+	const paths = resolveCanonicalWorktree(workdir);
+	if (!runtimeCache || runtimeCache.paths.codeGraphDb !== paths.codeGraphDb) {
+		if (runtimeCache) {
+			runtimeCache.store.close();
+			runtimeCache = null;
+		}
+		const store = new Store({ dbPath: paths.codeGraphDb, worktreeRoot: paths.worktreeRoot, gitCommonDir: paths.gitCommonDir }, runtime.sqlite);
+		try {
+			store.checkWorktree(paths.worktreeRoot, paths.gitCommonDir);
+		} catch (error) {
+			store.close();
+			ctx.ui?.notify?.(`code-graph: ${(error as Error).message}`, "error");
+			return null;
+		}
+		const ParserCtor = runtime.parser.Parser as unknown as new () => { parse(input: string | Buffer): unknown; setLanguage(language: unknown): void };
+		const parsers: Record<Language, ParserBackend> = {
+			javascript: makeBackend("javascript", ParserCtor, runtime.parser.javascript),
+			typescript: makeBackend("typescript", ParserCtor, runtime.parser.typescript),
+			tsx: makeBackend("tsx", ParserCtor, runtime.parser.tsx),
+			python: new PythonBackend(ParserCtor, runtime.parser.python),
+		};
+		runtimeCache = { runtime, parsers, paths, store };
+	}
+	return { entry: runtimeCache, status };
+}
+
+export function registerCodeGraphTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "code_graph",
+		label: "Code Graph",
+		description:
+			"Code-graph actions: read-only queries (status, screening without full_code, function read, manifest summary) plus `apply` — safe non-force materialization of DB-first staged edits into the worktree (same gate as /apply-graph: refused during active planning/accepted runs and for read-only refiner subagents via PI_PLANS_REFINER; returns per-file report with counts and a post-apply drift summary; never changes run status). reindex stays user-only (/init-graph).",
+		promptSnippet: "Read-only code graph queries",
+		parameters: CodeGraphParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const workdir = params.workdir ?? ctx.cwd;
+			if (params.action === "apply") {
+				if (process.env.PI_PLANS_REFINER === "1") {
+					return {
+						content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "code-graph apply refused: read-only refiner subagents cannot materialize worktree edits (PI_PLANS_REFINER)" }) }],
+						details: {},
+					};
+				}
+				const core = await applyGraphCore(normalizeWorkdir(workdir));
+				if (core.refused || core.failed || !core.report) {
+					return {
+						content: [{ type: "text", text: JSON.stringify({ ok: false, reason: core.refused ?? core.failed ?? "unknown error" }) }],
+						details: {},
+					};
+				}
+				const counts: Record<string, number> = { ok: 0, deleted: 0, stale: 0, "skipped-missing": 0, error: 0 };
+				for (const file of core.report.files) counts[file.status] = (counts[file.status] ?? 0) + 1;
+				return {
+					content: [{ type: "text", text: JSON.stringify({ ok: true, report: { counts, files: core.report.files }, drift: core.drift ?? null }) }],
+					details: {},
+				};
+			}
+			const ensured = await ensureRuntime(workdir, ctx);
+			if (!ensured) {
+				return {
+					content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "runtime unavailable" }) }],
+					details: {},
+				};
+			}
+			const { entry } = ensured;
+			switch (params.action) {
+				case "status":
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify({
+									ok: true,
+									dbPath: entry.paths.codeGraphDb,
+									worktreeRoot: entry.paths.worktreeRoot,
+									files: entry.store.read(() => entry.store.db.prepare("SELECT COUNT(*) AS c FROM files").get()) as { c: number } | undefined,
+									functions: entry.store.read(() => entry.store.db.prepare("SELECT COUNT(*) AS c FROM functions").get()) as { c: number } | undefined,
+								}),
+							},
+						],
+						details: {},
+					};
+				case "screening": {
+					const items = screeningQuery({
+						store: entry.store,
+						language: params.language,
+						functionNameLike: params.functionName,
+						limit: params.limit ?? 100,
+					});
+					return {
+						content: [{ type: "text", text: JSON.stringify({ ok: true, items }) }],
+						details: {},
+					};
+				}
+				case "get-function": {
+					if (!params.functionName) {
+						return {
+							content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "functionName required" }) }],
+							details: {},
+						};
+					}
+					const row = entry.store.read(() =>
+						entry.store.db
+							.prepare(
+								`SELECT file_dir, file_name, function_name, full_code, render_code,
+									full_code_hash, render_code_hash, version, kind
+								 FROM functions
+								 WHERE function_name = ? LIMIT 1`,
+							)
+							.get(params.functionName),
+					) as
+						| {
+								file_dir: string;
+								file_name: string;
+								function_name: string;
+								full_code: string;
+								render_code: string;
+								full_code_hash: string;
+								render_code_hash: string;
+								version: number;
+								kind: string;
+						  }
+						| undefined;
+					if (!row) {
+						return {
+							content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "not found" }) }],
+							details: {},
+						};
+					}
+					return {
+						content: [{ type: "text", text: JSON.stringify({ ok: true, function: row }) }],
+						details: {},
+					};
+				}
+case "update-function": {
+					if (!params.fileDir || !params.fileName || !params.functionName || typeof params.fullCode !== "string") {
+						return {
+							content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "fileDir, fileName, functionName, and fullCode are required" }) }],
+							details: {},
+						};
+					}
+					const result = updateFunction(entry.store, {
+						fileDir: params.fileDir,
+						fileName: params.fileName,
+						functionName: params.functionName,
+						fullCode: params.fullCode,
+					});
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: {} };
+				}
+				case "update-file": {
+					if (!params.fileDir || !params.fileName || typeof params.text !== "string") {
+						return {
+							content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "fileDir, fileName, and text are required" }) }],
+							details: {},
+						};
+					}
+					const result = updateFile(entry.store, {
+						fileDir: params.fileDir,
+						fileName: params.fileName,
+						text: params.text,
+						...(params.language ? { language: params.language } : {}),
+					});
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: {} };
+				}
+				case "delete-file": {
+					if (!params.fileDir || !params.fileName) {
+						return {
+							content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "fileDir and fileName are required" }) }],
+							details: {},
+						};
+					}
+					const result = deleteFile(entry.store, { fileDir: params.fileDir, fileName: params.fileName });
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: {} };
+				}
+				case "list-pending": {
+					return { content: [{ type: "text", text: JSON.stringify({ ok: true, pending: listPending(entry.store) }) }], details: {} };
+				}
+				
+				case "reindex":
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify({
+									ok: false,
+									reason: "reindex must run via the /init-graph slash command (D-013)",
+								}),
+							},
+						],
+						details: {},
+					};
+				case "manifest": {
+					const rows = entry.store.read(() =>
+						entry.store.db
+							.prepare(
+								`SELECT file_dir, file_name, COUNT(*) AS c FROM file_entries GROUP BY file_dir, file_name ORDER BY file_dir, file_name`,
+							)
+							.all(),
+					) as Array<{ file_dir: string; file_name: string; c: number }>;
+					return {
+						content: [{ type: "text", text: JSON.stringify({ ok: true, manifest: rows }) }],
+						details: {},
+					};
+				}
+			}
+		},
+	});
+}

package/tools/graph-aware-file-tools.ts

@@ -0,0 +1,392 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	createEditTool,
+	createReadTool,
+	createWriteTool,
+	truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import * as path from "node:path";
+import { isIndexablePath } from "../src/code-graph/discovery.ts";
+import { resolveGraphMode, type GraphMode } from "../src/code-graph/mode.ts";
+import { normalizeRelative, PathError } from "../src/code-graph/paths.ts";
+import { updateFile } from "../src/code-graph/mutations.ts";
+import type { Language } from "../src/code-graph/types.ts";
+import { ensureRuntime, type CodeGraphContext, type RuntimeCacheEntry } from "./code-graph.ts";
+
+interface GraphPathInfo {
+	absolutePath: string;
+	relativePath: string;
+	fileDir: string;
+	fileName: string;
+	language: Language;
+}
+
+interface GraphSnapshot {
+	info: GraphPathInfo;
+	text: string;
+}
+
+interface FunctionRow {
+	function_name: string;
+	is_primary: number;
+	provenance_start_line: number | null;
+	provenance_end_line: number | null;
+	provenance_start_byte: number | null;
+	provenance_end_byte: number | null;
+	summary_description: string | null;
+}
+
+type GraphToolSet = ReturnType<typeof createGraphAwareFileTools>;
+
+/** Files smaller than this are returned in full by default (digest not worth it). */
+const FULL_FILE_MAX_LINES = 200;
+/** Hard cap for digest output, header/footer lines included. */
+const DIGEST_MAX_LINES = 50;
+/** Native-equivalent full-read truncation hints are provided by truncateHead. */
+
+const toolCache = new Map<string, GraphToolSet>();
+
+function getBaseTools(cwd: string) {
+	return {
+		read: createReadTool(cwd),
+		write: createWriteTool(cwd),
+		edit: createEditTool(cwd),
+	};
+}
+
+const GraphReadParams = Type.Object({
+	path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
+	offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+	full: Type.Optional(
+		Type.Boolean({
+			description:
+				"Return the whole file (through the same safety truncation as native read) instead of the default function digest",
+		}),
+	),
+});
+
+function languageForFileName(fileName: string): Language | null {
+	switch (path.extname(fileName).toLowerCase()) {
+		case ".js":
+		case ".mjs":
+		case ".cjs":
+			return "javascript";
+		case ".ts":
+			return "typescript";
+		case ".tsx":
+			return "tsx";
+		case ".py":
+			return "python";
+		default:
+			return null;
+	}
+}
+
+function resolveGraphPath(cwd: string, worktreeRoot: string, target: string): GraphPathInfo | null {
+	const absolutePath = path.resolve(cwd, target);
+	const relativePath = path.relative(worktreeRoot, absolutePath).split(path.sep).join("/");
+	if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) return null;
+	if (!isIndexablePath(relativePath)) return null;
+	try {
+		const { fileDir, fileName } = normalizeRelative(worktreeRoot, absolutePath);
+		const language = languageForFileName(fileName);
+		if (!language) return null;
+		return { absolutePath, relativePath, fileDir, fileName, language };
+	} catch (error) {
+		if (error instanceof PathError) return null;
+		throw error;
+	}
+}
+
+function sliceByLines(text: string, offset?: number, limit?: number): string {
+	const lines = text.split("\n");
+	const start = offset ? Math.max(0, offset - 1) : 0;
+	const end = limit !== undefined ? start + Math.max(0, limit) : lines.length;
+	return lines.slice(start, end).join("\n");
+}
+
+function countLines(text: string): number {
+	return text.split("\n").length;
+}
+
+function textContent(result: { content: Array<{ type: string; text?: string }> }): string {
+	const part = result.content.find((entry) => entry.type === "text" && typeof entry.text === "string");
+	return part?.text ?? "";
+}
+
+function loadGraphSnapshot(entry: RuntimeCacheEntry, info: GraphPathInfo): GraphSnapshot | null {
+	const row = entry.store.read(() =>
+		entry.store.db
+			.prepare(`SELECT source_text, pending_kind FROM files WHERE file_dir = ? AND file_name = ?`)
+			.get(info.fileDir, info.fileName),
+	) as { source_text: string; pending_kind: string | null } | undefined;
+	if (!row || row.pending_kind === "delete") return null;
+	return {
+		info,
+		text: row.source_text,
+	};
+}
+
+function loadFunctionRows(entry: RuntimeCacheEntry, info: GraphPathInfo): FunctionRow[] {
+	return entry.store.read(() =>
+		entry.store.db
+			.prepare(
+				`SELECT function_name, is_primary, provenance_start_line, provenance_end_line,
+					provenance_start_byte, provenance_end_byte, summary_description
+				 FROM functions WHERE file_dir = ? AND file_name = ?`,
+			)
+			.all(info.fileDir, info.fileName),
+	) as FunctionRow[];
+}
+
+/** Provenance offsets are byte offsets: decode via Buffer, never string.slice. */
+function describeSlice(text: string, startByte: number | null, endByte: number | null): string {
+	if (startByte === null || endByte === null || endByte <= startByte) return "";
+	try {
+		const buf = Buffer.from(text, "utf8");
+		const slice = buf.subarray(startByte, Math.min(endByte, buf.length)).toString("utf8");
+		return slice.split("\n")[0]?.trim() ?? "";
+	} catch {
+		return "";
+	}
+}
+
+function truncatedDetails(
+	truncation: ReturnType<typeof truncateHead>,
+	totalLines: number,
+): Record<string, unknown> {
+	// Counts only — never the content copy; the text already lives in `content`.
+	return {
+		truncated: truncation.truncated === true,
+		truncatedBy: truncation.truncatedBy ?? null,
+		totalLines,
+		outputLines: truncation.outputLines,
+		outputBytes: truncation.outputBytes,
+		maxLines: truncation.maxLines,
+		maxBytes: truncation.maxBytes,
+	};
+}
+
+function fullTextResult(text: string, offset?: number, limit?: number) {
+	const totalLines = countLines(text);
+	if (offset !== undefined && offset > totalLines) {
+		// Align with native read: an offset past EOF is a caller error.
+		throw new Error(`offset ${offset} beyond end of file (${totalLines} lines)`);
+	}
+	const selected = sliceByLines(text, offset, limit);
+	const truncation = truncateHead(selected, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+	return {
+		content: [{ type: "text", text: truncation.content }],
+		details: truncatedDetails(truncation, totalLines),
+	};
+}
+
+/**
+ * Compact function digest: one line per named function, synthetic anonymous
+ * entries folded into a single count, capped at DIGEST_MAX_LINES with a tail
+ * pointer to the low-token graph tools.
+ */
+function buildDigest(info: GraphPathInfo, text: string, rows: FunctionRow[]) {
+	const totalLines = countLines(text);
+	const named: FunctionRow[] = [];
+	let anonymous = 0;
+	for (const row of rows) {
+		if (row.function_name.includes("<anonymous")) {
+			anonymous++;
+			continue;
+		}
+		named.push(row);
+	}
+	named.sort((a, b) => {
+		const primary = (b.is_primary ? 1 : 0) - (a.is_primary ? 1 : 0);
+		if (primary !== 0) return primary;
+		return (a.provenance_start_line ?? 0) - (b.provenance_start_line ?? 0);
+	});
+
+	const lines: string[] = [
+		`${info.relativePath} · ${info.language} · ${named.length} functions${anonymous ? ` (+${anonymous} anonymous)` : ""}`,
+	];
+	const bodyBudget = DIGEST_MAX_LINES - 2; // header + footer
+	for (const row of named) {
+		if (lines.length >= bodyBudget - 1) break; // reserve one line for the "+M more" tail
+		const description = (row.summary_description ?? "").trim() || describeSlice(text, row.provenance_start_byte, row.provenance_end_byte);
+		const range =
+			row.provenance_start_line && row.provenance_end_line ? ` (${row.provenance_start_line}-${row.provenance_end_line})` : "";
+		lines.push(`${row.function_name}${range}${description ? ` ${description}` : ""}`);
+	}
+	const hidden = named.length - (lines.length - 1);
+	if (hidden > 0) {
+		lines.push(`…+${hidden} more (code_graph screening / get-function)`);
+	}
+	lines.push(`Use full:true for the whole file (${totalLines} lines, safety-truncated), or code_graph get-function for one function body.`);
+	return {
+		content: [{ type: "text", text: lines.join("\n") }],
+		details: { functions: named.length, anonymous, shown: Math.max(0, lines.length - 2), hidden: Math.max(0, hidden), totalLines },
+	};
+}
+
+function createGraphReadTool(cwd: string) {
+	const base = getBaseTools(cwd).read;
+	return {
+		...base,
+		parameters: GraphReadParams,
+		async execute(
+			toolCallId: string,
+			params: { path: string; offset?: number; limit?: number; full?: boolean },
+			signal: AbortSignal | undefined,
+			onUpdate: any,
+			ctx: CodeGraphContext,
+		) {
+			const native = async (marker: string | null) => {
+				const result = await getBaseTools(ctx.cwd).read.execute(toolCallId, params, signal, onUpdate);
+				if (!marker) return result;
+				return {
+					...result,
+					content: [{ type: "text", text: `[graph-read fallback: ${marker} → native]\n${textContent(result)}` }],
+				};
+			};
+			const mode: GraphMode = resolveGraphMode(ctx.cwd);
+			if (mode === "off") return native(null);
+			if (mode === "config-unavailable") return native("config read failed");
+			const ensured = await ensureRuntime(ctx.cwd, ctx);
+			if (!ensured) return native("runtime unavailable");
+			const info = resolveGraphPath(ctx.cwd, ensured.entry.paths.worktreeRoot, params.path);
+			if (!info) return native(null); // not an indexable source file: native by design
+			const snapshot = loadGraphSnapshot(ensured.entry, info);
+			if (!snapshot) return native("not indexed");
+			const wantsFull = params.full === true || params.offset !== undefined || params.limit !== undefined;
+			if (wantsFull) return fullTextResult(snapshot.text, params.offset, params.limit);
+			const rows = loadFunctionRows(ensured.entry, info);
+			if (countLines(snapshot.text) < FULL_FILE_MAX_LINES || rows.length === 0) {
+				return fullTextResult(snapshot.text, params.offset, params.limit);
+			}
+			return buildDigest(info, snapshot.text, rows);
+		},
+	};
+}
+
+function createGraphWriteTool(cwd: string) {
+	const base = getBaseTools(cwd).write;
+	return {
+		...base,
+		async execute(toolCallId: string, params: { path: string; content: string }, signal: AbortSignal | undefined, onUpdate: any, ctx: CodeGraphContext) {
+			const stage = async (marker: string | null) => {
+				const result = await getBaseTools(ctx.cwd).write.execute(toolCallId, params, signal, onUpdate);
+				if (!marker) return result;
+				return {
+					...result,
+					content: [{ type: "text", text: `[graph-write fallback: ${marker} → native]\n${textContent(result)}` }],
+				};
+			};
+			const mode: GraphMode = resolveGraphMode(ctx.cwd);
+			if (mode === "off") return stage(null);
+			if (mode === "config-unavailable") return stage("config read failed");
+			const ensured = await ensureRuntime(ctx.cwd, ctx);
+			if (!ensured) return stage("runtime unavailable");
+			const info = resolveGraphPath(ctx.cwd, ensured.entry.paths.worktreeRoot, params.path);
+			if (!info) return stage(null);
+			const mutation = updateFile(ensured.entry.store, {
+				fileDir: info.fileDir,
+				fileName: info.fileName,
+				text: params.content,
+				language: info.language,
+			});
+			if (!mutation.ok) {
+				throw new Error(`code graph write failed: ${mutation.reason ?? "unknown error"}`);
+			}
+			return {
+				content: [
+					{
+						type: "text",
+						text: `code graph: staged ${mutation.created ? "new" : "updated"} file ${info.relativePath}; run code_graph apply to materialize`,
+					},
+				],
+				details: {},
+			};
+		},
+	};
+}
+
+function createGraphEditTool(cwd: string) {
+	const base = getBaseTools(cwd).edit;
+	return {
+		...base,
+		async execute(toolCallId: string, params: { path: string; edits: Array<{ oldText: string; newText: string }> }, signal: AbortSignal | undefined, onUpdate: any, ctx: CodeGraphContext) {
+			const stage = async (marker: string | null) => {
+				const result = await getBaseTools(ctx.cwd).edit.execute(toolCallId, params, signal, onUpdate);
+				if (!marker) return result;
+				return {
+					...result,
+					content: [{ type: "text", text: `[graph-edit fallback: ${marker} → native]\n${textContent(result)}` }],
+				};
+			};
+			const mode: GraphMode = resolveGraphMode(ctx.cwd);
+			if (mode === "off") return stage(null);
+			if (mode === "config-unavailable") return stage("config read failed");
+			const ensured = await ensureRuntime(ctx.cwd, ctx);
+			if (!ensured) return stage("runtime unavailable");
+			const info = resolveGraphPath(ctx.cwd, ensured.entry.paths.worktreeRoot, params.path);
+			if (!info) return stage(null);
+			const snapshot = loadGraphSnapshot(ensured.entry, info);
+			if (!snapshot) {
+				throw new Error(`code graph: ${info.relativePath} is not indexed; run /update-graph or /init-graph first`);
+			}
+			let stagedText: string | null = null;
+			const graphEdit = createEditTool(ctx.cwd, {
+				operations: {
+					access: async () => {},
+					readFile: async () => Buffer.from(snapshot.text, "utf8"),
+					writeFile: async (_absolutePath: string, content: string) => {
+						stagedText = content;
+					},
+				},
+			});
+			const result = await graphEdit.execute(toolCallId, params, signal, onUpdate);
+			if (stagedText === null) {
+				throw new Error(`code graph edit failed: no staged content captured for ${info.relativePath}`);
+			}
+			const mutation = updateFile(ensured.entry.store, {
+				fileDir: info.fileDir,
+				fileName: info.fileName,
+				text: stagedText,
+				language: info.language,
+			});
+			if (!mutation.ok) {
+				throw new Error(`code graph edit failed: ${mutation.reason ?? "unknown error"}`);
+			}
+			return {
+				...result,
+				content: [
+					{
+						type: "text",
+						text: `${textContent(result)} (staged in code graph; run code_graph apply to materialize)`,
+					},
+				],
+			};
+		},
+	};
+}
+
+export function createGraphAwareFileTools(cwd: string) {
+	let tools = toolCache.get(cwd);
+	if (!tools) {
+		tools = {
+			read: createGraphReadTool(cwd),
+			write: createGraphWriteTool(cwd),
+			edit: createGraphEditTool(cwd),
+		};
+		toolCache.set(cwd, tools);
+	}
+	return tools;
+}
+
+export function registerGraphAwareFileTools(pi: ExtensionAPI, cwd = process.cwd()): void {
+	const tools = createGraphAwareFileTools(cwd);
+	pi.registerTool(tools.read);
+	pi.registerTool(tools.write);
+	pi.registerTool(tools.edit);
+}