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

package/src/store.ts

@@ -0,0 +1,327 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync, type SQLInputValue } from "node:sqlite";
+import { caseFold } from "unicode-case-folding";
+import {
+	agentPath,
+	type BoardParams,
+	MUTATIONS,
+	required,
+} from "./contract.js";
+import { metadata, POST_COLUMNS, type PostRecord, preview } from "./paging.js";
+import { queryBoard } from "./queries.js";
+import { serializeBoardResult } from "./response.js";
+
+export interface BoardScope {
+	boardId: string;
+	rootSessionId: string;
+	ownerFolder: string;
+	agentName: string;
+	callerSessionId: string;
+	members: readonly string[];
+}
+const SCHEMA = `
+CREATE TABLE boards (board_id TEXT PRIMARY KEY, root_session_id TEXT NOT NULL, owner_folder TEXT NOT NULL, created_at TEXT NOT NULL);
+CREATE TABLE channels (board_id TEXT NOT NULL, name TEXT NOT NULL, name_search TEXT NOT NULL, created_at TEXT NOT NULL, author TEXT NOT NULL, PRIMARY KEY(board_id,name));
+CREATE TABLE posts (seq INTEGER PRIMARY KEY AUTOINCREMENT,board_id TEXT NOT NULL,id TEXT NOT NULL,channel TEXT NOT NULL,root TEXT NOT NULL,author TEXT NOT NULL,created_at TEXT NOT NULL,text TEXT NOT NULL,body_search TEXT NOT NULL,request_id TEXT NOT NULL,request TEXT NOT NULL,UNIQUE(board_id,id),UNIQUE(board_id,request_id));
+CREATE INDEX posts_channel ON posts(board_id,channel,created_at,seq);
+CREATE INDEX posts_root ON posts(board_id,root,created_at,seq);
+CREATE INDEX posts_order ON posts(board_id,created_at,seq);
+CREATE TABLE subscriptions (board_id TEXT NOT NULL,target TEXT NOT NULL,agent TEXT NOT NULL,enabled INTEGER NOT NULL,PRIMARY KEY(board_id,target,agent));
+PRAGMA user_version=1;`;
+
+/** One transaction/connection per call. Reads never create a file, schema or board. */
+export class BoardStore {
+	readonly db: DatabaseSync;
+	constructor(path: string, write: boolean) {
+		const fresh = !existsSync(path);
+		if (write && fresh) mkdirSync(dirname(path), { recursive: true });
+		this.db = new DatabaseSync(path, { readOnly: !write });
+		try {
+			this.db.exec("PRAGMA busy_timeout=5000");
+			if (write) {
+				if (fresh) chmodSync(path, 0o600);
+				this.db.exec("PRAGMA journal_mode=WAL; BEGIN IMMEDIATE");
+			}
+			const version = this.one<{ user_version: number }>(
+				"PRAGMA user_version",
+			)?.user_version;
+			if (
+				version === 0 &&
+				write &&
+				this.all("SELECT name FROM sqlite_master WHERE type='table'").length ===
+					0
+			)
+				this.db.exec(SCHEMA);
+			else if (version !== 1)
+				throw new Error("Unsupported Shepherdr board archive schema");
+			if (write) this.db.exec("COMMIT");
+		} catch (error) {
+			this.db.close();
+			throw error;
+		}
+	}
+	one<T>(sql: string, ...args: SQLInputValue[]): T | undefined {
+		return this.db.prepare(sql).get(...args) as T | undefined;
+	}
+	all<T>(sql: string, ...args: SQLInputValue[]): T[] {
+		return this.db.prepare(sql).all(...args) as T[];
+	}
+	run(sql: string, ...args: SQLInputValue[]) {
+		return this.db.prepare(sql).run(...args);
+	}
+	post(board: string, id: string): PostRecord {
+		const post = this.one<PostRecord>(
+			`SELECT ${POST_COLUMNS} FROM posts WHERE board_id=? AND id=?`,
+			board,
+			id,
+		);
+		if (!post) throw new Error("Post not found in this board");
+		return post;
+	}
+	root(board: string, id: string): PostRecord {
+		const post = this.post(board, id);
+		if (post.thread_id !== id)
+			throw new Error("thread_id must identify a first post");
+		return post;
+	}
+	channel(board: string, name: string) {
+		const channel = this.one<{
+			channel_name: string;
+			created_at: string;
+			created_by: string;
+			message_count: number;
+			last_message_id: string | null;
+		}>(
+			`SELECT name AS channel_name,created_at,author AS created_by,
+		(SELECT COUNT(*) FROM posts p WHERE p.board_id=c.board_id AND p.channel=c.name) AS message_count,
+		(SELECT id FROM posts p WHERE p.board_id=c.board_id AND p.channel=c.name ORDER BY created_at DESC,seq DESC LIMIT 1) AS last_message_id
+		FROM channels c WHERE board_id=? AND name=?`,
+			board,
+			name,
+		);
+		if (!channel) throw new Error("Channel not found in this board");
+		return channel;
+	}
+	execute(scope: BoardScope, params: BoardParams, requestId: string) {
+		const write = MUTATIONS.has(params.action);
+		this.db.exec(write ? "BEGIN IMMEDIATE" : "BEGIN");
+		try {
+			const result = write
+				? this.mutate(scope, params, requestId)
+				: { value: queryBoard(this, scope.boardId, params), recipients: [] };
+			if (write) serializeBoardResult(result.value);
+			this.db.exec("COMMIT");
+			return result;
+		} catch (error) {
+			this.db.exec("ROLLBACK");
+			throw error;
+		}
+	}
+	close() {
+		this.db.close();
+	}
+	private ensureBoard(scope: BoardScope, now: string) {
+		this.run(
+			"INSERT OR IGNORE INTO boards VALUES(?,?,?,?)",
+			scope.boardId,
+			scope.rootSessionId,
+			scope.ownerFolder,
+			now,
+		);
+	}
+	private insertChannel(scope: BoardScope, name: string, now: string) {
+		if (
+			this.one(
+				"SELECT 1 FROM channels WHERE board_id=? AND name=?",
+				scope.boardId,
+				name,
+			)
+		)
+			throw new Error("Channel already exists");
+		this.run(
+			"INSERT INTO channels VALUES(?,?,?,?,?)",
+			scope.boardId,
+			name,
+			caseFold(name),
+			now,
+			scope.agentName,
+		);
+	}
+	private subscription(
+		board: string,
+		target: string,
+		agent: string,
+		enabled: boolean,
+		implicit = false,
+	) {
+		this.run(
+			implicit
+				? "INSERT OR IGNORE INTO subscriptions VALUES(?,?,?,1)"
+				: "INSERT INTO subscriptions VALUES(?,?,?,?) ON CONFLICT(board_id,target,agent) DO UPDATE SET enabled=excluded.enabled",
+			...[board, target, agent, ...(implicit ? [] : [enabled ? 1 : 0])],
+		);
+	}
+	private resolve(scope: BoardScope, value: string) {
+		const path = agentPath(value, scope.agentName);
+		if (!scope.members.includes(path))
+			throw new Error(`Agent not bound to this tree: ${path}`);
+		return path;
+	}
+	private mutate(scope: BoardScope, params: BoardParams, requestId: string) {
+		const board = scope.boardId;
+		if (params.action === "post") return this.publish(scope, params, requestId);
+		if (params.action === "create_channel") {
+			const name = required(params.channel_name, "channel_name");
+			const now = new Date().toISOString();
+			this.ensureBoard(scope, now);
+			this.insertChannel(scope, name, now);
+			if (params.subscribe !== false)
+				this.subscription(board, `channel:${name}`, scope.agentName, true);
+			return { value: this.channel(board, name), recipients: [] };
+		}
+		const target_agent =
+			params.target_agent === undefined
+				? scope.agentName
+				: this.resolve(scope, params.target_agent);
+		const root =
+			params.thread_id === undefined
+				? undefined
+				: this.root(board, params.thread_id);
+		const channel = this.channel(
+			board,
+			root?.channel_name ?? required(params.channel_name, "channel_name"),
+		);
+		const thread_id = root?.thread_id ?? null;
+		const target = root
+			? `thread:${root.thread_id}`
+			: `channel:${channel.channel_name}`;
+		const last = root
+			? (this.one<{ id: string }>(
+					"SELECT id FROM posts WHERE board_id=? AND root=? ORDER BY created_at DESC,seq DESC LIMIT 1",
+					board,
+					root.thread_id,
+				)?.id ?? null)
+			: channel.last_message_id;
+		const enabled = params.action === "subscribe";
+		this.subscription(board, target, target_agent, enabled);
+		return {
+			value: {
+				channel_name: channel.channel_name,
+				thread_id,
+				target_agent,
+				enabled,
+				last_message_id: last,
+			},
+			recipients: [],
+		};
+	}
+	private publish(scope: BoardScope, params: BoardParams, requestId: string) {
+		const board = scope.boardId;
+		const request = JSON.stringify(
+			Object.fromEntries(
+				Object.entries({
+					...params,
+					agents_to_notify: params.agents_to_notify ?? [],
+				}).sort(([a], [b]) => a.localeCompare(b)),
+			),
+		);
+		const key = `${scope.callerSessionId}:${requestId}`;
+		if (!requestId || Buffer.byteLength(key) > 1024)
+			throw new Error("Invalid post invocation ID");
+		const previous = this.one<{ id: string; request: string }>(
+			"SELECT id,request FROM posts WHERE board_id=? AND request_id=?",
+			board,
+			key,
+		);
+		if (previous) {
+			if (previous.request !== request)
+				throw new Error("Invocation ID already used for a different post");
+			return { value: metadata(this.post(board, previous.id)), recipients: [] };
+		}
+		const recipients = new Set(
+			(params.agents_to_notify ?? []).map((name) => this.resolve(scope, name)),
+		);
+		const now = new Date().toISOString();
+		const id = randomUUID();
+		let channel: string;
+		let root: string = id;
+		if (params.thread_id !== undefined) {
+			const post = this.root(board, params.thread_id);
+			channel = post.channel_name;
+			root = post.thread_id;
+		} else if (params.new_channel_name !== undefined) {
+			channel = params.new_channel_name;
+			this.ensureBoard(scope, now);
+			this.insertChannel(scope, channel, now);
+			this.subscription(board, `channel:${channel}`, scope.agentName, true);
+		} else
+			channel = this.channel(
+				board,
+				required(params.channel_name, "channel_name"),
+			).channel_name;
+		const target = root === id ? `channel:${channel}` : `thread:${root}`;
+		for (const { agent } of this.all<{ agent: string }>(
+			"SELECT agent FROM subscriptions WHERE board_id=? AND target=? AND enabled=1",
+			board,
+			target,
+		))
+			recipients.add(agent);
+		recipients.delete(scope.agentName);
+		const post: PostRecord = {
+			message_id: id,
+			channel_name: channel,
+			author: scope.agentName,
+			thread_id: root,
+			created_at: now,
+			text: required(params.text, "text"),
+		};
+		this.run(
+			"INSERT INTO posts(board_id,id,channel,root,author,created_at,text,body_search,request_id,request) VALUES(?,?,?,?,?,?,?,?,?,?)",
+			board,
+			id,
+			channel,
+			root,
+			scope.agentName,
+			now,
+			post.text,
+			caseFold(post.text),
+			key,
+			request,
+		);
+		this.subscription(board, `thread:${root}`, scope.agentName, true, true);
+		return {
+			value: metadata(post),
+			notice: preview(post, 150),
+			recipients: [...recipients],
+		};
+	}
+}
+
+export function validateMutation(params: BoardParams) {
+	if (
+		params.action === "create_channel" ||
+		params.new_channel_name !== undefined
+	) {
+		const name = required(
+			params.new_channel_name ?? params.channel_name,
+			"channel_name",
+		);
+		if (
+			!name ||
+			!name.isWellFormed() ||
+			Buffer.byteLength(name) > 128 ||
+			name.trim() !== name ||
+			/\p{Cc}/u.test(name)
+		)
+			throw new Error(
+				"Channel must be 1-128 UTF-8 bytes without edge whitespace/control characters",
+			);
+	}
+	if (params.action === "post") {
+		const text = required(params.text, "text");
+		if (!text || !text.isWellFormed() || Buffer.byteLength(text) > 65536)
+			throw new Error("Post must be 1-65536 UTF-8 bytes");
+	}
+}

