@howaboua/pi-agent-board 0.0.0-stage → 0.0.1

package/src/activity.ts

@@ -0,0 +1,273 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	MessageRenderer,
+	SessionEntry,
+	Theme,
+} from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import type { BoardParams } from "./contract.js";
+
+const BOARD_POST_MARKER = "shepherdr-board-post-marker";
+
+export function recordBoardActivityMarker(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	params: BoardParams,
+	value: unknown,
+	requestId: string,
+): void {
+	const labels: Partial<Record<BoardParams["action"], string>> = {
+		create_channel: "Created board channel",
+		post: params.thread_id ? "Posted board reply" : "Created board thread",
+		read_thread: "Read board thread",
+		read_post: "Read board post",
+		list_boards: "Read board list",
+		get_channels: "Read board channels",
+		list_threads: "Read board threads",
+		search_posts: "Searched board posts",
+	};
+	const label = labels[params.action];
+	if (!label || !value || typeof value !== "object") return;
+	const result = value as Record<string, unknown>;
+	const root = result["root_post"];
+	const metadata =
+		root && typeof root === "object"
+			? (root as Record<string, unknown>)
+			: result;
+	const field = (key: string) =>
+		typeof metadata[key] === "string" ? metadata[key] : undefined;
+	if (
+		ctx.sessionManager
+			.getBranch()
+			.some(
+				(entry) =>
+					entry.type === "custom" &&
+					entry.customType === BOARD_POST_MARKER &&
+					entry.data &&
+					typeof entry.data === "object" &&
+					"requestId" in entry.data &&
+					entry.data.requestId === requestId,
+			)
+	)
+		return;
+	// Owner acknowledgements reach the sender here, never the subscription inbox.
+	pi.appendEntry(BOARD_POST_MARKER, {
+		operation: params.action,
+		label,
+		requestId,
+		boardId: params.board_id,
+		messageId: field("message_id") ?? params.message_id,
+		threadId: field("thread_id") ?? params.thread_id,
+		channelName:
+			field("channel_name") ?? params.channel_name ?? params.new_channel_name,
+	});
+}
+
+const BOARD_NOTICE = "shepherdr-board-post";
+const BOARD_CATCHUP = "shepherdr-board-catchup";
+
+interface BoardRow {
+	id: string;
+	label: string;
+	detail: () => string;
+}
+
+function boardRow(entry: SessionEntry): BoardRow | undefined {
+	if (
+		entry.type === "custom_message" &&
+		(entry.customType === BOARD_NOTICE || entry.customType === BOARD_CATCHUP)
+	) {
+		return {
+			id: entry.id,
+			label: "Board notice received",
+			detail: () =>
+				typeof entry.content === "string"
+					? entry.content
+					: JSON.stringify(entry.content),
+		};
+	}
+	if (entry.type === "custom" && entry.customType === BOARD_POST_MARKER) {
+		const data =
+			entry.data && typeof entry.data === "object"
+				? (entry.data as Record<string, unknown>)
+				: undefined;
+		const label =
+			typeof data?.["label"] === "string" ? data["label"] : "Board action";
+		const channel =
+			typeof data?.["channelName"] === "string" ? data["channelName"] : "";
+		return {
+			id: entry.id,
+			label: [label, channel]
+				.filter(Boolean)
+				.join(" · ")
+				.replace(/[\r\n\t\x00-\x1f\x7f]/g, " "),
+			detail: () => JSON.stringify(entry.data, null, 2) ?? "",
+		};
+	}
+	if (
+		entry.type === "message" &&
+		entry.message.role === "custom" &&
+		(entry.message.customType === BOARD_NOTICE ||
+			entry.message.customType === BOARD_CATCHUP)
+	) {
+		const content = entry.message.content;
+		return {
+			id: entry.id,
+			label: "Board notice received",
+			detail: () =>
+				typeof content === "string" ? content : JSON.stringify(content),
+		};
+	}
+	return undefined;
+}
+
+/** Project existing branch entries only. No new history or model delivery. */
+export function registerBoardActivityRenderer(pi: ExtensionAPI): void {
+	let sessionManager: ExtensionContext["sessionManager"] | undefined;
+	let generation = 0;
+	const restore = (_event: unknown, ctx: ExtensionContext) => {
+		sessionManager = ctx.sessionManager;
+		generation++;
+	};
+	pi.on("session_start", restore);
+	pi.on("session_tree", restore);
+	pi.on("session_compact", restore);
+	pi.on("session_shutdown", () => {
+		sessionManager = undefined;
+		cache = undefined;
+	});
+
+	interface BoardGroup {
+		rows: BoardRow[];
+		summary: string;
+		details?: string;
+	}
+	let cache:
+		| {
+				leaf: string | null;
+				generation: number;
+				groups: Map<string, BoardGroup>;
+				notices: Map<unknown, string>;
+		  }
+		| undefined;
+	const projection = () => {
+		const leaf = sessionManager?.getLeafId() ?? null;
+		if (cache?.leaf === leaf && cache.generation === generation) return cache;
+		const groups = new Map<string, BoardGroup>();
+		const notices = new Map<unknown, string>();
+		let rows: BoardRow[] = [];
+		let running = false;
+		const finish = () => {
+			if (!rows.length) return;
+			const counts = new Map<string, number>();
+			for (const row of rows)
+				counts.set(row.label, (counts.get(row.label) ?? 0) + 1);
+			const group: BoardGroup = {
+				rows,
+				summary:
+					"Board · " +
+					[...counts]
+						.map(([label, count]) => label + (count > 1 ? ` ×${count}` : ""))
+						.join(" · "),
+			};
+			for (const row of rows) groups.set(row.id, group);
+		};
+		for (const entry of sessionManager?.getBranch() ?? []) {
+			if (
+				entry.type === "message" &&
+				entry.message.role === "user" &&
+				!running
+			) {
+				finish();
+				rows = [];
+				running = true;
+			}
+			if (entry.type === "message" && entry.message.role === "assistant") {
+				const message = entry.message;
+				// Interrupted partial tool calls do not keep the next kickoff in this run.
+				running =
+					!["aborted", "error", "length"].includes(message.stopReason) &&
+					(message.stopReason === "toolUse" ||
+						message.content.some((block) => block.type === "toolCall"));
+			}
+			const row = boardRow(entry);
+			if (!row) continue;
+			rows.push(row);
+			if (entry.type === "custom_message") notices.set(entry.content, entry.id);
+			else if (entry.type === "message" && entry.message.role === "custom")
+				notices.set(entry.message.content, entry.id);
+		}
+		finish();
+		cache = { leaf, generation, groups, notices };
+		return cache;
+	};
+	const component = (
+		identity: string | { content: unknown },
+		expanded: boolean,
+		theme: Theme,
+		outputPad: number,
+		pending?: string,
+	) =>
+		new (class extends Text {
+			private readonly createdGeneration = generation;
+			private persisted = false;
+			override render(width: number): string[] {
+				if (!sessionManager) return [];
+				const padding = Math.min(
+					outputPad,
+					Math.max(0, Math.floor((width - 1) / 2)),
+				);
+				const contentWidth = Math.max(1, width - padding * 2);
+				const current = projection();
+				const ownId =
+					typeof identity === "string"
+						? identity
+						: current.notices.get(identity.content);
+				const group = ownId ? current.groups.get(ownId) : undefined;
+				if (group) this.persisted = true;
+				// Streamed custom messages can render before message_end persists them.
+				if (
+					!group &&
+					pending &&
+					!this.persisted &&
+					this.createdGeneration === generation
+				) {
+					this.setText(
+						theme.style(
+							truncateToWidth("Board · Notice received", contentWidth),
+							{ fg: "syntaxString", dim: true },
+						) + (expanded ? "\n" + pending : ""),
+					);
+					return super.render(width);
+				}
+				if (!group || group.rows.at(-1)?.id !== ownId) return [];
+				const heading = theme.style(
+					truncateToWidth(group.summary, contentWidth),
+					{ fg: "syntaxString", dim: true },
+				);
+				if (expanded)
+					group.details ??= group.rows
+						.map((row) => row.label + "\n" + row.detail())
+						.join("\n\n");
+				this.setText(heading + (expanded ? "\n" + group.details : ""));
+				return super.render(width);
+			}
+		})("", outputPad, 0);
+	// Pi's entry renderer contract does not expose outputPad; use its default inset.
+	pi.registerEntryRenderer(BOARD_POST_MARKER, (entry, { expanded }, theme) =>
+		component(entry.id, expanded, theme, 1),
+	);
+	const incoming: MessageRenderer = (message, { expanded, outputPad }, theme) =>
+		component(
+			{ content: message.content },
+			expanded,
+			theme,
+			outputPad,
+			typeof message.content === "string"
+				? message.content
+				: JSON.stringify(message.content),
+		);
+	pi.registerMessageRenderer(BOARD_NOTICE, incoming);
+	pi.registerMessageRenderer(BOARD_CATCHUP, incoming);
+}

