pi-dev-team 0.2.0

package/extensions/dev-team/lib/hooks.ts

@@ -0,0 +1,350 @@
+/**
+ * Hook bridge: runs the upstream Claude Code hook scripts (hooks/*.py, wired by hooks/hooks.json)
+ * from pi events.
+ *
+ * Input contract (what the scripts read, see PORTING.md): one JSON object on stdin with
+ *   hook_event_name, session_id, cwd, transcript_path, tool_name, tool_input, tool_response, prompt
+ * Output contract:
+ *   exit 2                       -> block (reason = stdout + stderr)
+ *   exit 0 + JSON on stdout      -> hookSpecificOutput.updatedInput / additionalContext,
+ *                                   {"decision":"block","reason"}, permissionDecision "deny", systemMessage
+ *   exit 0 + text on stdout      -> advisory (context for SessionStart/UserPromptSubmit, tool-result note otherwise)
+ *   exit 0 + stderr only         -> user notice
+ *   anything else / timeout      -> ignored (fail-open), like Claude Code for non-2 exits
+ */
+import { spawn, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DEV_TEAM_SUBAGENT_TOOL } from "./agents.ts";
+import { type DevTeamConfig, isHookEnabled } from "./config.ts";
+
+export type ClaudeEvent =
+	| "SessionStart"
+	| "UserPromptSubmit"
+	| "PreToolUse"
+	| "PostToolUse"
+	| "Stop"
+	| "SubagentStop"
+	| "SessionEnd";
+
+export interface HookSpec {
+	event: ClaudeEvent;
+	matcher?: RegExp;
+	name: string;
+	script: string;
+}
+
+export interface HookRun {
+	name: string;
+	code: number | null;
+	stdout: string;
+	stderr: string;
+	timedOut: boolean;
+	json?: Record<string, unknown>;
+}
+
+export interface HookOutcome {
+	block?: string;
+	/** Advisory text meant for the model. */
+	advisories: string[];
+	/** Text meant only for the user. */
+	notices: string[];
+	updatedInput?: Record<string, unknown>;
+	runs: HookRun[];
+}
+
+/** pi tool name -> Claude Code tool name used by hooks.json matchers and hook scripts. */
+export const PI_TO_CLAUDE_TOOL: Record<string, string> = {
+	bash: "Bash",
+	read: "Read",
+	write: "Write",
+	edit: "Edit",
+	grep: "Grep",
+	find: "Glob",
+	ls: "LS",
+	skill: "Skill",
+	[DEV_TEAM_SUBAGENT_TOOL]: "Agent",
+	ask_user: "AskUserQuestion",
+	web_fetch: "WebFetch",
+};
+
+export function claudeToolName(piName: string): string {
+	return PI_TO_CLAUDE_TOOL[piName] ?? piName;
+}
+
+function abs(cwd: string, p: unknown): string | undefined {
+	if (typeof p !== "string" || !p) return undefined;
+	const expanded = p.startsWith("~/") ? path.join(process.env.HOME ?? "", p.slice(2)) : p;
+	return path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
+}
+
+/** Build Claude's tool_input from pi tool arguments. */
+export function toClaudeInput(piName: string, input: Record<string, unknown>, cwd: string): Record<string, unknown> {
+	switch (piName) {
+		case "write": {
+			const file = abs(cwd, input.path);
+			return { file_path: file, path: file, content: input.content };
+		}
+		case "edit": {
+			const file = abs(cwd, input.path);
+			const edits = Array.isArray(input.edits) ? (input.edits as { oldText?: string; newText?: string }[]) : [];
+			if (!edits.length && typeof input.oldText === "string") edits.push({ oldText: input.oldText as string, newText: input.newText as string });
+			return {
+				file_path: file,
+				path: file,
+				old_string: edits.map((e) => e.oldText ?? "").join("\n"),
+				new_string: edits.map((e) => e.newText ?? "").join("\n"),
+				replace_all: false,
+			};
+		}
+		case "read": {
+			const file = abs(cwd, input.path);
+			return { file_path: file, path: file, offset: input.offset, limit: input.limit };
+		}
+		case "grep":
+			return { pattern: input.pattern, path: abs(cwd, input.path) ?? cwd, glob: input.glob };
+		case "find":
+			return { pattern: input.pattern, path: abs(cwd, input.path) ?? cwd };
+		case "ls":
+			return { path: abs(cwd, input.path) ?? cwd };
+		case "bash":
+			return { command: input.command, timeout: input.timeout };
+		case "skill":
+			return { skill: input.name, name: input.name, args: input.args ?? "" };
+		case DEV_TEAM_SUBAGENT_TOOL:
+			return {
+				subagent_type: input.agent,
+				prompt: input.task,
+				description: input.description ?? "",
+				model: input.model,
+			};
+		default:
+			return { ...input };
+	}
+}
+
+/** Apply a hook's updatedInput (Claude field names) back onto pi arguments, for the fields that have a clear mapping. */
+export function applyUpdatedInput(piName: string, piInput: Record<string, unknown>, updated: Record<string, unknown>): void {
+	if (piName === "bash" && typeof updated.command === "string") piInput.command = updated.command;
+	if (piName === DEV_TEAM_SUBAGENT_TOOL) {
+		if (typeof updated.prompt === "string") piInput.task = updated.prompt;
+		if (typeof updated.additionalContext === "string" && typeof piInput.task === "string") {
+			piInput.task = `${piInput.task}\n\n${updated.additionalContext}`;
+		}
+	}
+	if ((piName === "write" || piName === "edit" || piName === "read") && typeof updated.file_path === "string") {
+		piInput.path = updated.file_path;
+	}
+	if (piName === "write" && typeof updated.content === "string") piInput.content = updated.content;
+}
+
+function compileMatcher(m: unknown): RegExp | undefined {
+	if (typeof m !== "string" || m === "" || m === "*") return undefined;
+	try {
+		return new RegExp(`^(?:${m})$`);
+	} catch {
+		return undefined;
+	}
+}
+
+export function loadHookSpecs(packageRoot: string): HookSpec[] {
+	const file = path.join(packageRoot, "hooks", "hooks.json");
+	let data: { hooks?: Record<string, { matcher?: string; hooks?: { command?: string }[] }[]> };
+	try {
+		data = JSON.parse(fs.readFileSync(file, "utf-8"));
+	} catch {
+		return [];
+	}
+	const specs: HookSpec[] = [];
+	for (const [event, groups] of Object.entries(data.hooks ?? {})) {
+		for (const group of groups ?? []) {
+			const matcher = compileMatcher(group.matcher);
+			for (const h of group.hooks ?? []) {
+				const scripts = [...String(h.command ?? "").matchAll(/hooks\/([\w.-]+\.py)/g)].map((m) => m[1]);
+				const script = scripts[scripts.length - 1];
+				if (!script) continue;
+				specs.push({
+					event: event as ClaudeEvent,
+					matcher,
+					name: script.replace(/\.py$/, ""),
+					script: path.join(packageRoot, "hooks", script),
+				});
+			}
+		}
+	}
+	return specs;
+}
+
+let cachedPython: string | null | undefined;
+export function resolvePython(): string | null {
+	if (cachedPython !== undefined) return cachedPython;
+	const candidates = [process.env.DEV_TEAM_PYTHON, "python3", "python"].filter((c): c is string => !!c);
+	for (const c of candidates) {
+		const r = spawnSync(c, ["-c", "import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)"], { stdio: "ignore" });
+		if (r.status === 0) {
+			cachedPython = c;
+			return c;
+		}
+	}
+	cachedPython = null;
+	return null;
+}
+
+export class HookBridge {
+	private specs: HookSpec[];
+	private readonly packageRoot: string;
+	private readonly getConfig: () => DevTeamConfig;
+	private readonly resolveInterpreter: () => string | null;
+
+	constructor(packageRoot: string, getConfig: () => DevTeamConfig, resolveInterpreter: () => string | null = resolvePython) {
+		this.packageRoot = packageRoot;
+		this.getConfig = getConfig;
+		this.resolveInterpreter = resolveInterpreter;
+		this.specs = loadHookSpecs(packageRoot);
+	}
+
+	/**
+	 * The Python interpreter hooks run with, probed on first use (resolvePython caches it): pi loads
+	 * extensions in invocations that never start a session, so the extension factory must not start
+	 * processes.
+	 */
+	get python(): string | null {
+		return this.resolveInterpreter();
+	}
+
+	get all(): HookSpec[] {
+		return this.specs;
+	}
+
+	/** @param target what hooks.json matchers test: the Claude tool name, or the SessionStart source. */
+	select(event: ClaudeEvent, target?: string): HookSpec[] {
+		const config = this.getConfig();
+		if (!this.python) return [];
+		const seen = new Set<string>();
+		return this.specs.filter((s) => {
+			if (s.event !== event) return false;
+			if (target !== undefined && s.matcher && !s.matcher.test(target)) return false;
+			if (!isHookEnabled(config, s.name)) return false;
+			// the same script registered twice for one event+tool (e.g. telemetry) runs once
+			const key = s.name;
+			if (seen.has(key)) return false;
+			seen.add(key);
+			return true;
+		});
+	}
+
+	private runOne(spec: HookSpec, payload: Record<string, unknown>, cwd: string, extraEnv: Record<string, string>): Promise<HookRun> {
+		const config = this.getConfig();
+		return new Promise((resolve) => {
+			const run: HookRun = { name: spec.name, code: null, stdout: "", stderr: "", timedOut: false };
+			let proc: ReturnType<typeof spawn>;
+			try {
+				proc = spawn(this.python as string, [spec.script], {
+					cwd: fs.existsSync(cwd) ? cwd : undefined,
+					env: {
+						...process.env,
+						...config.env,
+						CLAUDE_PLUGIN_ROOT: this.packageRoot,
+						CLAUDE_PROJECT_DIR: cwd,
+						...extraEnv,
+					},
+					stdio: ["pipe", "pipe", "pipe"],
+				});
+			} catch {
+				resolve(run);
+				return;
+			}
+			const timer = setTimeout(() => {
+				run.timedOut = true;
+				proc.kill("SIGKILL");
+			}, Math.max(1, config.hooks.timeoutSec) * 1000);
+			proc.stdout?.on("data", (d) => {
+				run.stdout += d.toString();
+			});
+			proc.stderr?.on("data", (d) => {
+				run.stderr += d.toString();
+			});
+			proc.on("error", () => {
+				clearTimeout(timer);
+				resolve(run);
+			});
+			proc.on("close", (code) => {
+				clearTimeout(timer);
+				run.code = code;
+				const trimmed = run.stdout.trim();
+				if (trimmed.startsWith("{")) {
+					try {
+						run.json = JSON.parse(trimmed);
+					} catch {
+						/* plain text */
+					}
+				}
+				resolve(run);
+			});
+			proc.stdin?.on("error", () => {});
+			proc.stdin?.end(JSON.stringify(payload));
+		});
+	}
+
+	/** Run one hook script by name regardless of hooks.json wiring or the disabled list (e.g. post_format). */
+	async runScript(name: string, event: ClaudeEvent, payload: Record<string, unknown>, cwd: string): Promise<HookOutcome> {
+		const script = path.join(this.packageRoot, "hooks", `${name}.py`);
+		if (!this.python || !fs.existsSync(script)) return { advisories: [], notices: [], runs: [] };
+		return this.execute([{ event, name, script }], event, payload, cwd, {});
+	}
+
+	async run(
+		event: ClaudeEvent,
+		payload: Record<string, unknown>,
+		cwd: string,
+		opts: { matchTarget?: string; extraEnv?: Record<string, string> } = {},
+	): Promise<HookOutcome> {
+		return this.execute(this.select(event, opts.matchTarget), event, payload, cwd, opts);
+	}
+
+	private async execute(
+		specs: HookSpec[],
+		event: ClaudeEvent,
+		payload: Record<string, unknown>,
+		cwd: string,
+		opts: { extraEnv?: Record<string, string> },
+	): Promise<HookOutcome> {
+		const outcome: HookOutcome = { advisories: [], notices: [], runs: [] };
+		if (!specs.length) return outcome;
+		const full = { hook_event_name: event, ...payload };
+		const runs = await Promise.all(specs.map((s) => this.runOne(s, full, cwd, opts.extraEnv ?? {})));
+		outcome.runs = runs;
+		const blocks: string[] = [];
+		for (const r of runs) {
+			if (r.timedOut) continue;
+			const out = r.stdout.trim();
+			const err = r.stderr.trim();
+			if (r.code === 2) {
+				const reason = [...new Set([out, err].filter(Boolean))].join("\n") || `${r.name} blocked this action.`;
+				blocks.push(`[${r.name}] ${reason}`);
+				continue;
+			}
+			if (r.code !== 0) continue;
+			if (r.json) {
+				const j = r.json;
+				const hso = (j.hookSpecificOutput ?? {}) as Record<string, unknown>;
+				if (hso.updatedInput && typeof hso.updatedInput === "object") {
+					outcome.updatedInput = { ...(outcome.updatedInput ?? {}), ...(hso.updatedInput as Record<string, unknown>) };
+				}
+				if (typeof hso.additionalContext === "string" && hso.additionalContext.trim()) {
+					outcome.advisories.push(`[${r.name}] ${hso.additionalContext.trim()}`);
+				}
+				const deny = hso.permissionDecision === "deny" || j.decision === "block";
+				const reason = (hso.permissionDecisionReason ?? j.reason ?? "") as string;
+				if (deny) blocks.push(`[${r.name}] ${reason || "blocked"}`);
+				if (typeof j.systemMessage === "string" && j.systemMessage.trim()) outcome.notices.push(j.systemMessage.trim());
+				if (err) outcome.notices.push(`[${r.name}] ${err}`);
+				continue;
+			}
+			if (out) outcome.advisories.push(`[${r.name}] ${out}`);
+			if (err) outcome.notices.push(`[${r.name}] ${err}`);
+		}
+		if (blocks.length) outcome.block = blocks.join("\n\n");
+		return outcome;
+	}
+}

