pi-roundtable 0.1.0

package/src/core/speakers.ts

@@ -0,0 +1,143 @@
+import { ConfigError } from "./domain/errors.ts";
+import type { OwnerIdentity } from "./identity.ts";
+
+/** How much a speaker may do: `owner` above `admin` above `member`. */
+export const TIERS = ["member", "admin", "owner"] as const;
+export type Tier = (typeof TIERS)[number];
+
+/** Whether `tier` is `least` or above. */
+export function tierAtLeast(tier: Tier, least: Tier): boolean {
+	return TIERS.indexOf(tier) >= TIERS.indexOf(least);
+}
+
+/** A person whose message starts a turn, and the tier the policy gave them. */
+export interface Speaker {
+	id: string;
+	name: string;
+	tier: Tier;
+}
+
+/**
+ * Who a prompt addresses for this speaker: the owner for an owner-tier speaker, so the owner's
+ * prompts stay as they are, and otherwise the speaker by name, since a name needs no guess at
+ * pronouns.
+ */
+export function addressee(
+	speaker: Speaker | undefined,
+	owner: OwnerIdentity,
+): OwnerIdentity {
+	if (!speaker || speaker.tier === "owner") return owner;
+	return {
+		name: speaker.name,
+		pronouns: {
+			subject: speaker.name,
+			object: speaker.name,
+			possessive: `${speaker.name}'s`,
+		},
+	};
+}
+
+/**
+ * How a tool description names the person it serves in a session that several speakers share:
+ * the description is fixed when the session opens, so it names no one, and the prompt says who
+ * the speaker is.
+ */
+export const THE_SPEAKER: OwnerIdentity = {
+	name: "the speaker",
+	pronouns: {
+		subject: "the speaker",
+		object: "the speaker",
+		possessive: "the speaker's",
+	},
+};
+
+/** The turn's text under the speaker's name, so a conversation several speakers share says who wrote what. */
+export function attributed(speaker: Speaker, text: string): string {
+	if (speaker.tier === "owner") return text;
+	return `(Message from ${speaker.name}, at the ${speaker.tier} tier.)\n\n${text}`;
+}
+
+/** What a surface reports about the author of a message; the policy decides the rest. */
+export interface SpeakerFacts {
+	id: string;
+	name: string;
+	/** The roles the author holds in the server; empty where the surface has none. */
+	roleIds?: readonly string[];
+}
+
+/**
+ * Decides who may talk to the agents. Undefined means the author is nobody: no reply and no
+ * turn. A plugin may replace the configured policy.
+ */
+export interface SpeakerPolicy {
+	resolve(author: SpeakerFacts): Speaker | undefined;
+}
+
+/** Who holds one tier: user ids, role ids, and (for members) everyone. */
+export interface TierMembers {
+	users?: readonly string[];
+	roles?: readonly string[];
+	everyone?: boolean;
+}
+
+export interface SpeakerMap {
+	/** User ids of the owners. */
+	owners: readonly string[];
+	admins?: TierMembers;
+	members?: TierMembers;
+}
+
+/** The policy of an operator's map; the highest tier an author qualifies for wins. */
+export function speakerPolicy(map: SpeakerMap): SpeakerPolicy {
+	const holds = (tier: TierMembers | undefined, author: SpeakerFacts) =>
+		tier !== undefined &&
+		(tier.everyone === true ||
+			tier.users?.includes(author.id) === true ||
+			(author.roleIds ?? []).some((role) => tier.roles?.includes(role)));
+	const tierOf = (author: SpeakerFacts): Tier | undefined => {
+		if (map.owners.includes(author.id)) return "owner";
+		if (holds(map.admins, author)) return "admin";
+		if (holds(map.members, author)) return "member";
+		return undefined;
+	};
+	return {
+		resolve(author) {
+			const tier = tierOf(author);
+			return tier && { id: author.id, name: author.name, tier };
+		},
+	};
+}
+
+/**
+ * Reads a tier's members from text: comma-separated `user:<id>`, `role:<id>`, or `@everyone`;
+ * a bare id is a user. `allowEveryone` is false for tiers that cannot be everyone.
+ */
+export function parseTierMembers(
+	text: string | undefined,
+	name: string,
+	allowEveryone: boolean,
+): TierMembers | undefined {
+	const items = (text ?? "")
+		.split(",")
+		.map((item) => item.trim())
+		.filter((item) => item !== "");
+	if (items.length === 0) return undefined;
+	const users: string[] = [];
+	const roles: string[] = [];
+	let everyone = false;
+	for (const item of items) {
+		if (item === "@everyone") {
+			if (!allowEveryone)
+				throw new ConfigError(`${name} cannot include @everyone`);
+			everyone = true;
+			continue;
+		}
+		const [kind, id] = item.includes(":") ? item.split(":", 2) : ["user", item];
+		if ((kind !== "user" && kind !== "role") || !/^\d{17,20}$/.test(id ?? ""))
+			throw new ConfigError(
+				`${name} must list user:<id>, role:<id>, or @everyone, got ${item}`,
+			);
+		(kind === "role" ? roles : users).push(id as string);
+	}
+	return { users, roles, everyone };
+}