package/src/archive.ts

@@ -0,0 +1,103 @@
+import { existsSync } from "node:fs";
+import type { BoardParams } from "./contract.js";
+import { agentPath, MUTATIONS } from "./contract.js";
+import type { BoardBinding } from "./identity.js";
+import { page } from "./paging.js";
+import { boundedBoardRead, checkMutationBudget } from "./response.js";
+
+export async function readSubscribedUpdates(
+	caller: BoardBinding,
+	seen: string[],
+) {
+	if (!existsSync(caller.databasePath)) return [];
+	const { BoardStore } = await import("./store.js");
+	const store = new BoardStore(caller.databasePath, false);
+	try {
+		return store.all<{ message_id: string; thread_id: string }>(
+			`SELECT p.id AS message_id,p.root AS thread_id FROM posts p
+			WHERE p.board_id=? AND p.author<>? AND NOT EXISTS
+			(SELECT 1 FROM json_each(?) WHERE value=p.id) AND EXISTS
+			(SELECT 1 FROM subscriptions s WHERE s.board_id=p.board_id
+			AND s.agent=? AND s.enabled=1 AND s.target=CASE WHEN p.id=p.root
+			THEN 'channel:'||p.channel ELSE 'thread:'||p.root END)
+			ORDER BY p.seq ASC LIMIT 50`,
+			caller.boardId,
+			caller.agentName,
+			JSON.stringify(seen),
+			caller.agentName,
+		);
+	} finally {
+		store.close();
+	}
+}
+
+export async function executeArchive(
+	caller: BoardBinding,
+	memberNames: readonly string[],
+	params: BoardParams,
+	requestId: string,
+) {
+	const write = MUTATIONS.has(params.action);
+	if (write) checkMutationBudget(caller.agentName, params);
+	let storage: typeof import("./store.js");
+	try {
+		storage = await import("./store.js");
+	} catch (error) {
+		if (
+			error instanceof Error &&
+			"code" in error &&
+			error.code === "ERR_UNKNOWN_BUILTIN_MODULE"
+		)
+			throw new Error(
+				"Message boards require Node.js 22.13 or newer with SQLite support",
+				{ cause: error },
+			);
+		throw error;
+	}
+	storage.validateMutation(params);
+	if (write) {
+		for (const value of [
+			...(params.agents_to_notify ?? []),
+			...(params.target_agent === undefined ? [] : [params.target_agent]),
+		]) {
+			const target = agentPath(value, caller.agentName);
+			if (!memberNames.includes(target))
+				throw new Error(`Agent not bound to this tree: ${target}`);
+		}
+	}
+	const exists = existsSync(caller.databasePath);
+	if (
+		!exists &&
+		params.action === "search_posts" &&
+		params.after_message_id !== undefined
+	)
+		throw new Error("Post not found in this board");
+	if (
+		!exists &&
+		(!write ||
+			(params.action !== "create_channel" &&
+				params.new_channel_name === undefined))
+	) {
+		if (["get_channels", "search_posts", "list_boards"].includes(params.action))
+			return { value: page([], params), recipients: [] };
+		throw new Error("This board has no channels or posts yet");
+	}
+	const store = new storage.BoardStore(caller.databasePath, write);
+	try {
+		const scope = {
+			boardId: caller.boardId,
+			rootSessionId: caller.rootSessionId,
+			ownerFolder: caller.ownerFolder,
+			callerSessionId: caller.sessionId,
+			agentName: caller.agentName,
+			members: memberNames,
+		};
+		return write
+			? store.execute(scope, params, requestId)
+			: boundedBoardRead(params, (request) =>
+					store.execute(scope, request, requestId),
+				);
+	} finally {
+		store.close();
+	}
+}

