@selesai/code 0.13.22 → 0.13.23

package/dist/extensions/pi-graft/tools.test.ts

@@ -0,0 +1,330 @@
+import { describe, expect, it, vi } from "vitest";
+import type { GraftOp, GraftRun } from "./cli.ts";
+import type { GraftSettings, GraftState } from "./state.ts";
+import { makeCtx, makePi } from "./test-support.ts";
+import { registerGraftTools, renderAskResult, type GraftToolDetails, type GraftToolRuntime } from "./tools.ts";
+
+const TOOL_NAMES = [
+	"graft_find_code",
+	"graft_file_api",
+	"graft_trace_calls",
+	"graft_find_all",
+	"graft_repo_map",
+	"graft_check_freshness",
+];
+
+const ASK_JSON = JSON.stringify({
+	query: "where is auth verified",
+	mode: "lexical",
+	coverage: 0.7,
+	hits: [
+		{
+			kind: "symbol",
+			title: "verify · function",
+			pointer: "src/auth.ts:L10-L20",
+			snippet: "checks the token",
+			code: "export function verify(token: string) {\n  return true;\n}",
+		},
+	],
+	saved: { files: 1, baselineChars: 800 },
+});
+
+interface Harness {
+	/** The runtime the tools were registered against. */
+	runtime: GraftToolRuntime;
+	/** The operation each tool call asked Graft to run. */
+	run: ReturnType<typeof vi.fn>;
+	/** Runs a registered tool by name against this harness's runtime. */
+	exec: (
+		name: string,
+		params: Record<string, unknown>,
+		signal?: AbortSignal,
+	) => Promise<{ text: string; details: GraftToolDetails }>;
+	/** Results the runtime was told to treat as answered queries. */
+	noted: GraftRun[];
+}
+
+function makeHarness(
+	options: { result?: Partial<GraftRun>; settings?: GraftSettings; state?: GraftState } = {},
+): Harness {
+	const base: GraftRun = {
+		op: { kind: "repo-map" },
+		argv: ["graft", "map"],
+		cwd: "/repo",
+		code: 0,
+		stdout: "",
+		stderr: "",
+		killed: false,
+		cancelled: false,
+		timedOut: false,
+		...options.result,
+	};
+	const run = vi.fn(async (_ctx: unknown, op: GraftOp) => ({ ...base, op }));
+	const noted: GraftRun[] = [];
+	const runtime: GraftToolRuntime = {
+		run: run as never,
+		settings: () => options.settings ?? {},
+		state: () => options.state ?? { name: "fresh-structural", version: "0.18.0" },
+		noteQuery: ((_ctx: unknown, result: GraftRun) => {
+			noted.push(result);
+		}) as never,
+	};
+
+	const exec = async (
+		name: string,
+		params: Record<string, unknown>,
+		signal?: AbortSignal,
+	): Promise<{ text: string; details: GraftToolDetails }> => {
+		const { pi, tools } = makePi();
+		registerGraftTools(pi as never, runtime);
+		const definition = tools.get(name);
+		if (!definition) throw new Error(`${name} was not registered`);
+		const result = (await (definition.execute as (...args: unknown[]) => Promise<unknown>)(
+			"call-1",
+			params,
+			signal,
+			undefined,
+			makeCtx(),
+		)) as { content: { text: string }[]; details: GraftToolDetails };
+		return { text: result.content[0]!.text, details: result.details };
+	};
+
+	return { runtime, run, exec, noted };
+}
+
+describe("graft tool registration", () => {
+	it("registers exactly the six read-only semantic tools", () => {
+		const { pi, tools } = makePi();
+		registerGraftTools(pi as never, makeHarness().runtime);
+		expect([...tools.keys()].sort()).toEqual([...TOOL_NAMES].sort());
+	});
+
+	it("gives every tool a label, description and parameter schema", () => {
+		const { pi, tools } = makePi();
+		registerGraftTools(pi as never, makeHarness().runtime);
+		for (const name of TOOL_NAMES) {
+			const tool = tools.get(name)!;
+			expect(tool.description).toBeTruthy();
+			expect(tool.parameters).toBeTruthy();
+			expect(tool.label).toContain("Graft");
+		}
+	});
+
+	it("tells the model that Graft output is derived and must be verified against source", () => {
+		const { pi, tools } = makePi();
+		registerGraftTools(pi as never, makeHarness().runtime);
+		const guidelines = tools.get("graft_find_code")!.promptGuidelines as string[];
+		expect(guidelines.join("\n")).toContain("verify");
+		expect(tools.get("graft_find_code")!.description).toContain("derived");
+	});
+});
+
+describe("graft_find_code", () => {
+	it("asks Graft the model's question with source inlining and structured output", async () => {
+		const harness = makeHarness({ result: { stdout: ASK_JSON } });
+		const { text, details } = await harness.exec("graft_find_code", { question: "where is auth verified" });
+
+		expect(harness.run).toHaveBeenCalledTimes(1);
+		expect(harness.run.mock.calls[0]![1]).toEqual({
+			kind: "find-code",
+			question: "where is auth verified",
+			limit: undefined,
+			in: undefined,
+		});
+		expect(text).toContain("src/auth.ts:L10-L20");
+		expect(text).toContain("export function verify");
+		expect(details.references).toEqual([{ path: "src/auth.ts", span: "L10-L20" }]);
+		expect(details.coverage).toBe(0.7);
+		expect(details.saved).toEqual({ files: 1, baselineChars: 800 });
+		expect(details.operation).toBe("find-code");
+		expect(details.graphState).toBe("fresh-structural");
+		expect(harness.noted).toHaveLength(1);
+	});
+
+	it("applies the project's scope setting when the model does not name one", async () => {
+		const harness = makeHarness({ result: { stdout: ASK_JSON }, settings: { in: "packages/api" } });
+		await harness.exec("graft_find_code", { question: "auth" });
+		expect(harness.run.mock.calls[0]![1]).toMatchObject({ in: "packages/api" });
+	});
+
+	it("falls back to the CLI's own text when its JSON is not the shape we know", async () => {
+		const harness = makeHarness({
+			result: { stdout: "verify · function — src/auth.ts:L10-L20\n  checks the token" },
+		});
+		const { text, details } = await harness.exec("graft_find_code", { question: "auth" });
+		expect(text).toContain("src/auth.ts:L10-L20");
+		expect(details.references).toEqual([]);
+	});
+
+	it("keeps command diagnostics out of the model-facing text", async () => {
+		const harness = makeHarness({
+			result: { stdout: ASK_JSON, stderr: "[graft] rebuilt from src/ (2 files changed)" },
+		});
+		const { text, details } = await harness.exec("graft_find_code", { question: "auth" });
+		expect(text).not.toContain("rebuilt from");
+		expect(details.stderr).toContain("rebuilt from");
+	});
+
+	it("bounds the result and reports the truncation and the recovery path", async () => {
+		const harness = makeHarness({
+			result: {
+				stdout: JSON.stringify({ hits: [{ pointer: "src/a.ts", title: "big", code: "x".repeat(200_000) }] }),
+			},
+		});
+		const { text, details } = await harness.exec("graft_find_code", { question: "auth" });
+		expect(details.truncated).toBe(true);
+		expect(text).toContain("[graft] output truncated");
+		expect(Buffer.byteLength(text, "utf-8")).toBeLessThan(48 * 1024);
+	});
+
+	it("fails the tool call with the command's own diagnostic when Graft errors", async () => {
+		const harness = makeHarness({ result: { code: 1, stderr: "✗ no graft/ index here" } });
+		await expect(harness.exec("graft_find_code", { question: "auth" })).rejects.toThrow(/no graft\/ index here/);
+		expect(harness.noted).toHaveLength(0);
+	});
+
+	it("fails the tool call when the model cancels the turn", async () => {
+		const harness = makeHarness({ result: { cancelled: true } });
+		await expect(harness.exec("graft_find_code", { question: "auth" })).rejects.toThrow(/cancelled/);
+	});
+
+	it("reports a timeout as a timeout rather than as a generic failure", async () => {
+		const harness = makeHarness({ result: { code: 1, killed: true, timedOut: true } });
+		await expect(harness.exec("graft_find_code", { question: "auth" })).rejects.toThrow(/timed out/);
+	});
+});
+
+describe("the remaining read-only tools", () => {
+	it("maps graft_file_api to a signatures-only view of one file", async () => {
+		const harness = makeHarness({ result: { stdout: "src/app.ts\n  fn run(): void" } });
+		const { text, details } = await harness.exec("graft_file_api", { path: "src/app.ts" });
+		expect(harness.run.mock.calls[0]![1]).toEqual({ kind: "file-api", path: "src/app.ts" });
+		expect(text).toContain("fn run(): void");
+		expect(details.references).toEqual([]);
+	});
+
+	it("says so plainly when a file has no indexed signatures", async () => {
+		const harness = makeHarness({ result: { stdout: "  " } });
+		const { text } = await harness.exec("graft_file_api", { path: "src/missing.ts" });
+		expect(text).toContain("No indexed signatures for src/missing.ts");
+	});
+
+	it("defaults graft_trace_calls to the caller direction and forwards direction and depth", async () => {
+		const harness = makeHarness({ result: { stdout: "login · function · src/login.ts:L1-L4 · 2 in-edges" } });
+		await harness.exec("graft_trace_calls", { symbol: "verify" });
+		expect(harness.run.mock.calls[0]![1]).toEqual({
+			kind: "trace-calls",
+			symbol: "verify",
+			direction: "in",
+			depth: undefined,
+		});
+
+		await harness.exec("graft_trace_calls", { symbol: "verify", direction: "out", depth: 4 });
+		expect(harness.run.mock.calls[1]![1]).toEqual({
+			kind: "trace-calls",
+			symbol: "verify",
+			direction: "out",
+			depth: 4,
+		});
+	});
+
+	it("names the direction it searched when a trace found nothing", async () => {
+		const outgoing = makeHarness({ result: { stdout: "   " } });
+		const { text } = await outgoing.exec("graft_trace_calls", { symbol: "orphan", direction: "out" });
+		expect(text).toContain("No indexed callees for orphan");
+	});
+
+	it("passes graft_find_all flags through and reports an empty search as an answer", async () => {
+		const harness = makeHarness({ result: { stdout: "" } });
+		const { text } = await harness.exec("graft_find_all", {
+			pattern: "NEEDLE",
+			ignore_case: true,
+			fixed: true,
+			in: "src",
+		});
+		expect(harness.run.mock.calls[0]![1]).toEqual({
+			kind: "find-all",
+			pattern: "NEEDLE",
+			ignoreCase: true,
+			fixed: true,
+			in: "src",
+		});
+		expect(text).toContain("No matches for NEEDLE");
+	});
+
+	it("maps graft_repo_map to the token-budgeted orientation view", async () => {
+		const harness = makeHarness({ result: { stdout: "repo map — 113 files · 687 symbols" } });
+		const { text } = await harness.exec("graft_repo_map", { max_dirs: 8 });
+		expect(harness.run.mock.calls[0]![1]).toEqual({ kind: "repo-map", maxDirs: 8 });
+		expect(text).toContain("113 files");
+	});
+
+	it("says so when the repository map came back empty", async () => {
+		const harness = makeHarness({ result: { stdout: "" } });
+		const { text } = await harness.exec("graft_repo_map", {});
+		expect(text).toContain("empty repository map");
+	});
+});
+
+describe("graft_check_freshness", () => {
+	it("treats a non-zero exit as the drift answer rather than a tool failure", async () => {
+		const harness = makeHarness({ result: { code: 1, stdout: '{"stale":["src/a.ts"]}' } });
+		const { text, details } = await harness.exec("graft_check_freshness", {});
+		expect(text).toContain("has drifted");
+		expect(text).toContain("/graft build");
+		expect(details.exitCode).toBe(1);
+	});
+
+	it("reports an in-sync graph on exit zero", async () => {
+		const harness = makeHarness({ result: { code: 0, stdout: '{"stale":[]}' } });
+		const { text } = await harness.exec("graft_check_freshness", {});
+		expect(text).toContain("in sync with the working tree");
+	});
+
+	it("does not mark the graph fresh, because check never refreshes", async () => {
+		const harness = makeHarness({ result: { code: 0 } });
+		await harness.exec("graft_check_freshness", {});
+		expect(harness.noted).toHaveLength(0);
+	});
+
+	it("still fails on cancellation", async () => {
+		const harness = makeHarness({ result: { cancelled: true } });
+		await expect(harness.exec("graft_check_freshness", {})).rejects.toThrow(/cancelled/);
+	});
+});
+
+describe("renderAskResult", () => {
+	it("returns an explicit empty answer rather than blank text", () => {
+		const run: GraftRun = {
+			op: { kind: "find-code", question: "x" },
+			argv: ["graft", "ask", "x"],
+			cwd: "/repo",
+			code: 0,
+			stdout: "",
+			stderr: "",
+			killed: false,
+			cancelled: false,
+			timedOut: false,
+		};
+		expect(renderAskResult(run, { maxBytes: 4096, maxLines: 50 }).text).toBe("Graft returned no matching context.");
+	});
+});
+
+describe("read-only guarantee", () => {
+	it("never asks Graft to build or configure anything", async () => {
+		const harness = makeHarness();
+		const params: Record<string, Record<string, unknown>> = {
+			graft_find_code: { question: "anything" },
+			graft_file_api: { path: "src/a.ts" },
+			graft_trace_calls: { symbol: "x" },
+			graft_find_all: { pattern: "x" },
+			graft_repo_map: {},
+			graft_check_freshness: {},
+		};
+		for (const name of TOOL_NAMES) await harness.exec(name, params[name]!);
+
+		const kinds = harness.run.mock.calls.map((call) => (call[1] as GraftOp).kind);
+		expect(kinds).toEqual(["find-code", "file-api", "trace-calls", "find-all", "repo-map", "check-freshness"]);
+		expect(kinds).not.toContain("build");
+	});
+});