package/extensions/dev-team/lib/metrics.ts

@@ -0,0 +1,115 @@
+/**
+ * Native replacements for the transcript-parsing hooks.
+ *
+ * - Cost meter (hooks/cost_meter.py + hooks/lib/cost_meter.py): appends one cumulative row per
+ *   agent run to .claude/metrics/cost-metering.jsonl with the upstream row shape, so /cost-report,
+ *   `cost_meter.py regression|pace` and /autoship --max-cost-usd keep working. Uses pi's own
+ *   usage.cost (correct for every provider, including GitHub Copilot) instead of a Claude-only
+ *   price table. Adds `session_id` (upstream could not, see run_report `joinable:false`).
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { costUsd, type PiUsage, sessionEntries, sessionSpend } from "./session-spend.ts";
+
+export function projectRoot(cwd: string): string {
+	const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8" });
+	const out = (r.stdout ?? "").trim();
+	return r.status === 0 && out ? out : cwd;
+}
+
+export function telemetryConsent(): boolean {
+	try {
+		const data = JSON.parse(fs.readFileSync(path.join(os.homedir(), ".claude", "telemetry.json"), "utf-8"));
+		return data?.enabled === true;
+	} catch {
+		return false;
+	}
+}
+
+type Bucket = {
+	input_tokens: number;
+	output_tokens: number;
+	cache_creation_input_tokens: number;
+	cache_read_input_tokens: number;
+	cost_usd: number;
+	messages: number;
+};
+
+const newBucket = (): Bucket => ({
+	input_tokens: 0,
+	output_tokens: 0,
+	cache_creation_input_tokens: 0,
+	cache_read_input_tokens: 0,
+	cost_usd: 0,
+	messages: 0,
+});
+
+function add(bucket: Bucket, u: PiUsage, messages: number): void {
+	bucket.input_tokens += u.input ?? 0;
+	bucket.output_tokens += u.output ?? 0;
+	bucket.cache_read_input_tokens += u.cacheRead ?? 0;
+	bucket.cache_creation_input_tokens += u.cacheWrite ?? 0;
+	bucket.cost_usd += costUsd(u);
+	bucket.messages += messages;
+}
+
+function slim(map: Record<string, Bucket>): Record<string, Omit<Bucket, "messages">> {
+	const out: Record<string, Omit<Bucket, "messages">> = {};
+	for (const [k, b] of Object.entries(map)) {
+		const { messages: _m, ...rest } = b;
+		out[k] = { ...rest, cost_usd: Math.round(rest.cost_usd * 1e6) / 1e6 };
+	}
+	return out;
+}
+
+/** Build the cumulative cost row for the whole session (every branch, like upstream's whole-transcript sum). */
+export function buildCostRow(ctx: ExtensionContext): Record<string, unknown> | undefined {
+	const total = newBucket();
+	const byModel: Record<string, Bucket> = {};
+	const byThread: Record<string, Bucket> = {};
+	const byAgent: Record<string, Bucket> = {};
+	const bump = (map: Record<string, Bucket>, key: string, u: PiUsage, n: number) => {
+		map[key] ??= newBucket();
+		add(map[key], u, n);
+	};
+	let any = false;
+	for (const run of sessionSpend(sessionEntries(ctx))) {
+		// Rows keep upstream's shape: model turns only, so pi's other usage entries (cache warming) stay out.
+		if (run.thread === "overhead") continue;
+		add(total, run.usage, run.messages);
+		bump(byModel, run.model, run.usage, run.messages);
+		bump(byThread, run.thread, run.usage, run.messages);
+		bump(byAgent, run.thread === "main" ? "main" : `dev-team:${run.agent}`, run.usage, run.messages);
+		any = true;
+	}
+	if (!any) return undefined;
+	const file = ctx.sessionManager.getSessionFile();
+	return {
+		timestamp: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+		transcript: file ? path.basename(file) : `${ctx.sessionManager.getSessionId()}.jsonl`,
+		session_id: ctx.sessionManager.getSessionId(),
+		total: { ...total, cost_usd: Math.round(total.cost_usd * 1e6) / 1e6 },
+		by_model: slim(byModel),
+		by_thread: slim(byThread),
+		by_agent_type: slim(byAgent),
+		unpriced_models: [],
+		source: "pi-dev-team",
+	};
+}
+
+export function recordCost(ctx: ExtensionContext): string | undefined {
+	if (process.env.DEV_TEAM_COST_METER === "off" || !telemetryConsent()) return undefined;
+	const row = buildCostRow(ctx);
+	if (!row) return undefined;
+	const file = path.join(projectRoot(ctx.cwd), ".claude", "metrics", "cost-metering.jsonl");
+	try {
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		fs.appendFileSync(file, `${JSON.stringify(row)}\n`, "utf-8");
+		return file;
+	} catch {
+		return undefined;
+	}
+}