package/src/tool.ts

@@ -0,0 +1,22 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { BoardParameters } from "./contract.js";
+import { serializeBoardResult } from "./response.js";
+import type { BoardRuntime } from "./runtime.js";
+
+export function createBoardTool(board: BoardRuntime) {
+	return defineTool({
+		name: "board",
+		label: "Message board",
+		description: "Shared discussions and saved board history",
+		parameters: BoardParameters,
+		executionMode: "sequential",
+		async execute(id, params, signal, _onUpdate, ctx) {
+			signal?.throwIfAborted();
+			const value = await board.execute(ctx, params, id);
+			return {
+				content: [{ type: "text", text: serializeBoardResult(value) }],
+				details: {},
+			};
+		},
+	});
+}

package/src/turns.ts

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { sendPolicyMessage } from "./delivery.js";
+import { type BoardBinding, binding } from "./identity.js";
+import type { BoardEnvelope } from "./protocol.js";
+
+type ActiveEnvelope = Extract<BoardEnvelope, { operation: "board-active" }>;
+type NoticeEnvelope = Extract<BoardEnvelope, { operation: "board-notify" }>;
+
+/** Turn IDs are transient capabilities. A stale snapshot cannot reach a later turn. */
+export class BoardTurns {
+	private current: { ctx: ExtensionContext; turnId: string } | undefined;
+	readonly active = new Map<string, { sessionId: string; turnId: string }>();
+	constructor(
+		pi: ExtensionAPI,
+		register: (
+			ctx: ExtensionContext,
+			request: ActiveEnvelope,
+		) => Promise<unknown>,
+		availability: (ctx: ExtensionContext, error?: unknown) => void,
+		seen: (ctx: ExtensionContext, ids: string[]) => void,
+	) {
+		pi.on("session_start", () => {
+			this.current = undefined;
+			this.active.clear();
+		});
+		pi.on("agent_start", async (_event, ctx) => {
+			const own = binding(ctx);
+			if (!own.enabled) return;
+			const turnId = randomUUID();
+			this.current = { ctx, turnId };
+			try {
+				await register(ctx, { operation: "board-active", caller: own, turnId });
+				availability(ctx);
+			} catch (error) {
+				availability(ctx, error);
+			}
+		});
+		const stop = async () => {
+			const current = this.current;
+			this.current = undefined;
+			if (!current) return;
+			try {
+				await register(current.ctx, {
+					operation: "board-active",
+					caller: binding(current.ctx),
+					turnId: null,
+					previousTurnId: current.turnId,
+				});
+			} catch {
+				/* No retry or delayed removal may affect a later turn. */
+			}
+		};
+		pi.on("agent_end", stop);
+		pi.on("agent_settled", stop);
+		pi.on("session_shutdown", async () => {
+			await stop();
+			this.active.clear();
+		});
+		this.deliver = (request) => {
+			const current = this.current;
+			if (!current || current.turnId !== request.turnId || current.ctx.isIdle())
+				return false;
+			const own = binding(current.ctx);
+			if (
+				!own.enabled ||
+				own.boardId !== request.boardId ||
+				own.sessionId !== request.sessionId ||
+				own.agentName !== request.target
+			)
+				return false;
+			// No await between running-turn check and steering. Never use the idle kickoff.
+			sendPolicyMessage(
+				pi,
+				{
+					customType: "shepherdr-board-post",
+					content: `Board post ${JSON.stringify(request.notice)}`,
+					display: true,
+				},
+				{ deliverAs: "steer" },
+			);
+			seen(current.ctx, [request.notice.message_id]);
+			return true;
+		};
+	}
+	readonly deliver: (request: NoticeEnvelope) => boolean;
+	register(caller: BoardBinding, request: ActiveEnvelope) {
+		if (request.turnId)
+			this.active.set(caller.agentName, {
+				sessionId: caller.sessionId,
+				turnId: request.turnId,
+			});
+		else if (
+			this.active.get(caller.agentName)?.turnId === request.previousTurnId
+		)
+			this.active.delete(caller.agentName);
+	}
+}