package/dist/extensions/pi-graft/tools.ts

@@ -0,0 +1,333 @@
+/**
+ * The six read-only Graft tools.
+ *
+ * Names and jobs deliberately mirror Graft's own MCP tool surface, so a model
+ * that already knows Graft needs no new vocabulary:
+ *
+ *   graft_find_code       → graft ask --source --json
+ *   graft_file_api        → graft skeleton <file>
+ *   graft_trace_calls     → graft callers <symbol> [--direction out] [-d N]
+ *   graft_find_all        → graft grep <regex> [--in P] [-i] [--fixed]
+ *   graft_repo_map        → graft map [--max-dirs N]
+ *   graft_check_freshness → graft check --json
+ *
+ * Every one of them is read-only under Selesai's capability model. Nothing here
+ * can build, mutate, install, or configure anything — the build operations live
+ * behind the consent-gated commands in `commands.ts`.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@selesai/code";
+import { Type } from "typebox";
+import {
+	askReferences,
+	boundText,
+	graftFailureMessage,
+	MAX_FIND_LIMIT,
+	MAX_TRACE_DEPTH,
+	parseAskJson,
+	renderAsk,
+	RESULT_MAX_BYTES,
+	RESULT_MAX_LINES,
+	type GraftOp,
+	type GraftReference,
+	type GraftRun,
+} from "./cli.ts";
+import type { GraftSettings, GraftState, GraftStateName } from "./state.ts";
+
+export const GRAFT_TOOL_NAMES = [
+	"graft_check_freshness",
+	"graft_file_api",
+	"graft_find_all",
+	"graft_find_code",
+	"graft_repo_map",
+	"graft_trace_calls",
+] as const;
+
+export interface GraftToolRuntime {
+	/** Run a read-only Graft operation against the resolved repository root. */
+	run(ctx: ExtensionContext, op: GraftOp, signal?: AbortSignal): Promise<GraftRun>;
+	settings(): GraftSettings;
+	state(): GraftState;
+	/** A query answered; the graph is fresh as of now. */
+	noteQuery(ctx: ExtensionContext, run: GraftRun): void;
+}
+
+/** Structured details attached to every Graft tool result. */
+export interface GraftToolDetails {
+	operation: string;
+	/** Full argv, for support reports and TUI expansion. */
+	argv: string[];
+	cwd: string;
+	exitCode: number;
+	graphState: GraftStateName;
+	bytes: number;
+	truncated: boolean;
+	truncatedBy: "lines" | "bytes" | null;
+	/** `file` or `file:Lx-Ly` pointers the result references. */
+	references: GraftReference[];
+	/** Command diagnostics. Kept out of model-facing text on purpose. */
+	stderr?: string;
+	mode?: string;
+	/** Share of the query terms the top hit matched (`ask` only). */
+	coverage?: number;
+	saved?: { files: number; baselineChars: number };
+}
+
+const GUIDELINES = [
+	"Use graft_find_code to locate the systems, files, and symbols relevant to a repository question before reading widely.",
+	"Use graft_trace_calls before changing a shared symbol, to see its callers (or, with direction out, what it depends on) and the blast radius.",
+	"Use graft_file_api to see a file's signatures without reading its implementation bodies.",
+	"Use graft_find_all for exhaustive regex discovery across indexed files, grouped by enclosing symbol.",
+	"Use graft_repo_map to orient in an unfamiliar repository, and graft_check_freshness when you need to know whether Graft context describes the code as it is now.",
+	"Graft results are derived and may be incomplete: verify anything you are about to change with read or grep, and treat Graft pointers as leads rather than proof.",
+];
+
+function throwIfFailed(run: GraftRun, allowNonZero = false): void {
+	if (run.cancelled) throw new Error("Graft command cancelled.");
+	if (run.code === 0 || allowNonZero) return;
+	throw new Error(graftFailureMessage(run));
+}
+
+function textResult(text: string, details: GraftToolDetails) {
+	return { content: [{ type: "text" as const, text }], details };
+}
+
+function baseDetails(run: GraftRun, state: GraftStateName): Omit<GraftToolDetails, "bytes" | "truncated" | "truncatedBy" | "references"> {
+	return {
+		operation: run.op.kind,
+		argv: run.argv,
+		cwd: run.cwd,
+		exitCode: run.code,
+		graphState: state,
+		...(run.stderr.trim() ? { stderr: run.stderr.trim().slice(0, 4000) } : {}),
+	};
+}
+
+/** `graft ask` renders from its JSON when it parses, and from stdout otherwise. */
+export function renderAskResult(
+	run: GraftRun,
+	limits: { maxBytes: number; maxLines: number },
+): { text: string; references: GraftReference[]; bounded: ReturnType<typeof boundText>; payload: ReturnType<typeof parseAskJson> } {
+	const payload = parseAskJson(run.stdout);
+	if (payload) {
+		const bounded = boundText(renderAsk(payload), limits);
+		return { text: bounded.text, references: askReferences(payload), bounded, payload };
+	}
+	const bounded = boundText(run.stdout, limits);
+	return { text: bounded.text || "Graft returned no matching context.", references: [], bounded, payload: undefined };
+}
+
+export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime): void {
+	const limits = () => {
+		const maxBytes = runtime.settings().maxResultBytes ?? RESULT_MAX_BYTES;
+		return { maxBytes, maxLines: RESULT_MAX_LINES };
+	};
+
+	const scoped = (explicit: string | undefined): string | undefined => explicit ?? runtime.settings().in;
+
+	pi.registerTool({
+		name: "graft_find_code",
+		label: "Graft: find code",
+		description:
+			"Find the code relevant to a natural-language question about this repository. Returns ranked graph nodes with exact file:line pointers and the source inlined at each hit, so it is usually the whole answer and no follow-up read is needed. Use it to orient before editing or to locate the systems a change touches. The result is a derived summary — verify with read before changing anything.",
+		promptSnippet: "Find repository code relevant to a question (ranked nodes, file:line, source inlined)",
+		promptGuidelines: GUIDELINES,
+		parameters: Type.Object({
+			question: Type.String({ description: "What you want to understand, in plain words." }),
+			limit: Type.Optional(
+				Type.Integer({ minimum: 1, maximum: MAX_FIND_LIMIT, description: "Max hits (default 8)." }),
+			),
+			in: Type.Optional(
+				Type.String({ description: "Narrow to one sub-project: a repository-relative path prefix." }),
+			),
+		}),
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const run = await runtime.run(
+				ctx,
+				{
+					kind: "find-code",
+					question: params.question,
+					limit: params.limit,
+					in: scoped(params.in),
+				},
+				signal,
+			);
+			throwIfFailed(run);
+			runtime.noteQuery(ctx, run);
+
+			const { text, references, bounded, payload } = renderAskResult(run, limits());
+			return textResult(text, {
+				...baseDetails(run, runtime.state().name),
+				bytes: Buffer.byteLength(text, "utf-8"),
+				truncated: bounded.truncated,
+				truncatedBy: bounded.truncatedBy,
+				references,
+				...(payload?.mode ? { mode: payload.mode } : {}),
+				...(payload?.coverage !== undefined ? { coverage: payload.coverage } : {}),
+				...(payload?.saved ? { saved: payload.saved } : {}),
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "graft_file_api",
+		label: "Graft: file API",
+		description:
+			"Show every signature in one file without the implementation bodies — the file's API surface for roughly a tenth of the tokens of reading it. Use it to learn what a file offers before deciding which bodies to read. Accepts a repository-relative path or a unique basename.",
+		promptSnippet: "Show one file's signatures without implementation bodies",
+		parameters: Type.Object({
+			path: Type.String({ description: "Repository-relative path, or a unique file basename." }),
+		}),
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const run = await runtime.run(ctx, { kind: "file-api", path: params.path }, signal);
+			throwIfFailed(run);
+			runtime.noteQuery(ctx, run);
+			const bounded = boundText(run.stdout, limits());
+			const text = bounded.text || `No indexed signatures for ${params.path}.`;
+			return textResult(text, {
+				...baseDetails(run, runtime.state().name),
+				bytes: Buffer.byteLength(text, "utf-8"),
+				truncated: bounded.truncated,
+				truncatedBy: bounded.truncatedBy,
+				references: [],
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "graft_trace_calls",
+		label: "Graft: trace calls",
+		description:
+			"Trace a symbol's call graph. Default direction is 'in': who calls, references, implements, or extends it — the blast radius of changing it. Direction 'out' answers the reverse: what the symbol itself calls, references, or imports. Raise depth to walk transitively. Use it before modifying shared behavior.",
+		promptSnippet: "Trace who calls a symbol, or what it calls (blast radius)",
+		parameters: Type.Object({
+			symbol: Type.String({ description: "Symbol name; a qualified name like Cache.get is supported." }),
+			direction: Type.Optional(
+				StringEnum(["in", "out"] as const, {
+					description: "in = callers/dependents (default); out = what this symbol depends on.",
+				}),
+			),
+			depth: Type.Optional(
+				Type.Integer({ minimum: 1, maximum: MAX_TRACE_DEPTH, description: "Transitive depth (default 1)." }),
+			),
+		}),
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const run = await runtime.run(
+				ctx,
+				{
+					kind: "trace-calls",
+					symbol: params.symbol,
+					direction: params.direction ?? "in",
+					depth: params.depth,
+				},
+				signal,
+			);
+			throwIfFailed(run);
+			runtime.noteQuery(ctx, run);
+			const bounded = boundText(run.stdout, limits());
+			const direction = params.direction ?? "in";
+			const text = bounded.text || `No indexed ${direction === "in" ? "callers" : "callees"} for ${params.symbol}.`;
+			return textResult(text, {
+				...baseDetails(run, runtime.state().name),
+				bytes: Buffer.byteLength(text, "utf-8"),
+				truncated: bounded.truncated,
+				truncatedBy: bounded.truncatedBy,
+				references: [],
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "graft_find_all",
+		label: "Graft: find all",
+		description:
+			"Exhaustive regex search over every indexed file, with hits grouped by the symbol that encloses them and ranked by how coupled that symbol is. Prefer it over a plain text search when a broad pattern needs semantic context, and over graft_find_code when you need every occurrence rather than a ranked few.",
+		promptSnippet: "Exhaustive regex search over indexed files, grouped by enclosing symbol",
+		parameters: Type.Object({
+			pattern: Type.String({ description: "Regular expression to search for." }),
+			ignore_case: Type.Optional(Type.Boolean({ description: "Case-insensitive matching." })),
+			fixed: Type.Optional(Type.Boolean({ description: "Treat the pattern as a literal string, not a regex." })),
+			in: Type.Optional(Type.String({ description: "Narrow to files at or under this path prefix." })),
+		}),
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const run = await runtime.run(
+				ctx,
+				{
+					kind: "find-all",
+					pattern: params.pattern,
+					ignoreCase: params.ignore_case,
+					fixed: params.fixed,
+					in: scoped(params.in),
+				},
+				signal,
+			);
+			throwIfFailed(run);
+			runtime.noteQuery(ctx, run);
+			const bounded = boundText(run.stdout, limits());
+			const text = bounded.text || `No matches for ${params.pattern} in the indexed files.`;
+			return textResult(text, {
+				...baseDetails(run, runtime.state().name),
+				bytes: Buffer.byteLength(text, "utf-8"),
+				truncated: bounded.truncated,
+				truncatedBy: bounded.truncatedBy,
+				references: [],
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "graft_repo_map",
+		label: "Graft: repo map",
+		description:
+			"Token-budgeted orientation for an unfamiliar repository: directory clusters with file and symbol counts, each directory's local hubs, and the repository's global hotspots, ranked by in-degree. Use it as a first look before narrower queries.",
+		promptSnippet: "Directory clusters, hubs, and hotspots for an unfamiliar repository",
+		parameters: Type.Object({
+			max_dirs: Type.Optional(Type.Integer({ minimum: 1, maximum: 60, description: "Directories to show." })),
+		}),
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const run = await runtime.run(ctx, { kind: "repo-map", maxDirs: params.max_dirs }, signal);
+			throwIfFailed(run);
+			runtime.noteQuery(ctx, run);
+			const bounded = boundText(run.stdout, limits());
+			const text = bounded.text || "Graft returned an empty repository map.";
+			return textResult(text, {
+				...baseDetails(run, runtime.state().name),
+				bytes: Buffer.byteLength(text, "utf-8"),
+				truncated: bounded.truncated,
+				truncatedBy: bounded.truncatedBy,
+				references: [],
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "graft_check_freshness",
+		label: "Graft: check freshness",
+		description:
+			"Report whether the local Graft graph has drifted from the code. Use it when an earlier Graft answer might predate an edit, or when you need to tell the user that repository context is stale. It never rebuilds anything — it is the drift report.",
+		promptSnippet: "Report whether the local Graft graph has drifted from the code",
+		parameters: Type.Object({}),
+		async execute(_id, _params, signal, _onUpdate, ctx) {
+			// `graft check` exits 1 when the graph has drifted. That is the answer,
+			// not a failure, so a non-zero exit is allowed here and interpreted below.
+			const run = await runtime.run(ctx, { kind: "check-freshness" }, signal);
+			throwIfFailed(run, true);
+
+			const inSync = run.code === 0;
+			const bounded = boundText(run.stdout, limits());
+			const headline = inSync
+				? "Graft graph is in sync with the working tree."
+				: "Graft graph has drifted from the working tree (or has not been built yet). Run /graft build to rebuild it; Graft queries still refresh the graph they read.";
+			const text = `${headline}\n\n${bounded.text}`.trim();
+
+			return textResult(text, {
+				...baseDetails(run, runtime.state().name),
+				bytes: Buffer.byteLength(text, "utf-8"),
+				truncated: bounded.truncated,
+				truncatedBy: bounded.truncatedBy,
+				references: [],
+			});
+		},
+	});
+}

package/dist/extensions/pi-graft/tsconfig.json

@@ -0,0 +1,16 @@
+{
+	"extends": "../../../tsconfig.base.json",
+	"compilerOptions": {
+		"noEmit": true,
+		"declaration": false,
+		"declarationMap": false,
+		"sourceMap": false,
+		"inlineSources": false,
+		"baseUrl": "../../..",
+		"paths": {
+			"@selesai/code": ["./dist/index.d.ts"],
+			"@earendil-works/pi-coding-agent": ["./dist/index.d.ts"]
+		}
+	},
+	"include": ["./**/*.ts"]
+}