package/src/awareness.ts

@@ -0,0 +1,181 @@
+import { randomUUID } from "node:crypto";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { boardBriefing } from "./briefing.js";
+import {
+	contextBriefingWindow,
+	recordContextBriefing,
+	registerContextBriefing,
+} from "./context-briefing.js";
+import { binding } from "./identity.js";
+
+const OWNER = "shepherdr-board";
+const STATE = "shepherdr-board-awareness";
+interface AwarenessState {
+	sessionId: string;
+	signature: string;
+	epoch: string;
+}
+
+/** Board state is sampled once per selected window/membership, never on a timer. */
+export class BoardAwareness {
+	private readonly pi: ExtensionAPI;
+	private readonly read: (ctx: ExtensionContext) => Promise<unknown>;
+	private readonly availability: (
+		ctx: ExtensionContext,
+		error?: unknown,
+	) => void;
+	constructor(
+		pi: ExtensionAPI,
+		read: (ctx: ExtensionContext) => Promise<unknown>,
+		availability: (ctx: ExtensionContext, error?: unknown) => void,
+		privateBriefing: () => typeof boardBriefing | undefined,
+	) {
+		this.pi = pi;
+		this.read = read;
+		this.availability = availability;
+		this.privateBriefing = privateBriefing;
+		registerContextBriefing(
+			pi,
+			"board",
+			(ctx) => binding(ctx).enabled,
+			(ctx, windowId) => this.record(ctx, windowId),
+		);
+	}
+	private readonly privateBriefing: () => typeof boardBriefing | undefined;
+
+	refresh(ctx: ExtensionContext): AwarenessState {
+		const own = binding(ctx);
+		const signature = JSON.stringify([
+			own.boardId,
+			own.rootSessionId,
+			own.agentName,
+			own.upstream,
+			own.enabled,
+		]);
+		const saved = ctx.sessionManager
+			.getEntries()
+			.findLast(
+				(entry) =>
+					entry.type === "custom" &&
+					entry.customType === STATE &&
+					readState(entry.data).sessionId === own.sessionId,
+			);
+		if (saved?.type === "custom") {
+			const state = readState(saved.data);
+			if (state.signature === signature) return state;
+		}
+		const state = { sessionId: own.sessionId, signature, epoch: randomUUID() };
+		this.pi.appendEntry(STATE, state);
+		return state;
+	}
+	seen(ctx: ExtensionContext): string[] {
+		const own = binding(ctx);
+		return ctx.sessionManager.getEntries().flatMap((entry) => {
+			if (
+				entry.type !== "custom" ||
+				entry.customType !== "shepherdr-board-seen"
+			)
+				return [];
+			const data = entry.data as {
+				boardId?: string;
+				agentName?: string;
+				ids?: unknown;
+			};
+			return data?.boardId === own.boardId &&
+				data.agentName === own.agentName &&
+				Array.isArray(data.ids)
+				? data.ids.filter((id): id is string => typeof id === "string")
+				: [];
+		});
+	}
+	markSeen(ctx: ExtensionContext, ids: string[]) {
+		if (!ids.length) return;
+		const own = binding(ctx);
+		this.pi.appendEntry("shepherdr-board-seen", {
+			boardId: own.boardId,
+			agentName: own.agentName,
+			ids,
+		});
+	}
+	markRead(ctx: ExtensionContext, value: unknown) {
+		if (!value || typeof value !== "object") return;
+		const record = value as {
+			message_id?: unknown;
+			root_post?: unknown;
+			results?: unknown;
+		};
+		const posts = [
+			record,
+			record.root_post,
+			...(Array.isArray(record.results) ? record.results : []),
+		];
+		this.markSeen(
+			ctx,
+			posts.flatMap((post) =>
+				post &&
+				typeof post === "object" &&
+				"message_id" in post &&
+				typeof post.message_id === "string"
+					? [post.message_id]
+					: [],
+			),
+		);
+	}
+
+	private async record(ctx: ExtensionContext, windowId?: string) {
+		const own = binding(ctx);
+		const state = this.refresh(ctx);
+		if (!own.enabled) return;
+		const window = contextBriefingWindow(ctx, windowId);
+		const key = JSON.stringify([own.sessionId, window, state.epoch]);
+		await recordContextBriefing(this.pi, ctx, OWNER, key, async () => {
+			let population: "empty" | "populated" | "unavailable";
+			try {
+				const value = await this.read(ctx);
+				if (!binding(ctx).enabled) return;
+				if (
+					!value ||
+					typeof value !== "object" ||
+					!("results" in value) ||
+					!Array.isArray(value.results)
+				)
+					throw new Error("Invalid board population response");
+				population = value.results.length ? "populated" : "empty";
+				this.availability(ctx);
+			} catch (error) {
+				ctx.signal?.throwIfAborted();
+				population = "unavailable";
+				this.availability(ctx, error);
+			}
+			ctx.signal?.throwIfAborted();
+			if (!binding(ctx).enabled) return;
+			if (
+				binding(ctx).enabled !== own.enabled ||
+				this.refresh(ctx).epoch !== state.epoch
+			)
+				throw new Error("Board membership changed during its briefing");
+			return (this.privateBriefing() ?? boardBriefing)(
+				Boolean(own.upstream),
+				population,
+			);
+		});
+	}
+}
+
+function readState(value: unknown): AwarenessState {
+	if (
+		!value ||
+		typeof value !== "object" ||
+		!("sessionId" in value) ||
+		typeof value.sessionId !== "string" ||
+		!("signature" in value) ||
+		typeof value.signature !== "string" ||
+		!("epoch" in value) ||
+		typeof value.epoch !== "string"
+	)
+		throw new Error("Invalid saved board awareness");
+	return value as AwarenessState;
+}

