@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/extensions/session-bus/store.ts

@@ -0,0 +1,365 @@
+/**
+ * The file-backed store for one repository's session bus.
+ *
+ * Every session writes its own record, every message is its own file, and every
+ * claim is an exclusive-create file. That keeps concurrent Pi processes off one
+ * shared lock while still making the common operations atomic. The store knows
+ * nothing about models or UI; it only reads and writes validated JSON.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, link, readdir, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { asRecord, readJson } from "../../lib/config.ts";
+import { claimsConflict } from "./overlap.ts";
+import type { BusMessage, ClaimConflict, ClaimRecord, SessionRecord } from "./types.ts";
+import { INBOX_DIR_NAME, SESSIONS_DIR_NAME } from "../../lib/session-roster.ts";
+
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+
+export interface BusStoreOptions {
+	/** The repository bus directory, e.g. `<agent-dir>/session-bus/<key>`. */
+	dir: string;
+}
+
+export interface BusStore {
+	readonly dir: string;
+	ensure(): Promise<void>;
+	writeSession(record: SessionRecord): Promise<void>;
+	sessions(): Promise<SessionRecord[]>;
+	/** One session's record, or undefined when it is not on disk. */
+	session(id: string): Promise<SessionRecord | undefined>;
+	removeSession(id: string): Promise<void>;
+	writeMessage(target: string, message: BusMessage): Promise<void>;
+	/** Read a recipient's messages without consuming them, oldest first. */
+	peek(id: string, limit: number): Promise<BusMessage[]>;
+	inbox(id: string, limit: number): Promise<BusMessage[]>;
+	unread(id: string): Promise<number>;
+	claims(): Promise<ClaimRecord[]>;
+	claimAll(
+		paths: readonly string[],
+		owner: string,
+		ownerLabel: string,
+		at: number,
+	): Promise<{ claimed: string[]; conflicts: ClaimConflict[] }>;
+	release(path: string, owner: string): Promise<boolean>;
+	releaseAll(owner: string): Promise<string[]>;
+	prune(input: {
+		now: number;
+		activeIds: ReadonlySet<string>;
+		sessionTtlMs: number;
+		messageTtlMs: number;
+	}): Promise<void>;
+}
+
+/**
+ * Release each path through `release`, reporting the ones this session did not
+ * hold. One copy, because `release` and `leave` answer the same two lists, and a
+ * second loop is how the two answers drift.
+ */
+export async function releaseClaimed(
+	paths: readonly string[],
+	release: (path: string) => Promise<boolean>,
+): Promise<{ released: string[]; notOwned: string[] }> {
+	const released: string[] = [];
+	const notOwned: string[] = [];
+	for (const path of paths) {
+		if (await release(path)) released.push(path);
+		else notOwned.push(path);
+	}
+	return { released, notOwned };
+}
+
+const SHA = (value: string): string => createHash("sha256").update(value).digest("hex").slice(0, 32);
+
+function isSession(value: unknown): value is SessionRecord {
+	const entry = asRecord(value);
+	if (!entry) return false;
+	return (
+		typeof entry.id === "string" &&
+		typeof entry.label === "string" &&
+		typeof entry.pid === "number" &&
+		typeof entry.cwd === "string" &&
+		typeof entry.repoRoot === "string" &&
+		typeof entry.mode === "string" &&
+		typeof entry.startedAt === "number" &&
+		typeof entry.lastSeen === "number" &&
+		(entry.watching === undefined || isWatchingState(entry.watching))
+	);
+}
+
+/** The optional listening field, validated only when it is there. */
+function isWatchingState(value: unknown): boolean {
+	const entry = asRecord(value);
+	return entry !== undefined && typeof entry.armed === "boolean" && typeof entry.wake === "boolean";
+}
+
+function isMessage(value: unknown): value is BusMessage {
+	const entry = asRecord(value);
+	if (!entry) return false;
+	return (
+		typeof entry.id === "string" &&
+		typeof entry.from === "string" &&
+		typeof entry.fromLabel === "string" &&
+		typeof entry.to === "string" &&
+		typeof entry.toLabel === "string" &&
+		typeof entry.kind === "string" &&
+		typeof entry.text === "string" &&
+		typeof entry.at === "number" &&
+		(entry.paths === undefined || (Array.isArray(entry.paths) && entry.paths.every((path) => typeof path === "string")))
+	);
+}
+
+function isClaim(value: unknown): value is ClaimRecord {
+	const entry = asRecord(value);
+	if (!entry) return false;
+	return (
+		typeof entry.path === "string" &&
+		typeof entry.owner === "string" &&
+		typeof entry.ownerLabel === "string" &&
+		typeof entry.at === "number"
+	);
+}
+
+function readTyped<T>(path: string, guard: (value: unknown) => value is T): T | undefined {
+	const parsed = readJson(path);
+	return parsed !== undefined && guard(parsed) ? parsed : undefined;
+}
+
+async function writeJson(path: string, value: unknown): Promise<void> {
+	await mkdir(dirname(path), { recursive: true, mode: DIR_MODE });
+	const temp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+	await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf-8", mode: FILE_MODE });
+	try {
+		await rename(temp, path);
+	} catch {
+		// Windows cannot replace an existing file with rename; removing first keeps
+		// the write recoverable, and the window is only a heartbeat-sized race.
+		await rm(path, { force: true });
+		await rename(temp, path);
+	}
+}
+
+async function listFiles(dir: string): Promise<string[]> {
+	try {
+		return (await readdir(dir)).filter((name) => name.endsWith(".json")).sort();
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Drop a recipient's directory once it holds no files, so a bus does not keep
+ * one empty directory for every session that ever joined it. An inbox with mail
+ * stays, because a session's id survives a resume and its mail is still its own;
+ * non-recursive removal also loses the race to a message that lands meanwhile.
+ */
+async function dropIfEmpty(dir: string): Promise<void> {
+	const entries = await readdir(dir).catch(() => null);
+	if (!entries || entries.length > 0) return;
+	await rmdir(dir).catch(() => {});
+}
+
+/** Create a store rooted at one repository's bus directory. */
+export function createBusStore(options: BusStoreOptions): BusStore {
+	const { dir } = options;
+	const sessionsDir = join(dir, SESSIONS_DIR_NAME);
+	const inboxRoot = join(dir, INBOX_DIR_NAME);
+	const claimsDir = join(dir, "claims");
+
+	const sessionFile = (id: string): string => join(sessionsDir, `${SHA(id)}.json`);
+	const inboxDir = (id: string): string => join(inboxRoot, SHA(id));
+	const claimFile = (path: string): string => join(claimsDir, `${SHA(path)}.json`);
+
+	async function readSessions(): Promise<SessionRecord[]> {
+		const sessions: SessionRecord[] = [];
+		for (const name of await listFiles(sessionsDir)) {
+			const record = readTyped(join(sessionsDir, name), isSession);
+			if (record) sessions.push(record);
+		}
+		return sessions.sort((a, b) => b.lastSeen - a.lastSeen || a.label.localeCompare(b.label));
+	}
+
+	async function readMessages(id: string, limit: number, remove: boolean): Promise<BusMessage[]> {
+		const directory = inboxDir(id);
+		const messages: BusMessage[] = [];
+		for (const name of await listFiles(directory)) {
+			const path = join(directory, name);
+			const message = readTyped(path, isMessage);
+			if (message) messages.push(message);
+			if (remove || !message) await rm(path, { force: true });
+			if (messages.length >= limit) break;
+		}
+		return messages.sort((a, b) => a.at - b.at || a.id.localeCompare(b.id)).slice(0, limit);
+	}
+
+	async function readClaims(): Promise<ClaimRecord[]> {
+		const claims: ClaimRecord[] = [];
+		for (const name of await listFiles(claimsDir)) {
+			const claim = readTyped(join(claimsDir, name), isClaim);
+			if (claim) claims.push(claim);
+		}
+		return claims.sort((a, b) => a.path.localeCompare(b.path));
+	}
+
+	async function claimOne(
+		path: string,
+		owner: string,
+		ownerLabel: string,
+		at: number,
+	): Promise<{ claim: ClaimRecord; conflict?: ClaimRecord }> {
+		await mkdir(claimsDir, { recursive: true, mode: DIR_MODE });
+		const file = claimFile(path);
+		const claim: ClaimRecord = { path, owner, ownerLabel, at };
+		// Publish a written temp file instead of creating the claim and filling it
+		// afterwards: the link is the exclusive create, so no reader can observe a
+		// half-written claim and mistake it for a crashed owner's.
+		const temp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+		await writeFile(temp, `${JSON.stringify(claim, null, 2)}\n`, { encoding: "utf-8", mode: FILE_MODE });
+		try {
+			try {
+				await link(temp, file);
+				return { claim };
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			}
+			const existing = readTyped(file, isClaim);
+			if (existing) {
+				return existing.owner === owner ? { claim: existing } : { claim, conflict: existing };
+			}
+			// A claim file that does not parse is debris from before claims were
+			// published whole; clear it once so a stale path cannot block forever.
+			await rm(file, { force: true });
+			await link(temp, file);
+			return { claim };
+		} finally {
+			await rm(temp, { force: true });
+		}
+	}
+
+	async function releaseOne(path: string, owner: string): Promise<boolean> {
+		const file = claimFile(path);
+		const existing = readTyped(file, isClaim);
+		if (!existing || existing.owner !== owner) return false;
+		await rm(file, { force: true });
+		return true;
+	}
+
+	/**
+	 * Claim every path for one owner, or nothing.
+	 *
+	 * The pre-check reads the claims once and reports every blocking owner, so a
+	 * batch that cannot be satisfied touches no file. A create that loses a race
+	 * after the pre-check releases the paths this batch already took.
+	 */
+	async function claimAll(
+		paths: readonly string[],
+		owner: string,
+		ownerLabel: string,
+		at: number,
+	): Promise<{ claimed: string[]; conflicts: ClaimConflict[] }> {
+		const existing = await readClaims();
+		const conflicts: ClaimConflict[] = [];
+		for (const path of paths) {
+			for (const held of existing) {
+				if (held.owner !== owner && claimsConflict(path, held.path)) {
+					conflicts.push({ path, owner: held.owner, ownerLabel: held.ownerLabel });
+				}
+			}
+		}
+		if (conflicts.length > 0) return { claimed: [], conflicts };
+		const claimed: string[] = [];
+		for (const path of paths) {
+			const result = await claimOne(path, owner, ownerLabel, at);
+			if (result.conflict) {
+				for (const done of claimed) await releaseOne(done, owner);
+				const { owner: holder, ownerLabel: holderLabel } = result.conflict;
+				return { claimed: [], conflicts: [{ path, owner: holder, ownerLabel: holderLabel }] };
+			}
+			claimed.push(path);
+		}
+		return { claimed, conflicts: [] };
+	}
+
+	return {
+		dir,
+		async ensure() {
+			await Promise.all([
+				mkdir(sessionsDir, { recursive: true, mode: DIR_MODE }),
+				mkdir(inboxRoot, { recursive: true, mode: DIR_MODE }),
+				mkdir(claimsDir, { recursive: true, mode: DIR_MODE }),
+			]);
+		},
+
+		async writeSession(record) {
+			await writeJson(sessionFile(record.id), record);
+		},
+
+		sessions: readSessions,
+
+		session: async (id) => readTyped(sessionFile(id), isSession),
+
+		async removeSession(id) {
+			await rm(sessionFile(id), { force: true });
+			await dropIfEmpty(inboxDir(id));
+		},
+
+		async writeMessage(target, message) {
+			const directory = inboxDir(target);
+			await mkdir(directory, { recursive: true, mode: DIR_MODE });
+			await writeJson(join(directory, `${message.id}.json`), message);
+		},
+
+		peek: (id, limit) => readMessages(id, limit, false),
+
+		inbox: (id, limit) => readMessages(id, limit, true),
+
+		async unread(id) {
+			return (await listFiles(inboxDir(id))).length;
+		},
+
+		claims: readClaims,
+
+		claimAll,
+
+		release: releaseOne,
+
+		async releaseAll(owner) {
+			const released: string[] = [];
+			for (const claim of await readClaims()) {
+				if (claim.owner !== owner) continue;
+				await rm(claimFile(claim.path), { force: true });
+				released.push(claim.path);
+			}
+			return released;
+		},
+
+		async prune({ now: at, activeIds, sessionTtlMs, messageTtlMs }) {
+			// The caller's set can lag: a peer that joined and claimed since that read is
+			// live on disk, and its claims are its own. This read is the answer, so the
+			// set only adds to what it found rather than deciding who survives.
+			const live = new Set(activeIds);
+			for (const session of await readSessions()) {
+				if (at - session.lastSeen > sessionTtlMs) {
+					await rm(sessionFile(session.id), { force: true });
+					await dropIfEmpty(inboxDir(session.id));
+					live.delete(session.id);
+				} else {
+					live.add(session.id);
+				}
+			}
+			for (const claim of await readClaims()) {
+				if (!live.has(claim.owner)) await rm(claimFile(claim.path), { force: true });
+			}
+			for (const name of await readdir(inboxRoot).catch(() => [] as string[])) {
+				const directory = join(inboxRoot, name);
+				for (const file of await listFiles(directory)) {
+					const message = readTyped(join(directory, file), isMessage);
+					if (!message || at - message.at > messageTtlMs) await rm(join(directory, file), { force: true });
+				}
+				await dropIfEmpty(directory);
+			}
+		},
+	};
+}

package/extensions/session-bus/tools.ts

@@ -0,0 +1,192 @@
+/**
+ * The `session` tool.
+ *
+ * One action-shaped tool keeps the prompt surface small: status, send, inbox,
+ * claim, release, join. The runtime owns file I/O and lifecycle; this
+ * module only validates the action, calls the runtime, and hands the result to
+ * the shared presentation module — one collapsed line, or the board's rows on
+ * expand.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { errorResult, textResult } from "../../lib/tool-result.ts";
+import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
+import { formatClaim, formatInbox, formatJoin, formatRelease, formatSend, formatStatus } from "./format.ts";
+import { normalizeAction, TOOL_NAME } from "./protocol.ts";
+import type { SessionBus } from "./runtime.ts";
+import { collapsedLine, resultSections, SessionResult } from "./result.ts";
+import type { SessionDetails } from "./types.ts";
+
+export { TOOL_NAME };
+
+const SessionParams = Type.Object({
+	action: StringEnum(["status", "send", "inbox", "claim", "release", "join"] as const, {
+		description: "status, send, inbox, claim, release, or join.",
+	}),
+	to: Type.Optional(Type.String({ description: "Target session label/id, or * for an event broadcast." })),
+	text: Type.Optional(Type.String({ description: "Message text, at most 4000 characters." })),
+	kind: Type.Optional(
+		StringEnum(["message", "event", "ask", "handoff"] as const, {
+			description: "Message kind; defaults to message.",
+		}),
+	),
+	paths: Type.Optional(
+		Type.Array(Type.String(), { description: "Repository-relative file or directory paths to claim or release." }),
+	),
+	limit: Type.Optional(
+		Type.Integer({ minimum: 1, maximum: 50, description: "Inbox messages to consume (default 20)." }),
+	),
+	wake: Type.Optional(
+		Type.Boolean({
+			description: "With join: mail raises one turn per burst once the agent is idle; omitted waits for the next turn.",
+		}),
+	),
+	listen: Type.Optional(
+		Type.Boolean({
+			description: "With join: false joins without listening, so mail waits in the inbox until `inbox` reads it.",
+		}),
+	),
+	label: Type.Optional(
+		Type.String({ description: "With join: what other sessions call this one, e.g. `billing-lead`." }),
+	),
+});
+
+type SessionArgs = Static<typeof SessionParams>;
+
+/**
+ * The call line's subject: the verb, and what it acts on. `end` clipping keeps
+ * the verb readable, because the paths that follow are the detail, not the
+ * identity of the call.
+ */
+function callSubject(action: string, args: Record<string, unknown>): string {
+	if (action === "join") {
+		const label = typeof args.label === "string" ? args.label.trim() : "";
+		return label ? `join ${label}` : "join";
+	}
+	if (action === "send") {
+		const to = typeof args.to === "string" ? args.to : "";
+		return to ? `send ${to}` : "send";
+	}
+	if (action !== "claim" && action !== "release") return action;
+	const paths = Array.isArray(args.paths) ? args.paths.filter((path): path is string => typeof path === "string") : [];
+	const [first, ...rest] = paths;
+	if (first === undefined) return action;
+	return `${action} ${first}${rest.length > 0 ? ` +${rest.length}` : ""}`;
+}
+
+export function registerTools(pi: ExtensionAPI, bus: SessionBus): void {
+	pi.registerTool({
+		name: TOOL_NAME,
+		label: "Session bus",
+		description:
+			"Coordinate parallel Pi sessions on this repository. Actions: `status` (sessions, unread, claims), " +
+			"`send` (to a label/id, or `*` for an event), `inbox` (consume messages), `claim`/`release` (paths), " +
+			"`join` (get on the bus under a label, and listen for mail unless `listen: false`; `wake` raises a turn). " +
+			"Delivery is pull-based unless this session joined and is listening.",
+		promptSnippet: "Coordinate parallel sessions: status, send, inbox, claim, release, join.",
+		promptGuidelines: [
+			"Check `session inbox` when starting a coordinated turn.",
+			"Claim the paths you will edit before changing them; release them when done.",
+			'Send `kind: "event"` for contract, build, or test changes another session needs.',
+			"Never put credentials or secrets in a session-bus message.",
+		],
+		parameters: SessionParams,
+		annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const args = params as SessionArgs;
+			const action = normalizeAction(args.action);
+			if (!action) return errorResult("status", `unknown action "${String(args.action)}".`);
+			try {
+				await bus.start(ctx);
+				switch (action) {
+					case "status": {
+						const status = await bus.status();
+						return textResult(formatStatus(status), { action, status });
+					}
+					case "send": {
+						const result = await bus.send({
+							to: typeof args.to === "string" ? args.to : "",
+							text: typeof args.text === "string" ? args.text : "",
+							kind: args.kind,
+							paths: args.paths,
+						});
+						return textResult(formatSend(result.delivered, result.messageId), {
+							action,
+							delivered: result.delivered,
+							messageId: result.messageId,
+						});
+					}
+					case "inbox": {
+						const messages = await bus.inbox(args.limit);
+						return textResult(formatInbox(messages), { action, messages });
+					}
+					case "claim": {
+						const result = await bus.claim(args.paths);
+						return textResult(formatClaim(result.claimed, result.conflicts), {
+							action,
+							claimed: result.claimed,
+							conflicts: result.conflicts,
+						});
+					}
+					case "release": {
+						const result = await bus.release(args.paths);
+						return textResult(formatRelease(result.released, result.notOwned), {
+							action,
+							released: result.released,
+							notOwned: result.notOwned,
+						});
+					}
+					case "join": {
+						const label = typeof args.label === "string" ? args.label.trim() : "";
+						const joined = await bus.join({
+							...(label === "" ? {} : { label }),
+							...(args.wake === undefined ? {} : { wake: args.wake }),
+							...(args.listen === undefined ? {} : { listen: args.listen }),
+						});
+						// A label is the bus's name and Pi's session name in one act, so the footer,
+						// `/resume`, and the record a peer addresses agree. A bare join derives its
+						// label from the name Pi already shows and must not rename it back.
+						if (label !== "") pi.setSessionName(joined.label);
+						return textResult(formatJoin(joined.label, joined.watching), {
+							action,
+							label: joined.label,
+							watching: joined.watching,
+						});
+					}
+				}
+			} catch (error) {
+				return errorResult(action, error instanceof Error ? error.message : String(error));
+			}
+		},
+
+		renderCall(args, theme, context) {
+			const action = typeof args.action === "string" ? args.action : "session";
+			return callLine(theme, context.lastComponent, TOOL_NAME, callSubject(action, args as Record<string, unknown>));
+		},
+
+		renderResult(result, options, theme, context) {
+			const text = reuseText(context?.lastComponent);
+			const details = toolDetails<SessionDetails>(result.details);
+			const outcome = detailsOrLine(theme, result, options.expanded, details);
+			if ("line" in outcome) {
+				text.setText(outcome.line);
+				return text;
+			}
+			const value = outcome.details;
+			const sections = options.expanded ? resultSections(value) : undefined;
+			if (!sections) {
+				text.setText(collapsedLine(theme, value));
+				return text;
+			}
+			const view =
+				context?.lastComponent instanceof SessionResult ? context.lastComponent : new SessionResult(sections, theme);
+			view.setInput(sections, theme);
+			return view;
+		},
+	});
+}