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

package/src/integration.ts

@@ -0,0 +1,54 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { BoardBinding } from "./identity.js";
+import type { BoardEnvelope } from "./protocol.js";
+
+/** Optional membership transport. The runtime owns storage, settings and delivery. */
+export interface BoardAdapter {
+	briefing?(
+		member: boolean,
+		population: "empty" | "populated" | "unavailable",
+	): string;
+	request(
+		route: string,
+		request: BoardEnvelope,
+		signal?: AbortSignal,
+	): Promise<unknown>;
+	commitDirectory(
+		own: BoardBinding,
+		directory: BoardBinding[],
+		caller: BoardBinding,
+		request: Extract<
+			BoardEnvelope,
+			{ operation: "board-register" | "board-unregister" }
+		>,
+	): unknown;
+	routeNotice(
+		ctx: ExtensionContext,
+		request: Extract<BoardEnvelope, { operation: "board-notify" }>,
+		signal?: AbortSignal,
+	): Promise<unknown>;
+	propagateEnabled(ctx: ExtensionContext, enabled: boolean): Promise<void>;
+}
+
+export type { BoardScope } from "./config.js";
+export {
+	contextBriefingWindow,
+	hasContextRollover,
+	recordContextBriefing,
+	registerContextBriefing,
+} from "./context-briefing.js";
+export type { BoardBinding } from "./identity.js";
+export {
+	BindingSchema,
+	binding,
+	children,
+	members,
+	parseBinding,
+	removeMember,
+	rootBoardSetting,
+	saveBinding,
+	saveChild,
+	saveMember,
+} from "./identity.js";
+export type { BoardEnvelope } from "./protocol.js";
+export { isBoardEnvelope } from "./protocol.js";

package/src/paging.ts

@@ -0,0 +1,55 @@
+import type { BoardParams } from "./contract.js";
+
+export interface PostRecord {
+	message_id: string;
+	channel_name: string;
+	author: string;
+	thread_id: string;
+	created_at: string;
+	text: string;
+}
+export const POST_COLUMNS =
+	"id AS message_id,channel AS channel_name,author,root AS thread_id,created_at,text";
+export function metadata({ text: _text, ...value }: PostRecord) {
+	return value;
+}
+export function preview(post: PostRecord, chars: number) {
+	const text = Array.from(post.text);
+	return {
+		...metadata(post),
+		text_preview: text.slice(0, chars).join(""),
+		n_chars: text.length,
+		truncated: text.length > chars,
+	};
+}
+export function window(params: BoardParams) {
+	const limit = Math.min(params.limit ?? 20, 50);
+	let offset = 0;
+	if (params.cursor !== undefined) {
+		const bytes = Buffer.from(params.cursor, "base64url");
+		if (bytes.length !== 4 || bytes.toString("base64url") !== params.cursor)
+			throw new Error("Invalid cursor");
+		offset = bytes.readUInt32BE();
+	}
+	return { limit, offset };
+}
+export function page<T>(values: T[], params: BoardParams) {
+	const { limit, offset } = window(params);
+	const has_more = values.length > limit;
+	const results = values.slice(0, limit);
+	let next_cursor: string | null = null;
+	if (has_more) {
+		if (offset + results.length > 0xffffffff)
+			throw new Error("Cursor exceeds board limit");
+		const bytes = Buffer.alloc(4);
+		bytes.writeUInt32BE(offset + results.length);
+		next_cursor = bytes.toString("base64url");
+	}
+	return { results, n_returned: results.length, has_more, next_cursor };
+}
+export function budget(params: BoardParams, count: number) {
+	return Math.min(
+		params.max_chars_per_post ?? 1000,
+		Math.floor(20000 / Math.max(1, count)),
+	);
+}

package/src/protocol.ts

@@ -0,0 +1,78 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "typebox";
+import { Check } from "typebox/value";
+import { BindingSchema } from "./identity.js";
+
+const NoticeSchema = Type.Object(
+	{
+		message_id: Type.String(),
+		channel_name: Type.String(),
+		author: Type.String(),
+		thread_id: Type.String(),
+		created_at: Type.String(),
+		text_preview: Type.String({ maxLength: 300 }),
+		n_chars: Type.Integer({ minimum: 0 }),
+		truncated: Type.Boolean(),
+	},
+	{ additionalProperties: false },
+);
+const Protocol = Type.Union([
+	Type.Object({
+		operation: Type.Literal("board-catchup"),
+		caller: BindingSchema,
+		seen: Type.Array(Type.String()),
+	}),
+	Type.Object({
+		operation: Type.Literal("board-bind"),
+		binding: BindingSchema,
+	}),
+	Type.Object({
+		operation: Type.Literal("board-register"),
+		caller: BindingSchema,
+		member: BindingSchema,
+	}),
+	Type.Object({
+		operation: Type.Literal("board-unregister"),
+		caller: BindingSchema,
+		member: BindingSchema,
+	}),
+	Type.Object({
+		operation: Type.Literal("board-enabled"),
+		boardId: Type.String(),
+		enabled: Type.Boolean(),
+	}),
+	Type.Object({
+		operation: Type.Literal("board-active"),
+		caller: BindingSchema,
+		turnId: Type.Union([Type.String(), Type.Null()]),
+		previousTurnId: Type.Optional(Type.String()),
+	}),
+	Type.Object({
+		operation: Type.Literal("board-call"),
+		caller: BindingSchema,
+		params: Type.Unknown(),
+		requestId: Type.String(),
+	}),
+	Type.Object({
+		operation: Type.Literal("board-notify"),
+		boardId: Type.String(),
+		target: Type.String(),
+		sessionId: Type.String(),
+		turnId: Type.String(),
+		notice: NoticeSchema,
+	}),
+]);
+export type BoardEnvelope = Static<typeof Protocol>;
+export function parseEnvelope(value: unknown): BoardEnvelope {
+	if (!Check(Protocol, value)) throw new Error("Invalid board host request");
+	return value as BoardEnvelope;
+}
+export function isBoardEnvelope(value: unknown): boolean {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		"operation" in value &&
+		typeof value.operation === "string" &&
+		value.operation.startsWith("board-")
+	);
+}