package/src/core/testing/database.ts

@@ -0,0 +1,52 @@
+import { describe } from "bun:test";
+import type { SQL } from "bun";
+import { type Migration, migrate, openPool } from "../db/migrations.ts";
+
+// PostgreSQL-backed tests run only when ROUNDTABLE_TEST_DATABASE_URL points at a test database.
+// CI sets it; without it `bun test` skips those suites instead of failing to connect.
+const url = process.env.ROUNDTABLE_TEST_DATABASE_URL;
+
+if (process.env.CI && !url) {
+	throw new Error(
+		"ROUNDTABLE_TEST_DATABASE_URL is not set; CI must run the PostgreSQL-backed tests.",
+	);
+}
+
+/** The guild the stores of the tests serve. */
+export const TEST_GUILD = "900000000000000001";
+
+export const testDatabaseUrl = url ?? "";
+
+export const describeDb = url ? describe : describe.skip;
+
+/** A test pool with the migrations run, as the host runs them before any store attaches; the caller closes it. */
+export async function migratedPool(...migrations: Migration[]): Promise<SQL> {
+	const sql = openPool(testDatabaseUrl);
+	await migrate(sql, migrations);
+	return sql;
+}
+
+/** A store with its own migrated test pool, as stores opened before the host owned the pool. */
+export type TestStore<T> = T & { close(): Promise<void> };
+
+/** Migrates a pool for the store alone and attaches it; closing the store closes that pool. */
+export async function openTestStore<T extends object, A extends unknown[]>(
+	Store: {
+		migration: Migration;
+		/** The migrations to run when the store's arguments decide them, such as a guild. */
+		migrations?(...args: A): Migration[];
+		attach(sql: SQL, ...args: A): T | Promise<T>;
+	},
+	...args: A
+): Promise<TestStore<T>> {
+	const sql = await migratedPool(
+		...(Store.migrations?.(...args) ?? [Store.migration]),
+	);
+	try {
+		const store = await Store.attach(sql, ...args);
+		return Object.assign(store, { close: () => sql.close() });
+	} catch (error) {
+		await sql.close();
+		throw error;
+	}
+}

package/src/core/testing/file-size.ts

@@ -0,0 +1,34 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+/** The most lines a source file may have before it is split along its responsibilities. */
+export const MAX_SOURCE_LINES = 500;
+/** The most lines a test file may have. */
+export const MAX_TEST_LINES = 700;
+
+function typeScriptFiles(dir: string): string[] {
+	return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		if (entry.name === "node_modules") return [];
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) return typeScriptFiles(path);
+		return /\.tsx?$/.test(entry.name) ? [path] : [];
+	});
+}
+
+/** The files under `dirs` over their limit, each as `<path> has <n> lines`. */
+export function oversizedFiles(
+	root: string,
+	dirs: readonly string[],
+): string[] {
+	return dirs
+		.flatMap((dir) => typeScriptFiles(join(root, dir)))
+		.flatMap((file) => {
+			const lines = readFileSync(file, "utf8").split("\n").length - 1;
+			const limit = /\.test\.tsx?$/.test(file)
+				? MAX_TEST_LINES
+				: MAX_SOURCE_LINES;
+			return lines > limit
+				? [`${relative(root, file)} has ${lines} lines, over ${limit}`]
+				: [];
+		});
+}