package/src/viewer/archive.ts

@@ -0,0 +1,227 @@
+import { statSync } from "node:fs";
+import {
+	DatabaseSync,
+	type SQLInputValue,
+	type SQLOutputValue,
+} from "node:sqlite";
+import type {
+	BoardDetail,
+	BoardIndex,
+	BoardSummary,
+	Post,
+	ThreadDetail,
+	ThreadPage,
+	ViewSource,
+} from "./contracts.ts";
+
+type Row = Record<string, SQLOutputValue>;
+function text(row: Row, key: string): string {
+	const value = row[key];
+	if (typeof value !== "string")
+		throw new Error(`Invalid board archive field: ${key}`);
+	return value;
+}
+function count(row: Row, key: string): number {
+	const value = row[key];
+	if (typeof value !== "number" || !Number.isSafeInteger(value))
+		throw new Error(`Invalid board archive count: ${key}`);
+	return value;
+}
+function nullableText(row: Row, key: string): string | null {
+	return row[key] === null ? null : text(row, key);
+}
+function post(row: Row): Post {
+	return {
+		id: text(row, "id"),
+		channel: text(row, "channel"),
+		author: text(row, "author"),
+		createdAt: text(row, "created_at"),
+		text: text(row, "text"),
+	};
+}
+
+/** The archive is opened read-only; no migrations, board creation or subscriptions. */
+export class Archive {
+	private readonly db: DatabaseSync | undefined;
+	private readonly source: ViewSource;
+	constructor(source: ViewSource) {
+		this.source = source;
+		try {
+			statSync(source.databasePath);
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT")
+				return;
+			throw error;
+		}
+		const db = new DatabaseSync(source.databasePath, { readOnly: true });
+		try {
+			db.exec("PRAGMA busy_timeout=2000; PRAGMA query_only=ON; BEGIN");
+			if (db.prepare("PRAGMA user_version").get()?.["user_version"] !== 1)
+				throw new Error("Unsupported board archive version");
+			this.db = db;
+		} catch (error) {
+			db.close();
+			throw error;
+		}
+	}
+	close(): void {
+		this.db?.close();
+	}
+	private all(sql: string, ...args: SQLInputValue[]): Row[] {
+		return this.db?.prepare(sql).all(...args) ?? [];
+	}
+
+	index(): BoardIndex {
+		const { databasePath: _path, ...context } = this.source;
+		const boards: BoardSummary[] = this.all(
+			`SELECT b.board_id,b.root_session_id,b.created_at,
+			(SELECT MAX(created_at) FROM posts WHERE board_id=b.board_id) AS last_activity,
+			(SELECT COUNT(*) FROM channels WHERE board_id=b.board_id) AS channels,
+			(SELECT COUNT(*) FROM posts WHERE board_id=b.board_id) AS posts,
+			(SELECT COUNT(DISTINCT author) FROM posts WHERE board_id=b.board_id) AS agents
+			FROM boards b WHERE owner_folder=? ORDER BY COALESCE(last_activity,b.created_at) DESC`,
+			this.source.folder,
+		).map((row) => ({
+			id: text(row, "board_id"),
+			rootSessionId: text(row, "root_session_id"),
+			createdAt: text(row, "created_at"),
+			lastActivity: nullableText(row, "last_activity"),
+			channels: count(row, "channels"),
+			posts: count(row, "posts"),
+			agents: count(row, "agents"),
+		}));
+		if (!boards.some((board) => board.id === context.boardId))
+			boards.unshift({
+				id: context.boardId,
+				rootSessionId: context.sessionId,
+				createdAt: null,
+				lastActivity: null,
+				channels: 0,
+				posts: 0,
+				agents: 0,
+			});
+		return { context, boards };
+	}
+
+	private board(id: string): BoardSummary {
+		const board = this.index().boards.find((board) => board.id === id);
+		if (!board) throw new Error("Board not found in this folder");
+		return board;
+	}
+
+	detail(id: string): BoardDetail {
+		const board = this.board(id);
+		const channels = this.all(
+			`SELECT c.name,c.author,c.created_at,COUNT(p.id) AS posts,
+			COUNT(CASE WHEN p.id=p.root THEN 1 END) AS threads,MAX(p.created_at) AS last_activity
+			FROM channels c LEFT JOIN posts p ON p.board_id=c.board_id AND p.channel=c.name
+			WHERE c.board_id=? GROUP BY c.name ORDER BY COALESCE(last_activity,c.created_at) DESC,c.name`,
+			id,
+		).map((row) => ({
+			name: text(row, "name"),
+			author: text(row, "author"),
+			createdAt: text(row, "created_at"),
+			posts: count(row, "posts"),
+			threads: count(row, "threads"),
+			lastActivity: nullableText(row, "last_activity"),
+		}));
+		const agents = this.all(
+			"SELECT author,COUNT(*) AS posts,MAX(created_at) AS last_activity FROM posts WHERE board_id=? GROUP BY author ORDER BY posts DESC,author",
+			id,
+		).map((row) => ({
+			name: text(row, "author"),
+			posts: count(row, "posts"),
+			lastActivity: text(row, "last_activity"),
+		}));
+		const subscriptions = this.all(
+			"SELECT target,agent,enabled FROM subscriptions WHERE board_id=? ORDER BY target,agent",
+			id,
+		).map((row) => ({
+			target: text(row, "target"),
+			agent: text(row, "agent"),
+			enabled: count(row, "enabled") === 1,
+		}));
+		return { board, channels, agents, subscriptions };
+	}
+
+	threads(id: string, params: URLSearchParams): ThreadPage {
+		this.board(id);
+		const channel = params.get("channel");
+		const query = params.get("q");
+		const author = params.get("author");
+		if (query && query.length > 1000) throw new Error("Search is too long");
+		const where = ["r.board_id=?", "r.id=r.root"];
+		const args: SQLInputValue[] = [id];
+		if (channel !== null) {
+			where.push("r.channel=?");
+			args.push(channel);
+		}
+		if (query || author) {
+			const match = ["m.board_id=r.board_id", "m.root=r.id"];
+			if (query) {
+				match.push("instr(lower(m.text),lower(?))>0");
+				args.push(query);
+			}
+			if (author) {
+				match.push("m.author=?");
+				args.push(author);
+			}
+			where.push(`EXISTS(SELECT 1 FROM posts m WHERE ${match.join(" AND ")})`);
+		}
+		const cursor = this.cursor(params);
+		const rows = this.all(
+			`SELECT r.id,r.channel,r.author,r.text,r.created_at,
+			MAX(p.created_at) AS last_activity,MAX(p.seq) AS last_seq,COUNT(*)-1 AS replies
+			FROM posts r JOIN posts p ON p.board_id=r.board_id AND p.root=r.id
+			WHERE ${where.join(" AND ")} GROUP BY r.id HAVING MAX(p.seq)<? ORDER BY last_seq DESC LIMIT 41`,
+			...args,
+			cursor ?? Number.MAX_SAFE_INTEGER,
+		);
+		const visible = rows.slice(0, 40);
+		const last = visible.at(-1);
+		return {
+			threads: visible.map((row) => ({
+				id: text(row, "id"),
+				channel: text(row, "channel"),
+				author: text(row, "author"),
+				preview: text(row, "text").slice(0, 600),
+				createdAt: text(row, "created_at"),
+				lastActivity: text(row, "last_activity"),
+				replies: count(row, "replies"),
+			})),
+			nextCursor:
+				rows.length > 40 && last ? String(count(last, "last_seq")) : null,
+		};
+	}
+
+	thread(id: string, threadId: string, params: URLSearchParams): ThreadDetail {
+		this.board(id);
+		const root = this.all(
+			"SELECT id,channel,author,created_at,text FROM posts WHERE board_id=? AND id=? AND root=id",
+			id,
+			threadId,
+		)[0];
+		if (!root) throw new Error("Thread not found in this board");
+		const rows = this.all(
+			"SELECT seq,id,channel,author,created_at,text FROM posts WHERE board_id=? AND root=? AND id<>root AND seq>? ORDER BY seq LIMIT 81",
+			id,
+			threadId,
+			this.cursor(params) ?? 0,
+		);
+		const visible = rows.slice(0, 80);
+		const last = visible.at(-1);
+		return {
+			root: post(root),
+			replies: visible.map(post),
+			nextCursor: rows.length > 80 && last ? String(count(last, "seq")) : null,
+		};
+	}
+
+	private cursor(params: URLSearchParams): number | undefined {
+		const value = params.get("cursor");
+		if (value === null) return undefined;
+		if (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(Number(value)))
+			throw new Error("Invalid page cursor");
+		return Number(value);
+	}
+}