package/src/queries.ts

@@ -0,0 +1,176 @@
+import { caseFold } from "unicode-case-folding";
+import { agentPath, type BoardParams, required } from "./contract.js";
+import {
+	budget,
+	metadata,
+	POST_COLUMNS,
+	type PostRecord,
+	page,
+	preview,
+	window,
+} from "./paging.js";
+import type { BoardStore } from "./store.js";
+
+export function queryBoard(
+	store: BoardStore,
+	ownBoard: string,
+	params: BoardParams,
+): Record<string, unknown> {
+	const board = params.board_id ?? ownBoard;
+	const { limit, offset } = window(params);
+	const order = params.recent_first === false ? "ASC" : "DESC";
+	if (params.action === "list_boards") {
+		const rows = store.all<{
+			board_id: string;
+			root_session_id: string;
+			owner_folder: string;
+			created_at: string;
+			last_activity_at: string;
+			channel_count: number;
+			message_count: number;
+		}>(
+			`SELECT b.*,
+		COALESCE((SELECT MAX(created_at) FROM posts p WHERE p.board_id=b.board_id),(SELECT MAX(created_at) FROM channels c WHERE c.board_id=b.board_id),b.created_at) AS last_activity_at,
+		(SELECT COUNT(*) FROM channels c WHERE c.board_id=b.board_id) AS channel_count,
+		(SELECT COUNT(*) FROM posts p WHERE p.board_id=b.board_id) AS message_count
+		FROM boards b ORDER BY last_activity_at DESC,board_id DESC LIMIT ? OFFSET ?`,
+			limit + 1,
+			offset,
+		);
+		return page(
+			rows.map((row) => ({ ...row, current: row.board_id === ownBoard })),
+			params,
+		);
+	}
+	if (params.action === "get_channels") {
+		const rows = store.all<{ name: string }>(
+			`SELECT name FROM channels c WHERE board_id=? AND instr(name_search,?)>0 ORDER BY
+		COALESCE((SELECT MAX(created_at) FROM posts p WHERE p.board_id=c.board_id AND p.channel=c.name),c.created_at) ${order},name ${order} LIMIT ? OFFSET ?`,
+			board,
+			caseFold(params.query ?? ""),
+			limit + 1,
+			offset,
+		);
+		return page(
+			rows.map(({ name }) => store.channel(board, name)),
+			params,
+		);
+	}
+	if (params.action === "read_post") {
+		const post = store.post(board, required(params.message_id, "message_id"));
+		const chars = Array.from(post.text);
+		const offset = Math.min(params.offset_chars ?? 0, chars.length);
+		const text = chars
+			.slice(offset, offset + Math.min(params.limit_chars ?? 20000, 20000))
+			.join("");
+		return {
+			...metadata(post),
+			text,
+			n_chars: chars.length,
+			next_offset_chars: offset + Array.from(text).length,
+		};
+	}
+	if (params.action === "read_thread") {
+		const root = store.root(board, required(params.thread_id, "thread_id"));
+		const replies = store.all<PostRecord>(
+			`SELECT ${POST_COLUMNS} FROM posts WHERE board_id=? AND root=? AND id<>root ORDER BY created_at DESC,seq DESC LIMIT ? OFFSET ?`,
+			board,
+			root.message_id,
+			limit + 1,
+			offset,
+		);
+		const chars = budget(params, Math.min(replies.length, limit) + 1);
+		return {
+			root_post: preview(root, chars),
+			...page(
+				replies.map((post) => preview(post, chars)),
+				params,
+			),
+		};
+	}
+	if (params.action === "list_threads") {
+		const channel = store.channel(
+			board,
+			required(params.channel_name, "channel_name"),
+		);
+		const sort =
+			params.sort === "activity"
+				? "(SELECT MAX(created_at) FROM posts r WHERE r.board_id=p.board_id AND r.root=p.id)"
+				: "p.created_at";
+		const roots = store.all<PostRecord>(
+			`SELECT ${POST_COLUMNS} FROM posts p WHERE board_id=? AND channel=? AND id=root ORDER BY ${sort} ${order},seq ${order} LIMIT ? OFFSET ?`,
+			board,
+			channel.channel_name,
+			limit + 1,
+			offset,
+		);
+		const chars = budget(params, 2 * Math.min(roots.length, limit));
+		return page(
+			roots.map((root) => {
+				const reply = store.one<PostRecord>(
+					`SELECT ${POST_COLUMNS} FROM posts WHERE board_id=? AND root=? AND id<>root ORDER BY created_at DESC,seq DESC LIMIT 1`,
+					board,
+					root.message_id,
+				);
+				const count =
+					store.one<{ n: number }>(
+						"SELECT COUNT(*) AS n FROM posts WHERE board_id=? AND root=? AND id<>root",
+						board,
+						root.message_id,
+					)?.n ?? 0;
+				return {
+					thread_id: root.message_id,
+					root_post: preview(root, chars),
+					reply_count: count,
+					last_activity_at:
+						reply && reply.created_at > root.created_at
+							? reply.created_at
+							: root.created_at,
+					latest_reply: reply ? preview(reply, chars) : null,
+				};
+			}),
+			params,
+		);
+	}
+	if (params.action === "search_posts") return search(store, board, params);
+	throw new Error(`Unsupported board read: ${params.action}`);
+}
+
+function search(store: BoardStore, board: string, params: BoardParams) {
+	const { limit, offset } = window(params);
+	const clauses = ["board_id=?"];
+	const args: (string | number)[] = [board];
+	if (params.channel_name !== undefined) {
+		clauses.push("channel=?");
+		args.push(params.channel_name);
+	}
+	if (params.author !== undefined) {
+		clauses.push("author=?");
+		args.push(agentPath(params.author, "/root"));
+	}
+	if (params.query !== undefined) {
+		clauses.push("instr(body_search,?)>0");
+		args.push(caseFold(params.query));
+	}
+	if (params.after_message_id !== undefined) {
+		const after = store.one<{ created_at: string; seq: number }>(
+			"SELECT created_at,seq FROM posts WHERE board_id=? AND id=?",
+			board,
+			params.after_message_id,
+		);
+		if (!after) throw new Error("Post not found in this board");
+		clauses.push("(created_at,seq)>(?,?)");
+		args.push(after.created_at, after.seq);
+	}
+	const posts = store.all<PostRecord>(
+		`SELECT ${POST_COLUMNS} FROM posts WHERE ${clauses.join(" AND ")} ORDER BY created_at DESC,seq DESC LIMIT ? OFFSET ?`,
+		...args,
+		limit + 1,
+		offset,
+	);
+	const chars = budget(params, Math.min(posts.length, limit));
+	return page(
+		posts.map((post) => preview(post, chars)),
+		params,
+	);
+}

