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

package/src/context-briefing.ts

@@ -0,0 +1,227 @@
+import { randomUUID } from "node:crypto";
+import {
+	buildSessionContext,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type {
+	CODEX_CONTEXT_BRIEFING_TYPE,
+	CodexContextBriefing,
+	CodexContextBriefingHandler,
+} from "@howaboua/pi-codex-conversion/developer-messages";
+import { registerInferenceBriefing } from "./delivery.js";
+
+// Conversion projects this durable protocol in inference, compaction and native replay.
+const BRIEFING: typeof CODEX_CONTEXT_BRIEFING_TYPE = "codex-context-briefing";
+
+export function registerContextBriefing(
+	pi: ExtensionAPI,
+	name: string,
+	relevant: (ctx: ExtensionContext) => boolean,
+	record: CodexContextBriefingHandler,
+) {
+	const hosted = registerInferenceBriefing(pi, record);
+	const warned = new Set<string>();
+	pi.on("context_with_system", async (event, ctx) => {
+		await hosted.ready;
+		if (hosted.hosted()) return;
+		if (
+			hosted.outdated &&
+			relevant(ctx) &&
+			!warned.has(ctx.sessionManager.getSessionId())
+		) {
+			warned.add(ctx.sessionManager.getSessionId());
+			ctx.ui.notify(
+				`Update Codex Conversion and reload to preserve ${name} briefings through its context rollover and native replay. Native Pi briefings and other agent tools remain available.`,
+				"warning",
+			);
+		}
+		try {
+			await record(ctx, undefined, event.messages);
+			return { messages: projectNative(ctx, event.messages) };
+		} catch (error) {
+			ctx.abort();
+			throw error;
+		}
+	});
+}
+
+export function contextBriefingWindow(
+	ctx: ExtensionContext,
+	windowId?: string,
+) {
+	const branch = ctx.sessionManager.getBranch();
+	const compaction = branch.findLastIndex(
+		(entry) =>
+			entry.type === "compaction" &&
+			!(
+				entry.details &&
+				typeof entry.details === "object" &&
+				"strategy" in entry.details &&
+				entry.details.strategy === "codex-context-window"
+			),
+	);
+	const boundary = branch.findLastIndex(
+		(entry) =>
+			entry.type === "custom_message" &&
+			entry.customType === "codex-context-window" &&
+			entry.details &&
+			typeof entry.details === "object" &&
+			"contextManagement" in entry.details &&
+			entry.details.contextManagement &&
+			typeof entry.details.contextManagement === "object" &&
+			"kind" in entry.details.contextManagement &&
+			entry.details.contextManagement.kind === "window",
+	);
+	return compaction > boundary
+		? branch[compaction]!.id
+		: (windowId ?? ctx.sessionManager.getSessionId());
+}
+
+export function hasContextRollover(ctx: ExtensionContext): boolean {
+	return ctx.sessionManager.getBranch().some((entry) => {
+		if (entry.type === "compaction") return true;
+		if (
+			entry.type !== "custom_message" ||
+			entry.customType !== "codex-context-window" ||
+			!entry.details ||
+			typeof entry.details !== "object" ||
+			!("contextManagement" in entry.details)
+		)
+			return false;
+		const window = entry.details.contextManagement;
+		return Boolean(
+			window &&
+				typeof window === "object" &&
+				"kind" in window &&
+				window.kind === "window" &&
+				"windowNumber" in window &&
+				typeof window.windowNumber === "number" &&
+				window.windowNumber > 0,
+		);
+	});
+}
+
+export async function recordContextBriefing(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	owner: string,
+	key: string,
+	content: () => Promise<string | undefined>,
+) {
+	const saved = ctx.sessionManager
+		.getEntries()
+		.findLast(
+			(entry) =>
+				entry.type === "custom" &&
+				entry.customType === BRIEFING &&
+				readBriefing(entry.data).owner === owner &&
+				readBriefing(entry.data).key === key,
+		);
+	if (saved?.type === "custom") {
+		// Tree may select an ancestor before its metadata child. Reuse immutable bytes/ID.
+		if (
+			!ctx.sessionManager
+				.getBranch()
+				.some(
+					(entry) =>
+						entry.type === "custom" &&
+						entry.customType === BRIEFING &&
+						readBriefing(entry.data).owner === owner &&
+						readBriefing(entry.data).key === key,
+				)
+		)
+			pi.appendEntry(BRIEFING, readBriefing(saved.data));
+		return;
+	}
+	const value = await content();
+	if (value === undefined) return;
+	pi.appendEntry(BRIEFING, {
+		protocol: 1,
+		id: randomUUID(),
+		owner,
+		key,
+		content: value,
+	} satisfies CodexContextBriefing);
+}
+
+function projectNative(
+	ctx: ExtensionContext,
+	messages: NativeMessage[],
+): NativeMessage[] {
+	const entries = ctx.sessionManager.getBranch().map((entry) => {
+		if (entry.type !== "custom" || entry.customType !== BRIEFING) return entry;
+		const briefing = readBriefing(entry.data);
+		return {
+			...entry,
+			type: "custom_message" as const,
+			content: briefing.content,
+			display: false,
+			details: briefing,
+		};
+	});
+	const reconstructed = buildSessionContext(entries).messages;
+	const positions = new Map<string, number[]>();
+	messages.forEach((message, index) => {
+		const key = messageKey(message);
+		const indices = positions.get(key) ?? [];
+		indices.push(index);
+		positions.set(key, indices);
+	});
+	const insertions = new Map<number, NativeMessage[]>();
+	let pending: NativeMessage[] = [];
+	let last = messages[0]?.role === "system" ? 0 : -1;
+	const insert = (index: number) => {
+		if (!pending.length) return;
+		const position =
+			messages[0]?.role === "system" ? Math.max(1, index) : index;
+		insertions.set(position, [...(insertions.get(position) ?? []), ...pending]);
+		pending = [];
+	};
+	for (const message of reconstructed) {
+		const index = positions.get(messageKey(message))?.shift();
+		if (index !== undefined) {
+			insert(index);
+			last = index;
+		} else if (message.role === "custom" && message.customType === BRIEFING) {
+			pending.push(message);
+		}
+	}
+	insert(last + 1);
+	return messages
+		.flatMap((message, index) => [...(insertions.get(index) ?? []), message])
+		.concat(insertions.get(messages.length) ?? []);
+}
+
+type NativeMessage = ReturnType<typeof buildSessionContext>["messages"][number];
+function messageKey(message: NativeMessage) {
+	return JSON.stringify([
+		message.role,
+		message.timestamp,
+		message.role === "custom"
+			? message.customType === BRIEFING
+				? readBriefing(message.details).id
+				: message.customType
+			: message.role === "toolResult"
+				? message.toolCallId
+				: undefined,
+	]);
+}
+function readBriefing(value: unknown): CodexContextBriefing {
+	if (
+		!value ||
+		typeof value !== "object" ||
+		!("protocol" in value) ||
+		value.protocol !== 1 ||
+		!("id" in value) ||
+		typeof value.id !== "string" ||
+		!("owner" in value) ||
+		typeof value.owner !== "string" ||
+		!("key" in value) ||
+		typeof value.key !== "string" ||
+		!("content" in value) ||
+		typeof value.content !== "string"
+	)
+		throw new Error("Invalid saved context briefing");
+	return value as CodexContextBriefing;
+}

package/src/contract.ts

@@ -0,0 +1,189 @@
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import type { Static } from "typebox";
+import { Check } from "typebox/value";
+
+const BOARD_ACTIONS = [
+	"help",
+	"list_boards",
+	"create_channel",
+	"get_channels",
+	"post",
+	"list_threads",
+	"read_thread",
+	"read_post",
+	"search_posts",
+	"subscribe",
+	"unsubscribe",
+] as const;
+export const BoardParameters = Type.Object({
+	action: Type.Optional(StringEnum(BOARD_ACTIONS)),
+});
+const positive = Type.Optional(
+	Type.Integer({ minimum: 1, maximum: 0xffffffff }),
+);
+const string = Type.Optional(Type.String());
+const Request = Type.Object(
+	{
+		action: StringEnum(BOARD_ACTIONS),
+		channel_name: string,
+		new_channel_name: string,
+		thread_id: string,
+		message_id: string,
+		text: string,
+		query: string,
+		author: string,
+		target_agent: string,
+		after_message_id: string,
+		board_id: string,
+		cursor: string,
+		subscribe: Type.Optional(Type.Boolean()),
+		recent_first: Type.Optional(Type.Boolean()),
+		sort: Type.Optional(StringEnum(["created", "activity"])),
+		limit: positive,
+		max_chars_per_post: positive,
+		limit_chars: positive,
+		offset_chars: Type.Optional(
+			Type.Integer({ minimum: 0, maximum: 0xffffffff }),
+		),
+		agents_to_notify: Type.Optional(
+			Type.Array(Type.String(), { maxItems: 256 }),
+		),
+	},
+	{ additionalProperties: false },
+);
+export type BoardParams = Static<typeof Request>;
+export type BoardAction = BoardParams["action"];
+export const MUTATIONS = new Set<BoardAction>([
+	"create_channel",
+	"post",
+	"subscribe",
+	"unsubscribe",
+]);
+const paging = ["limit", "cursor"];
+const reads = ["board_id"];
+const fields: Record<BoardAction, string[]> = {
+	help: [],
+	list_boards: paging,
+	create_channel: ["channel_name", "subscribe"],
+	get_channels: ["query", "recent_first", ...paging, ...reads],
+	post: [
+		"text",
+		"channel_name",
+		"new_channel_name",
+		"thread_id",
+		"agents_to_notify",
+	],
+	list_threads: [
+		"channel_name",
+		"sort",
+		"recent_first",
+		"max_chars_per_post",
+		...paging,
+		...reads,
+	],
+	read_thread: ["thread_id", "max_chars_per_post", ...paging, ...reads],
+	read_post: ["message_id", "offset_chars", "limit_chars", ...reads],
+	search_posts: [
+		"channel_name",
+		"query",
+		"author",
+		"after_message_id",
+		"max_chars_per_post",
+		...paging,
+		...reads,
+	],
+	subscribe: ["channel_name", "thread_id", "target_agent"],
+	unsubscribe: ["channel_name", "thread_id", "target_agent"],
+};
+const requiredFields: Partial<Record<BoardAction, string[]>> = {
+	create_channel: ["channel_name"],
+	post: ["text"],
+	list_threads: ["channel_name"],
+	read_thread: ["thread_id"],
+	read_post: ["message_id"],
+};
+export function parseBoardRequest(value: unknown): BoardParams {
+	if (
+		value === undefined ||
+		(typeof value === "object" &&
+			value !== null &&
+			!Array.isArray(value) &&
+			Object.keys(value).length === 0)
+	)
+		return { action: "help" };
+	if (!Check(Request, value))
+		throw new Error("Invalid board request; call board help");
+	const request = { ...(value as BoardParams) };
+	const allowed = new Set(["action", ...fields[request.action]]);
+	if (Object.keys(request).some((field) => !allowed.has(field)))
+		throw new Error(`Unknown ${request.action} field; board_id is read-only`);
+	for (const field of requiredFields[request.action] ?? []) {
+		if (!(field in request)) throw new Error(`${field} is required`);
+	}
+	for (const field of [
+		"thread_id",
+		"message_id",
+		"after_message_id",
+		"board_id",
+	] as const) {
+		const id = request[field];
+		if (
+			id !== undefined &&
+			!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(
+				id,
+			)
+		)
+			throw new Error(`${field} must be a UUID`);
+		if (id !== undefined) request[field] = id.toLowerCase();
+	}
+	if (request.action === "post")
+		exactlyOne(request, ["channel_name", "new_channel_name", "thread_id"]);
+	if (request.action === "subscribe" || request.action === "unsubscribe")
+		exactlyOne(request, ["channel_name", "thread_id"]);
+	return request;
+}
+function exactlyOne(value: BoardParams, keys: (keyof BoardParams)[]) {
+	if (keys.filter((key) => value[key] !== undefined).length !== 1)
+		throw new Error(`Provide exactly one of ${keys.join(", ")}`);
+}
+export function required(value: string | undefined, field: string): string {
+	if (value === undefined) throw new Error(`${field} is required`);
+	return value;
+}
+export function agentPath(value: string, caller: string): string {
+	const path = value.startsWith("/") ? value : `${caller}/${value}`;
+	if (!/^\/root(?:\/[a-zA-Z0-9_-]+)*$/.test(path))
+		throw new Error("Invalid agent path");
+	return path;
+}
+export const boardHelp = {
+	actions: Object.fromEntries(
+		Object.entries(fields).map(([action, values]) => [
+			action,
+			values
+				.map(
+					(field) =>
+						`${field}${requiredFields[action as BoardAction]?.includes(field) ? "" : "?"}`,
+				)
+				.join(" "),
+		]),
+	),
+	rules: {
+		scope:
+			"Defaults to your tree; board_id browses history, never writes. list_boards discovers saved boards",
+		post: "text required; exactly one of channel_name, new_channel_name, thread_id. Thread ID is the first post ID. New channel subscribes author to first posts",
+		subscriptions:
+			"Exactly one of channel_name/thread_id; channel covers first posts, thread covers replies. target_agent defaults to you. Posting subscribes author to thread unless explicitly unsubscribed",
+		notify:
+			"agents_to_notify is one-time, excludes author; only running turns, no waking or offline notices",
+		agents:
+			"Use spawn's boardAgent; absolute /root/... or child path relative to you, not a pane or contextAgent",
+		paging:
+			"limit default20, cap50; cursor opaque, keep query/sort unchanged. Concurrent posts may shift pages",
+		order:
+			"Newest first; get_channels by activity, list_threads sort=created|activity. read_thread pages newest replies with root on every page",
+		text: "Case-insensitive substring search; max_chars_per_post default1000. read_post offsets count Unicode characters, limit_chars default20000. Continue at next_offset_chars<n_chars",
+		budget:
+			"Post cap64KiB, channel1-128 UTF-8 bytes without edge whitespace/control characters. Results cap8000 serialized UTF-8 bytes; reads may reduce limits, continue with returned cursor/offset",
+	},
+};

package/src/delivery.ts

@@ -0,0 +1,76 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+	CodexContextBriefingHandler,
+	CodexDeveloperCustomMessage,
+	CodexDeveloperMessageOptions,
+} from "@howaboua/pi-codex-conversion/developer-messages";
+
+type Delivery =
+	typeof import("@howaboua/pi-codex-conversion/developer-messages");
+let optionalDelivery: Promise<Delivery | undefined> | undefined;
+
+function loadDelivery() {
+	return (optionalDelivery ??= import(
+		"@howaboua/pi-codex-conversion/developer-messages"
+	).catch((error) => {
+		if (isMissingOptionalModule(error, "developer-messages")) return undefined;
+		throw error;
+	}));
+}
+
+export function isMissingOptionalModule(error: unknown, subpath: string) {
+	if (!(error instanceof Error) || !("code" in error)) return false;
+	const name = "@howaboua/pi-codex-conversion";
+	if (error.code === "ERR_PACKAGE_PATH_NOT_EXPORTED")
+		return (
+			error.message.includes(name) && error.message.includes(`./${subpath}`)
+		);
+	if (
+		error.code !== "ERR_MODULE_NOT_FOUND" &&
+		error.code !== "MODULE_NOT_FOUND"
+	)
+		return false;
+	const missing = error.message.match(
+		/Cannot find (?:package|module) ['"]([^'"]+)['"]/,
+	)?.[1];
+	return missing === name || missing === `${name}/${subpath}`;
+}
+
+let delivery: Delivery | undefined;
+export async function initializeDelivery() {
+	delivery = await loadDelivery();
+}
+
+export function registerInferenceBriefing(
+	pi: ExtensionAPI,
+	handler: CodexContextBriefingHandler,
+) {
+	let unregister: (() => void) | undefined;
+	const ready = loadDelivery().then((api) => {
+		delivery = api;
+		unregister = api?.registerCodexContextBriefing?.(pi, handler);
+	});
+	pi.on("session_shutdown", () => unregister?.());
+	return {
+		ready,
+		hosted: () => delivery?.hasCodexContextBriefingHost?.(pi) ?? false,
+		get outdated() {
+			return Boolean(delivery && !delivery.registerCodexContextBriefing);
+		},
+	};
+}
+
+export function sendPolicyMessage(
+	pi: ExtensionAPI,
+	message: CodexDeveloperCustomMessage,
+	options: CodexDeveloperMessageOptions,
+) {
+	if (delivery?.trySendCodexDeveloperCustomMessage?.(pi, message, options))
+		return;
+	pi.sendMessage(
+		message,
+		options.deliverAs === "nextTurn"
+			? { ...options, deliverAs: "steer" }
+			: options,
+	);
+}

