shared agents.md behavior

Author: ava-silver

pi/extensions/agents-md.ts

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { isReadToolResult, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const LOCAL_FILENAME = "AGENTS.local.md";
+const SUBDIRECTORY_FILENAME = "AGENTS.md";
+
+// Walk from cwd up to the filesystem root, collecting AGENTS.local.md files.
+// Ordered root-first, same as pi's own AGENTS.md discovery, so nearer files
+// take precedence when read top-to-bottom.
+export function findLocalAgentsFiles(cwd: string, projectTrusted: boolean): string[] {
+	if (!projectTrusted) return [];
+
+	const found: string[] = [];
+	let dir = cwd;
+	while (true) {
+		const candidate = join(dir, LOCAL_FILENAME);
+		if (existsSync(candidate)) found.push(candidate);
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return found.reverse();
+}
+
+export function findSubdirectoryAgentsFiles(cwd: string, readPath: string): string[] {
+	const root = resolve(cwd);
+	const target = resolve(root, readPath);
+	const pathFromRoot = relative(root, target);
+	if (pathFromRoot === ".." || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot)) return [];
+
+	const found: string[] = [];
+	let dir = dirname(target);
+	while (dir !== root) {
+		const candidate = join(dir, SUBDIRECTORY_FILENAME);
+		if (candidate !== target && existsSync(candidate)) found.push(candidate);
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return found.reverse();
+}
+
+export default function localAgentsMdExtension(pi: ExtensionAPI): void {
+	const loaded = new Set<string>();
+
+	pi.on("session_start", () => loaded.clear());
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		const files = findLocalAgentsFiles(ctx.cwd, ctx.isProjectTrusted());
+		if (files.length === 0) return;
+
+		const blocks = files.map((path) => {
+			const content = readFileSync(path, "utf8").trim();
+			return `<local_instructions path="${path}">\n${content}\n</local_instructions>`;
+		});
+
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n${blocks.join("\n\n")}`,
+		};
+	});
+
+	pi.on("tool_result", (event, ctx) => {
+		if (!isReadToolResult(event) || event.isError || !ctx.isProjectTrusted()) return;
+		const readPath = event.input.path;
+		if (typeof readPath !== "string") return;
+
+		const files = findSubdirectoryAgentsFiles(ctx.cwd, readPath).filter((path) => !loaded.has(path));
+		const blocks: string[] = [];
+		for (const path of files) {
+			try {
+				const content = readFileSync(path, "utf8").trim();
+				loaded.add(path);
+				blocks.push(`<subdirectory_instructions path="${path}">\n${content}\n</subdirectory_instructions>`);
+			} catch {}
+		}
+		if (blocks.length === 0) return;
+
+		return {
+			content: [...event.content, { type: "text", text: `\n\n${blocks.join("\n\n")}` }],
+		};
+	});
+}

pi/extensions/local-agents-md.ts

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext, ToolResultEvent } from "@earendil-works/pi-coding-agent";
+import localAgentsMdExtension, { findLocalAgentsFiles, findSubdirectoryAgentsFiles } from "../agents-md.ts";
+
+test("does not discover project-local instructions in an untrusted project", () => {
+	const root = mkdtempSync(join(tmpdir(), "local-agents-"));
+	try {
+		const nested = join(root, "project", "nested");
+		mkdirSync(nested, { recursive: true });
+		const parentFile = join(root, "project", "AGENTS.local.md");
+		const childFile = join(nested, "AGENTS.local.md");
+		writeFileSync(parentFile, "parent");
+		writeFileSync(childFile, "child");
+
+		assert.deepEqual(findLocalAgentsFiles(nested, true), [parentFile, childFile]);
+		assert.deepEqual(findLocalAgentsFiles(nested, false), []);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("discovers AGENTS.md files between the project root and a read file", () => {
+	const root = mkdtempSync(join(tmpdir(), "subdirectory-agents-"));
+	try {
+		const sourceDir = join(root, "nested", "child");
+		mkdirSync(sourceDir, { recursive: true });
+		const parentFile = join(root, "nested", "AGENTS.md");
+		const childFile = join(sourceDir, "AGENTS.md");
+		writeFileSync(parentFile, "parent");
+		writeFileSync(childFile, "child");
+
+		assert.deepEqual(findSubdirectoryAgentsFiles(root, join(sourceDir, "source.ts")), [parentFile, childFile]);
+		assert.deepEqual(findSubdirectoryAgentsFiles(root, join(root, "outside.ts")), []);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("adds newly discovered instructions to a read result once", () => {
+	const root = mkdtempSync(join(tmpdir(), "subdirectory-agents-"));
+	try {
+		const sourceDir = join(root, "nested");
+		mkdirSync(sourceDir);
+		writeFileSync(join(sourceDir, "AGENTS.md"), "Use bun test.");
+
+		let handler: ((event: ToolResultEvent, ctx: ExtensionContext) => unknown) | undefined;
+		localAgentsMdExtension({
+			on(event: string, callback: unknown) {
+				if (event === "tool_result") handler = callback as typeof handler;
+			},
+		} as ExtensionAPI);
+		const event = {
+			type: "tool_result",
+			toolCallId: "test",
+			toolName: "read",
+			input: { path: join(sourceDir, "source.ts") },
+			content: [{ type: "text", text: "source" }],
+			details: undefined,
+			isError: false,
+		} as ToolResultEvent;
+		const ctx = { cwd: root, isProjectTrusted: () => true } as ExtensionContext;
+
+		assert.ok(handler);
+		const result = handler(event, ctx) as { content: Array<{ type: "text"; text: string }> };
+		assert.match(result.content.at(-1)?.text ?? "", /Use bun test/);
+		assert.equal(handler(event, ctx), undefined);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});