package/src/briefing.ts

@@ -0,0 +1,19 @@
+export function boardBriefing(
+	member: boolean,
+	population: "empty" | "populated" | "unavailable",
+) {
+	const state =
+		population === "populated"
+			? "Read relevant board threads."
+			: population === "empty"
+				? "Shared board available; no posts yet."
+				: "Shared board status unavailable. Check board help and retry reading when available.";
+	return [
+		state,
+		member ? "The root agent owns setup; follow your assigned task." : "",
+		"Post only new information that changes another agent's work: ownership, decisions, findings or blockers. Reply in existing threads; link rather than repeat. Keep personal checkpoints in notes. Skip acknowledgements, routine status and duplicated completion reports.",
+		"Channels group shared workstreams; threads group topics. Reuse a relevant channel, not a catch-all. Create a channel only for a distinct coordination need, never just to announce a task or result.",
+	]
+		.filter(Boolean)
+		.join(" ");
+}

package/src/config.ts

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	realpathSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const CONFIG_FILE = "pi-shepherdr.json";
+export type BoardScope = "session" | "folder" | "global";
+
+function object(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readDocument(path: string): Record<string, unknown> {
+	if (!existsSync(path)) return {};
+	try {
+		const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!object(value)) throw new Error("configuration must be an object");
+		if (value["board"] !== undefined && !object(value["board"]))
+			throw new Error("board must be an object");
+		return value;
+	} catch (error) {
+		throw new Error(`Could not read ${path}: ${String(error)}`, {
+			cause: error,
+		});
+	}
+}
+
+function readEnabled(path: string, scope: "folder" | "global") {
+	const document = readDocument(path);
+	const board = object(document["board"]) ? document["board"] : {};
+	const field = scope === "global" ? "enabledGlobally" : "enabled";
+	const wrongField = scope === "global" ? "enabled" : "enabledGlobally";
+	if (wrongField in board)
+		throw new Error(`${path}: use board.${field} for ${scope} enablement`);
+	const value = board[field];
+	if (value !== undefined && typeof value !== "boolean")
+		throw new Error(`${path}: board.${field} must be a boolean`);
+	return value;
+}
+
+function boardConfigPaths(folder: string) {
+	// Keep aliases on one write target so atomic saves do not replace symlinks.
+	function configPath(directory: string) {
+		const path = resolve(directory, CONFIG_FILE);
+		return existsSync(path) ? realpathSync(path) : path;
+	}
+	const global = configPath(getAgentDir());
+	const local = configPath(resolve(folder, ".pi"));
+	return {
+		global,
+		// The global config is never also a folder config.
+		folder: local === global ? undefined : local,
+	};
+}
+
+export function readBoardConfig(folder: string, defaultEnabled = false) {
+	const paths = boardConfigPaths(folder);
+	const global = readEnabled(paths.global, "global");
+	return {
+		paths,
+		folder: paths.folder ? readEnabled(paths.folder, "folder") : undefined,
+		global: global ?? defaultEnabled,
+	};
+}
+
+export function writeBoardConfig(
+	folder: string,
+	scope: "folder" | "global",
+	enabled: boolean | undefined,
+) {
+	if (scope === "global" && enabled === undefined)
+		throw new Error("Global enablement must be on or off");
+	const path = boardConfigPaths(folder)[scope];
+	if (!path)
+		throw new Error(
+			"This folder's config is the global config; use a session override instead",
+		);
+	readEnabled(path, scope);
+	const document = readDocument(path);
+	const board = object(document["board"]) ? { ...document["board"] } : {};
+	const field = scope === "global" ? "enabledGlobally" : "enabled";
+	if (enabled === undefined) delete board[field];
+	else board[field] = enabled;
+	if (enabled === undefined && !existsSync(path)) return;
+	document["board"] = board;
+	mkdirSync(dirname(path), { recursive: true });
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, {
+			mode: 0o600,
+		});
+		renameSync(temporary, path);
+	} finally {
+		rmSync(temporary, { force: true });
+	}
+}