package/src/identity.ts

@@ -0,0 +1,174 @@
+import { resolve } from "node:path";
+import { Type } from "@earendil-works/pi-ai";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { Static } from "typebox";
+import { Check } from "typebox/value";
+import { readBoardConfig } from "./config.js";
+
+const uuid = Type.String({ pattern: "^[a-f0-9-]{36}$" });
+export const BindingSchema = Type.Object(
+	{
+		protocol: Type.Literal(1),
+		boardId: uuid,
+		rootSessionId: uuid,
+		sessionId: uuid,
+		agentName: Type.String({ pattern: "^/root(?:/[a-zA-Z0-9_-]+)*$" }),
+		ownerFolder: Type.String({ minLength: 1 }),
+		databasePath: Type.String({ minLength: 1 }),
+		enabled: Type.Boolean(),
+		upstream: Type.Optional(Type.String({ minLength: 1 })),
+	},
+	{ additionalProperties: false },
+);
+export type BoardBinding = Static<typeof BindingSchema>;
+const ChildSchema = Type.Object({
+	parentSessionId: uuid,
+	binding: BindingSchema,
+	machine: Type.String(),
+	sessionFile: Type.String({ minLength: 1 }),
+});
+export type BoardChild = Static<typeof ChildSchema>;
+const BINDING = "shepherdr-board-binding";
+const MEMBER = "shepherdr-board-member";
+const CHILD = "shepherdr-board-child";
+const SETTING = "shepherdr-board-setting";
+const defaults = new WeakMap<ExtensionContext["sessionManager"], boolean>();
+export function setBoardDefault(ctx: ExtensionContext, enabled: boolean) {
+	defaults.set(ctx.sessionManager, enabled);
+}
+const REMOVED = "shepherdr-board-removed";
+const SettingSchema = Type.Object({
+	sessionId: uuid,
+	enabled: Type.Union([Type.Boolean(), Type.Null()]),
+});
+
+function sessionBoardSetting(ctx: ExtensionContext): boolean | undefined {
+	let enabled: boolean | undefined;
+	for (const entry of ctx.sessionManager.getEntries()) {
+		if (entry.type !== "custom" || entry.customType !== SETTING) continue;
+		if (!Check(SettingSchema, entry.data))
+			throw new Error("Invalid saved board setting");
+		const value = entry.data as Static<typeof SettingSchema>;
+		if (value.sessionId === ctx.sessionManager.getSessionId())
+			enabled = value.enabled ?? undefined;
+	}
+	return enabled;
+}
+
+export function saveBoardSetting(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	enabled: boolean | undefined,
+) {
+	pi.appendEntry(SETTING, {
+		sessionId: ctx.sessionManager.getSessionId(),
+		enabled: enabled ?? null,
+	});
+}
+
+export function rootBoardSetting(ctx: ExtensionContext) {
+	try {
+		const config = readBoardConfig(
+			resolve(ctx.sessionManager.getCwd()),
+			defaults.get(ctx.sessionManager),
+		);
+		const session = sessionBoardSetting(ctx);
+		return {
+			enabled: session ?? config.folder ?? config.global,
+			source:
+				session !== undefined
+					? "session"
+					: config.folder !== undefined
+						? "folder"
+						: "global default",
+		};
+	} catch (error) {
+		return {
+			enabled: false,
+			source: "invalid configuration",
+			error: String(error),
+		};
+	}
+}
+
+export function parseBinding(value: unknown): BoardBinding {
+	if (!Check(BindingSchema, value))
+		throw new Error("Invalid Shepherdr board binding");
+	return value as BoardBinding;
+}
+export function binding(ctx: ExtensionContext): BoardBinding {
+	const sessionId = ctx.sessionManager.getSessionId();
+	let saved: BoardBinding | undefined;
+	for (const entry of ctx.sessionManager.getEntries()) {
+		if (entry.type !== "custom" || entry.customType !== BINDING) continue;
+		const candidate = parseBinding(entry.data);
+		if (candidate.sessionId === sessionId) saved = candidate;
+	}
+	const ownerFolder = resolve(ctx.sessionManager.getCwd());
+	if (saved?.upstream) return saved;
+	return {
+		...(saved ?? {
+			protocol: 1,
+			sessionId,
+			rootSessionId: sessionId,
+			boardId: sessionId,
+			agentName: "/root",
+			ownerFolder,
+			databasePath: resolve(ownerFolder, ".pi", "agent-message-board.sqlite"),
+			enabled: false,
+		}),
+		enabled: rootBoardSetting(ctx).enabled,
+	};
+}
+export function saveBinding(pi: ExtensionAPI, value: BoardBinding) {
+	pi.appendEntry(BINDING, value);
+}
+export function members(ctx: ExtensionContext): BoardBinding[] {
+	const own = binding(ctx);
+	const found = new Map([[own.agentName, own]]);
+	for (const entry of ctx.sessionManager.getEntries()) {
+		if (entry.type === "custom" && entry.customType === REMOVED) {
+			const value = parseBinding(entry.data);
+			if (value.boardId === own.boardId) found.delete(value.agentName);
+			continue;
+		}
+		if (entry.type !== "custom" || entry.customType !== MEMBER) continue;
+		const value = parseBinding(entry.data);
+		if (value.rootSessionId === own.sessionId && value.boardId === own.boardId)
+			found.set(value.agentName, value);
+	}
+	return [...found.values()];
+}
+export function saveMember(pi: ExtensionAPI, value: BoardBinding) {
+	pi.appendEntry(MEMBER, value);
+}
+export function children(ctx: ExtensionContext): BoardChild[] {
+	const own = binding(ctx);
+	const found = new Map<string, BoardChild>();
+	for (const entry of ctx.sessionManager.getEntries()) {
+		if (entry.type === "custom" && entry.customType === REMOVED) {
+			const value = parseBinding(entry.data);
+			if (value.boardId === own.boardId) found.delete(value.agentName);
+			continue;
+		}
+		if (entry.type !== "custom" || entry.customType !== CHILD) continue;
+		if (!Check(ChildSchema, entry.data))
+			throw new Error("Invalid saved board child route");
+		const value = entry.data as BoardChild;
+		if (
+			value.parentSessionId === own.sessionId &&
+			value.binding.boardId === own.boardId
+		)
+			found.set(value.binding.agentName, value);
+	}
+	return [...found.values()];
+}
+export function saveChild(pi: ExtensionAPI, value: BoardChild) {
+	pi.appendEntry(CHILD, value);
+}
+export function removeMember(pi: ExtensionAPI, value: BoardBinding) {
+	pi.appendEntry(REMOVED, value);
+}