package/extensions/dev-team/lib/safe-read.ts

@@ -0,0 +1,49 @@
+/**
+ * Bounded read of a file a repository may control (agent and skill markdown, settings and config
+ * JSON, a pull request body file). Anything that is not a regular file of at most `maxBytes` (a FIFO,
+ * /dev/zero, a device, a directory, a huge file) is skipped, so a repo cannot stall or exhaust the
+ * session. The type is checked before the file is opened, because opening a device or FIFO can have
+ * side effects. The open descriptor must still be the same regular file, so it cannot be swapped
+ * between the check and the read. The read stops after `maxBytes`, because some files (Linux /proc)
+ * report size 0 and yield far more. Symlinks are followed, so the target is what gets checked.
+ */
+import * as fs from "node:fs";
+
+export const MAX_REPO_FILE_BYTES = 1024 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+
+export type BoundedRead = { text: string } | { skipped: "too-large" | "not-a-file" | "unreadable" };
+
+/** Like readSmallFile, but says why a file was skipped. */
+export function readBoundedFile(file: string, maxBytes = MAX_REPO_FILE_BYTES): BoundedRead {
+	let fd: number | undefined;
+	try {
+		const pathStat = fs.statSync(file);
+		if (!pathStat.isFile()) return { skipped: "not-a-file" };
+		if (pathStat.size > maxBytes) return { skipped: "too-large" };
+		fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0) | (fs.constants.O_NOCTTY ?? 0));
+		const openStat = fs.fstatSync(fd);
+		if (!openStat.isFile() || openStat.dev !== pathStat.dev || openStat.ino !== pathStat.ino) return { skipped: "not-a-file" };
+		if (openStat.size > maxBytes) return { skipped: "too-large" };
+		const chunks: Buffer[] = [];
+		let total = 0;
+		for (;;) {
+			const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes + 1 - total));
+			const n = fs.readSync(fd, chunk, 0, chunk.length, null);
+			if (n === 0) break;
+			chunks.push(chunk.subarray(0, n));
+			total += n;
+			if (total > maxBytes) return { skipped: "too-large" };
+		}
+		return { text: Buffer.concat(chunks, total).toString("utf-8") };
+	} catch {
+		return { skipped: "unreadable" };
+	} finally {
+		if (fd !== undefined) fs.closeSync(fd);
+	}
+}
+
+export function readSmallFile(file: string, maxBytes = MAX_REPO_FILE_BYTES): string | undefined {
+	const result = readBoundedFile(file, maxBytes);
+	return "text" in result ? result.text : undefined;
+}