package/src/core/testing/locale.ts

@@ -0,0 +1,8 @@
+import { setLocale } from "../i18n/index.ts";
+import { setTimeZone } from "../time.ts";
+
+/** The neutral defaults the core's suite runs under; a test that changes them puts them back with this. */
+export function useTestLocale(): void {
+	setTimeZone("UTC");
+	setLocale("en", { assistant: "Roundtable", root: "roundtable" });
+}

package/src/core/testing/modules.ts

@@ -0,0 +1,97 @@
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { modulesPlugin } from "../builtin/modules.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import { silentLogger } from "../log.ts";
+import type { Contribution, PluginContext } from "../plugin.ts";
+import {
+	type CoreDiscord,
+	CoreRegistry,
+	type CoreStores,
+} from "../services.ts";
+
+/** What the modules' tools did, for a test to read. */
+export interface ModuleRecord {
+	/** Where each delegation job's thread opened. */
+	threadOrigins: (ChannelKey | undefined)[];
+	/** The channel each delegated report came back to. */
+	reportChannels: ChannelKey[];
+	/** How often a conversation without a chat channel fell back to the owner's messages. */
+	ownerChannelAsked: number;
+}
+
+export const OWNER_CHANNEL: ChannelKey = "discord:owner-dm";
+
+/** The modules plugin set up over stand-in stores and surface; returns its contribution and the record. */
+export async function setUpModules(
+	options: { agentChannelOf?: (name: string) => ChannelKey } = {},
+): Promise<{
+	contribution: Contribution;
+	record: ModuleRecord;
+	core: CoreRegistry;
+}> {
+	const record: ModuleRecord = {
+		threadOrigins: [],
+		reportChannels: [],
+		ownerChannelAsked: 0,
+	};
+	const core = new CoreRegistry();
+	// SAFETY: the tools under test read no store; each stub is asked for nothing else.
+	core.provide("stores", {
+		memory: {},
+		schedules: {},
+		confirmations: {},
+		agents: {},
+		skills: {},
+	} as unknown as CoreStores);
+	// SAFETY: the tools under test use the surface's owner channel and the threads' open only.
+	core.provide("discord", {
+		surface: {
+			ownerChannel: async () => {
+				record.ownerChannelAsked += 1;
+				return OWNER_CHANNEL;
+			},
+			ownerDiscord: () => ({}),
+		},
+		threads: {
+			open: async (origin: ChannelKey | undefined) => {
+				record.threadOrigins.push(origin);
+				return undefined;
+			},
+		},
+		guard: {},
+		cards: {},
+		studio: {},
+	} as unknown as CoreDiscord);
+	const plugin = modulesPlugin({
+		owner: {
+			id: "1",
+			name: "Owner",
+			pronouns: { subject: "they", object: "them", possessive: "their" },
+		},
+		assistant: "Assistant",
+		// SAFETY: a worker of the test's own replaces the one that would read the runtime.
+		modelRuntime: {} as ModelRuntime,
+		agentDir: "/tmp/agent",
+		dataDir: "/tmp/data",
+		delegation: {
+			model: { provider: "test", id: "worker" },
+			thinking: "low",
+			worker: { run: async () => "found it" },
+		},
+		...(options.agentChannelOf
+			? { agentChannelOf: options.agentChannelOf }
+			: {}),
+	});
+	// SAFETY: setup reads only the logger, the conversations' background, and the core services.
+	const context = {
+		logger: silentLogger(),
+		conversations: {
+			background: async (turn: { channel: ChannelKey }) => {
+				record.reportChannels.push(turn.channel);
+				return { status: "ran" };
+			},
+		},
+		core,
+	} as unknown as PluginContext;
+	return { contribution: await plugin.setup(context), record, core };
+}