package/src/response.ts

@@ -0,0 +1,56 @@
+import type { BoardParams } from "./contract.js";
+
+// Includes UTF-8 text, JSON escaping and metadata, in every tool mode.
+const MAX_RESPONSE_BYTES = 8000;
+
+export function serializeBoardResult(value: unknown): string {
+	const text = JSON.stringify(value);
+	if (Buffer.byteLength(text) > MAX_RESPONSE_BYTES)
+		throw new Error(
+			"Result exceeds the output budget. Reduce limit or max_chars_per_post; use read_post with a smaller limit_chars for long posts.",
+		);
+	return text;
+}
+
+export function checkMutationBudget(caller: string, params: BoardParams) {
+	// Native acknowledgement reserve, checked before opening or creating storage.
+	const target = params.target_agent ?? "";
+	if (
+		2048 + Buffer.byteLength(caller) + Buffer.byteLength(target) >
+		MAX_RESPONSE_BYTES
+	)
+		throw new Error(
+			"Output budget is too small to acknowledge a message-board mutation; no change was made.",
+		);
+}
+
+export function boundedBoardRead<T extends { value: unknown }>(
+	params: BoardParams,
+	fetch: (request: BoardParams) => T,
+): T {
+	const limit = Math.min(params.limit ?? 20, 50);
+	const chars = Math.min(params.max_chars_per_post ?? 1000, 20000);
+	const postChars = Math.min(params.limit_chars ?? 20000, 20000);
+	const previews = ["list_threads", "search_posts", "read_thread"].includes(
+		params.action,
+	);
+	const post = params.action === "read_post";
+	const largest = post ? postChars : previews ? Math.max(limit, chars) : limit;
+	for (let scale = 1; ; scale *= 2) {
+		const reduced = (value: number) => Math.max(1, Math.floor(value / scale));
+		// Reissue the original cursor/offset so continuation matches the reduced page.
+		const result = fetch({
+			...params,
+			...(post
+				? { limit_chars: reduced(postChars) }
+				: { limit: reduced(limit) }),
+			...(previews ? { max_chars_per_post: reduced(chars) } : {}),
+		});
+		if (Buffer.byteLength(JSON.stringify(result.value)) <= MAX_RESPONSE_BYTES)
+			return result;
+		if (Math.floor(largest / scale) <= 1)
+			throw new Error(
+				"The output budget is too small for this result's metadata.",
+			);
+	}
+}