package/extensions/dev-team/lib/session-files.ts

@@ -0,0 +1,57 @@
+/**
+ * Files the port writes for a session: synthetic subagent transcripts (read by the SubagentStop hooks)
+ * and the complete output of a subagent whose result was cut. All of it lives in one private
+ * directory per pi process, created with mkdtemp (mode 0700, unpredictable name), so another local
+ * user cannot pre-create or redirect it in a shared temp directory. Files are created exclusively
+ * (`wx`). Everything is removed when pi quits; a reload, new, resumed or forked session keeps it, since
+ * tool results already in a session may point at these files.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+// Kept on globalThis so a /reload, which loads this module again, still finds and removes the same root.
+const ROOT_KEY = Symbol.for("pi-dev-team.session-files.root");
+const shared = globalThis as { [ROOT_KEY]?: string };
+
+/** The private root for this process, created on first use. `baseDir` is for tests. */
+function root(baseDir?: string): string {
+	if (baseDir) return baseDir;
+	shared[ROOT_KEY] ??= fs.mkdtempSync(path.join(os.tmpdir(), "pi-dev-team-"));
+	return shared[ROOT_KEY];
+}
+
+function safeSegment(value: string): string {
+	return value.replace(/[^\w.-]/g, "_").replace(/^\.+/, "_");
+}
+
+/** `<root>/<session>/<area>`, created owner-only. */
+export function sessionDir(sessionId: string, area: string, baseDir?: string): string {
+	const dir = path.join(root(baseDir), safeSegment(sessionId), safeSegment(area));
+	fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+	return dir;
+}
+
+/** Write a new file owner-only; never follows or overwrites an existing path. */
+export function writeSessionFile(sessionId: string, area: string, name: string, content: string, baseDir?: string): string {
+	const file = path.join(sessionDir(sessionId, area, baseDir), safeSegment(name));
+	fs.writeFileSync(file, content, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+	return file;
+}
+
+/** Remove everything this process wrote (idempotent; safe when nothing was written). */
+export function removeProcessFiles(baseDir?: string): void {
+	const base = baseDir ?? shared[ROOT_KEY];
+	if (!base) return;
+	fs.rmSync(base, { recursive: true, force: true });
+	if (!baseDir) delete shared[ROOT_KEY];
+}
+
+/** Keep a subagent's complete output when its result was cut; undefined if it cannot be saved. */
+export function saveFullOutput(sessionId: string, agent: string, agentId: string, output: string, baseDir?: string): string | undefined {
+	try {
+		return writeSessionFile(sessionId, "subagent-output", `${agent}-${agentId}.md`, output, baseDir);
+	} catch {
+		return undefined;
+	}
+}