package/src/core/testing/owner.ts

@@ -0,0 +1,15 @@
+import type { OwnerIdentity } from "../identity.ts";
+import type { Speaker } from "../speakers.ts";
+
+/** The owner tests speak for; its words match the texts the tests expect. */
+export const TEST_OWNER: OwnerIdentity = {
+	name: "Riley",
+	pronouns: { subject: "he", object: "him", possessive: "his" },
+};
+
+/** The owner as a speaker of the tests. */
+export const OWNER_SPEAKER: Speaker = {
+	id: "1",
+	name: TEST_OWNER.name,
+	tier: "owner",
+};

package/src/core/testing/thread-host.ts

@@ -0,0 +1,60 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	DispatchThreads,
+	type ThreadHost,
+} from "../discord/dispatch-threads.ts";
+import { silentLogger } from "../log.ts";
+
+/** A ThreadHost that records what happens; parents in `hostless` cannot host threads. */
+export class FakeThreadHost implements ThreadHost {
+	/** Start lines by parent id, as last edited. */
+	readonly lines = new Map<string, string>();
+	readonly opened: { parentId: string; name: string; id: string }[] = [];
+	readonly posts: { threadId: string; text: string }[] = [];
+	readonly closed: string[] = [];
+	readonly hostless = new Set<string>();
+	failOpen = false;
+	#next = 900;
+
+	async open(
+		parentId: string,
+		name: string,
+		line: (thread?: string) => string,
+	): Promise<string | undefined> {
+		if (this.hostless.has(parentId)) return undefined;
+		if (this.failOpen) throw new Error("Missing Permissions");
+		const id = String(this.#next++);
+		this.opened.push({ parentId, name, id });
+		this.lines.set(parentId, line(`<#${id}>`));
+		return id;
+	}
+
+	async post(threadId: string, text: string): Promise<void> {
+		this.posts.push({ threadId, text });
+	}
+
+	async close(threadId: string): Promise<void> {
+		this.closed.push(threadId);
+	}
+
+	/** The texts posted in one thread, in order. */
+	textsIn(threadId: string): string[] {
+		return this.posts.filter((p) => p.threadId === threadId).map((p) => p.text);
+	}
+}
+
+/** Dispatch threads over a fake host, with a ledger in a fresh temporary directory. */
+export function fakeThreads(host = new FakeThreadHost()) {
+	const ledgerPath = join(
+		mkdtempSync(join(tmpdir(), "roundtable-threads-")),
+		"dispatch-threads.json",
+	);
+	const threads = new DispatchThreads({
+		host,
+		ledgerPath,
+		logger: silentLogger(),
+	});
+	return { host, threads, ledgerPath };
+}

package/src/core/time.test.ts

@@ -0,0 +1,166 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { setLocale } from "./i18n/index.ts";
+import { nextRun, parseRecurrence } from "./modules/schedules/recurrence.ts";
+import { scheduleToolSpecs } from "./shared/schedule-tools.ts";
+import { useTestLocale } from "./testing/locale.ts";
+import {
+	setTimeZone,
+	timeZone,
+	zonedDate,
+	zonedInstant,
+	zonedStamp,
+	zonedToday,
+} from "./time.ts";
+
+afterEach(useTestLocale);
+
+describe("configured time zone", () => {
+	test("defaults to UTC before a host configures the process", () => {
+		const result = Bun.spawnSync({
+			cmd: [
+				"bun",
+				"-e",
+				'import { timeZone } from "./src/core/time.ts"; console.log(timeZone())',
+			],
+		});
+		expect(result.exitCode).toBe(0);
+		expect(result.stdout.toString().trim()).toBe("UTC");
+	});
+
+	test("rejects an invalid zone without changing the current one", () => {
+		setTimeZone("UTC");
+		expect(() => setTimeZone("Not/A_Zone")).toThrow("Not/A_Zone");
+		expect(timeZone()).toBe("UTC");
+	});
+
+	test("Taipei agrees with the former +8 arithmetic for a year-long sweep", () => {
+		setTimeZone("Asia/Taipei");
+		const start = Date.parse("2026-01-01T00:00:00Z");
+		for (let i = 0; i < 366; i += 1) {
+			const at = new Date(start + i * 86_400_000 + i * 61_000);
+			const old = new Date(at.getTime() + 8 * 3_600_000).toISOString();
+			expect(zonedDate(at)).toBe(old.slice(0, 10));
+			expect(zonedStamp(at)).toBe(old.slice(0, 16).replace("T", " "));
+		}
+		expect(zonedToday()).toBe(zonedDate(new Date()));
+	});
+
+	test("New York resolves spring gaps later and fall folds to the first occurrence", () => {
+		setTimeZone("America/New_York");
+		expect(zonedInstant("2026-03-08", "02:30").toISOString()).toBe(
+			"2026-03-08T07:30:00.000Z",
+		);
+		expect(zonedStamp(zonedInstant("2026-03-08", "02:30"))).toBe(
+			"2026-03-08 03:30",
+		);
+		expect(zonedInstant("2026-11-01", "01:30").toISOString()).toBe(
+			"2026-11-01T05:30:00.000Z",
+		);
+	});
+
+	test("handles +14 and half-hour offsets", () => {
+		setTimeZone("Pacific/Kiritimati");
+		expect(zonedInstant("2026-07-01", "09:15").toISOString()).toBe(
+			"2026-06-30T19:15:00.000Z",
+		);
+		setTimeZone("America/St_Johns");
+		expect(zonedInstant("2026-01-01", "09:15").toISOString()).toBe(
+			"2026-01-01T12:45:00.000Z",
+		);
+		expect(zonedInstant("2026-07-01", "09:15").toISOString()).toBe(
+			"2026-07-01T11:45:00.000Z",
+		);
+	});
+
+	test("daily, weekly, and interval recurrence stay at wall-clock time across DST", () => {
+		setTimeZone("America/New_York");
+		const before = new Date("2026-03-07T15:00:00Z");
+		const daily = parseRecurrence(
+			{ time: "09:00", start_date: "2026-03-07" },
+			before,
+		);
+		expect(nextRun(daily, before)?.toISOString()).toBe(
+			"2026-03-08T13:00:00.000Z",
+		);
+		expect(
+			nextRun(daily, new Date("2026-03-08T13:00:00Z"))?.toISOString(),
+		).toBe("2026-03-09T13:00:00.000Z");
+		expect(
+			nextRun(daily, new Date("2026-10-31T13:00:00Z"))?.toISOString(),
+		).toBe("2026-11-01T14:00:00.000Z");
+		const weekly = parseRecurrence(
+			{ time: "09:00", weekdays: ["sun"] },
+			before,
+		);
+		expect(nextRun(weekly, before)?.toISOString()).toBe(
+			"2026-03-08T13:00:00.000Z",
+		);
+		expect(
+			nextRun(weekly, new Date("2026-03-08T13:00:00Z"))?.toISOString(),
+		).toBe("2026-03-15T13:00:00.000Z");
+		const interval = parseRecurrence(
+			{ time: "09:00", every_days: 2, start_date: "2026-03-07" },
+			before,
+		);
+		expect(nextRun(interval, before)?.toISOString()).toBe(
+			"2026-03-09T13:00:00.000Z",
+		);
+		expect(
+			nextRun(
+				{ kind: "once", date: "2026-11-01", time: "01:30" },
+				new Date("2026-10-31T12:00:00Z"),
+			)?.toISOString(),
+		).toBe("2026-11-01T05:30:00.000Z");
+	});
+
+	test("the wording of every catalog derives from the configured zone, with none special", () => {
+		const errors = () => [
+			() => parseRecurrence({ at: "soon" }, new Date()),
+			() => parseRecurrence({ time: "soon" }, new Date()),
+		];
+		const messagesFor = (locale: "en" | "zh-TW") => {
+			setLocale(locale, { assistant: "Roundtable", root: "roundtable" });
+			return errors().map((run) => {
+				try {
+					run();
+				} catch (error) {
+					return String(error);
+				}
+				throw new Error("expected the recurrence to be refused");
+			});
+		};
+		setTimeZone("Europe/Berlin");
+		expect(messagesFor("en")).toEqual([
+			expect.stringContaining('at must be Europe/Berlin time as "YYYY-MM-DD'),
+			expect.stringContaining('"HH:MM", Europe/Berlin) to repeat'),
+		]);
+		setTimeZone("America/Argentina/Buenos_Aires");
+		expect(messagesFor("zh-TW")).toEqual([
+			expect.stringContaining('at must be Buenos Aires time as "YYYY-MM-DD'),
+			expect.stringContaining('"HH:MM", Buenos Aires) to repeat'),
+		]);
+		setTimeZone("UTC");
+		expect(scheduleToolSpecs()[0]?.description).toContain("UTC time");
+	});
+
+	test("relative once scheduling preserves the second occurrence of a fall-back hour", () => {
+		setTimeZone("America/New_York");
+		const now = new Date("2026-11-01T06:10:00Z");
+		const once = parseRecurrence({ in_minutes: 20 }, now);
+		expect(nextRun(once, now)?.toISOString()).toBe("2026-11-01T06:30:00.000Z");
+	});
+
+	test("tool descriptions take the zone when built, in the wording of the locale", () => {
+		setTimeZone("Asia/Taipei");
+		expect(scheduleToolSpecs()[0]?.description).toContain(
+			"set Asia/Taipei time",
+		);
+		setLocale("zh-TW", { assistant: "Roundtable", root: "roundtable" });
+		expect(scheduleToolSpecs()[0]?.description).toContain("set Taipei time");
+		setLocale("en", { assistant: "Roundtable", root: "roundtable" });
+		setTimeZone("America/New_York");
+		expect(scheduleToolSpecs()[0]?.description).toContain(
+			"America/New_York time",
+		);
+	});
+});

package/src/core/time.ts

@@ -0,0 +1,67 @@
+/** The host chooses one IANA zone before starting its services. */
+let zone = "UTC";
+
+export function setTimeZone(value: string): void {
+	try {
+		new Intl.DateTimeFormat("sv-SE", { timeZone: value });
+	} catch {
+		throw new Error(`Invalid time zone: ${value}`);
+	}
+	zone = value;
+}
+
+export function timeZone(): string {
+	return zone;
+}
+
+/** The formatter is constructed when used, not at import time, so configuration is observed. */
+function stamp(at: Date): string {
+	return new Intl.DateTimeFormat("sv-SE", {
+		timeZone: zone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		hourCycle: "h23",
+	}).format(at);
+}
+
+export function zonedDate(at: Date): string {
+	return stamp(at).slice(0, 10);
+}
+
+export function zonedStamp(at: Date): string {
+	return stamp(at);
+}
+
+export function zonedToday(): string {
+	return zonedDate(new Date());
+}
+
+/** Convert a local minute to an instant. Choose the first occurrence in a fold and
+ * a later valid wall time in a gap (e.g. 02:30 becomes 03:30).
+ * Probe both sides of a transition: a single offset iteration can oscillate in a gap.
+ */
+export function zonedInstant(date: string, time: string): Date {
+	const wall = `${date} ${time}`;
+	const utc = Date.parse(`${date}T${time}:00Z`);
+	const minute = 60_000;
+	const offsets = new Set<number>();
+	for (const delta of [-86_400_000, 0, 86_400_000]) {
+		const probe = utc + delta;
+		const local = stamp(new Date(probe));
+		const localAsUtc = Date.parse(`${local.replace(" ", "T")}:00Z`);
+		offsets.add(localAsUtc - Math.floor(probe / minute) * minute);
+	}
+	const candidates = [...offsets]
+		.map((offset) => new Date(utc - offset))
+		.sort((a, b) => a.getTime() - b.getTime());
+	const fallback = candidates.at(-1);
+	if (!fallback) throw new Error(`Could not resolve local time: ${wall}`);
+	return (
+		candidates.find((candidate) => stamp(candidate) === wall) ??
+		candidates.find((candidate) => stamp(candidate) > wall) ??
+		fallback
+	);
+}