pi-roundtable 0.1.0

package/src/core/modules/schedules/schedule-store.ts

@@ -0,0 +1,213 @@
+import type { SQL } from "bun";
+import type { Migration } from "../../db/migrations.ts";
+import type { ChannelKey } from "../../domain/conversation.ts";
+import type { Tier } from "../../speakers.ts";
+import type { Recurrence } from "./recurrence.ts";
+
+/** Owner schedules run the owner agent; party schedules run the channel's party role. */
+export type ScheduleMode = "owner" | "party";
+
+export interface Schedule {
+	id: number;
+	channel: ChannelKey;
+	mode: ScheduleMode;
+	title: string;
+	prompt: string;
+	recurrence: Recurrence;
+	nextRun: Date;
+	createdById: string;
+	createdByName: string;
+	/** The creator's tier when it was set; the schedule runs at it and lower tiers may not change it. */
+	createdTier: Tier;
+	createdAt: Date;
+	lastRun?: Date;
+	lastStatus?: string;
+}
+
+export interface NewSchedule {
+	channel: ChannelKey;
+	mode: ScheduleMode;
+	title: string;
+	prompt: string;
+	recurrence: Recurrence;
+	nextRun: Date;
+	createdById: string;
+	createdByName: string;
+	createdTier: Tier;
+}
+
+export interface ScheduleChange {
+	title?: string;
+	prompt?: string;
+	recurrence?: Recurrence;
+	nextRun?: Date;
+}
+
+interface Row {
+	id: string | number;
+	channel_key: ChannelKey;
+	mode: ScheduleMode;
+	title: string;
+	prompt: string;
+	recurrence: string;
+	next_run: Date;
+	created_by_id: string;
+	created_by_name: string;
+	created_tier: Tier;
+	created_at: Date;
+	last_run: Date | null;
+	last_status: string | null;
+}
+
+function toSchedule(row: Row): Schedule {
+	return {
+		id: Number(row.id),
+		channel: row.channel_key,
+		mode: row.mode,
+		title: row.title,
+		prompt: row.prompt,
+		// pi-lens-ignore: unchecked-throwing-call — this store wrote the JSON; a corrupt row should fail loudly
+		recurrence: JSON.parse(row.recurrence) as Recurrence,
+		nextRun: row.next_run,
+		createdById: row.created_by_id,
+		createdByName: row.created_by_name,
+		createdTier: row.created_tier,
+		createdAt: row.created_at,
+		...(row.last_run ? { lastRun: row.last_run } : {}),
+		...(row.last_status ? { lastStatus: row.last_status } : {}),
+	};
+}
+
+/** Scheduled turns, in the database. A one-time schedule's row is deleted once it fires. */
+export class ScheduleStore {
+	readonly #sql: SQL;
+
+	private constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	/** The store's tables; the host runs this before any store attaches. */
+	static readonly migration: Migration = {
+		name: "schedules",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS schedules (
+					id bigserial PRIMARY KEY,
+					channel_key text NOT NULL,
+					mode text NOT NULL,
+					title text NOT NULL,
+					prompt text NOT NULL,
+					recurrence text NOT NULL,
+					next_run timestamptz NOT NULL,
+					created_by_id text NOT NULL,
+					created_by_name text NOT NULL,
+					created_at timestamptz NOT NULL DEFAULT now(),
+					last_run timestamptz,
+					last_status text
+				)`;
+			// Schedules made before tiers existed were the owner's.
+			await sql`ALTER TABLE schedules ADD COLUMN IF NOT EXISTS created_tier text NOT NULL DEFAULT 'owner'`;
+			await sql`CREATE INDEX IF NOT EXISTS schedules_next_run ON schedules (next_run)`;
+			await sql`CREATE INDEX IF NOT EXISTS schedules_channel ON schedules (channel_key)`;
+		},
+	};
+
+	/** The store over the host's migrated pool. */
+	static async attach(sql: SQL): Promise<ScheduleStore> {
+		return new ScheduleStore(sql);
+	}
+
+	async create(schedule: NewSchedule): Promise<Schedule> {
+		const rows: Row[] = await this.#sql`
+			INSERT INTO schedules (channel_key, mode, title, prompt, recurrence, next_run,
+				created_by_id, created_by_name, created_tier)
+			VALUES (${schedule.channel}, ${schedule.mode}, ${schedule.title}, ${schedule.prompt},
+				${JSON.stringify(schedule.recurrence)}, ${schedule.nextRun},
+				${schedule.createdById}, ${schedule.createdByName}, ${schedule.createdTier})
+			RETURNING *`;
+		const [row] = rows;
+		if (!row) throw new Error("the schedule insert returned no row");
+		return toSchedule(row);
+	}
+
+	async get(id: number): Promise<Schedule | undefined> {
+		const rows: Row[] = await this
+			.#sql`SELECT * FROM schedules WHERE id = ${id}`;
+		return rows[0] ? toSchedule(rows[0]) : undefined;
+	}
+
+	async forChannel(channel: ChannelKey): Promise<Schedule[]> {
+		const rows: Row[] = await this.#sql`
+			SELECT * FROM schedules WHERE channel_key = ${channel} ORDER BY next_run`;
+		return rows.map(toSchedule);
+	}
+
+	async all(): Promise<Schedule[]> {
+		const rows: Row[] = await this
+			.#sql`SELECT * FROM schedules ORDER BY next_run`;
+		return rows.map(toSchedule);
+	}
+
+	/** Applies a change to one of the channel's schedules; undefined when it has no such schedule. */
+	async update(
+		channel: ChannelKey,
+		id: number,
+		change: ScheduleChange,
+	): Promise<Schedule | undefined> {
+		const current = await this.get(id);
+		if (!current || current.channel !== channel) return undefined;
+		const rows: Row[] = await this.#sql`
+			UPDATE schedules SET
+				title = ${change.title ?? current.title},
+				prompt = ${change.prompt ?? current.prompt},
+				recurrence = ${JSON.stringify(change.recurrence ?? current.recurrence)},
+				next_run = ${change.nextRun ?? current.nextRun}
+			WHERE id = ${id}
+			RETURNING *`;
+		return rows[0] ? toSchedule(rows[0]) : undefined;
+	}
+
+	/** Deletes a schedule, only from the given channel when one is given. */
+	async remove(
+		id: number,
+		channel?: ChannelKey,
+	): Promise<Schedule | undefined> {
+		const rows: Row[] = channel
+			? await this.#sql`
+				DELETE FROM schedules WHERE id = ${id} AND channel_key = ${channel} RETURNING *`
+			: await this.#sql`DELETE FROM schedules WHERE id = ${id} RETURNING *`;
+		return rows[0] ? toSchedule(rows[0]) : undefined;
+	}
+
+	async due(now: Date): Promise<Schedule[]> {
+		const rows: Row[] = await this.#sql`
+			SELECT * FROM schedules WHERE next_run <= ${now} ORDER BY next_run`;
+		return rows.map(toSchedule);
+	}
+
+	/**
+	 * Takes a due schedule before it runs: moves it to its next run, or deletes it when there
+	 * is none. The next_run guard makes a second claim of the same run a no-op.
+	 */
+	async claim(
+		schedule: Schedule,
+		next: Date | undefined,
+		now: Date,
+	): Promise<boolean> {
+		const rows: unknown[] = next
+			? await this.#sql`
+				UPDATE schedules SET next_run = ${next}, last_run = ${now}, last_status = 'running'
+				WHERE id = ${schedule.id} AND next_run = ${schedule.nextRun}
+				RETURNING id`
+			: await this.#sql`
+				DELETE FROM schedules WHERE id = ${schedule.id} AND next_run = ${schedule.nextRun}
+				RETURNING id`;
+		return rows.length > 0;
+	}
+
+	/** Records how a run ended; a deleted one-time schedule has no row left to update. */
+	async recordStatus(id: number, status: string): Promise<void> {
+		await this
+			.#sql`UPDATE schedules SET last_status = ${status} WHERE id = ${id}`;
+	}
+}

package/src/core/modules/schedules/schedule-tools.ts

@@ -0,0 +1,196 @@
+import type { ChannelKey } from "../../domain/conversation.ts";
+import { ScheduleError } from "../../domain/errors.ts";
+import { messages } from "../../i18n/index.ts";
+import type { ScheduleToolName } from "../../shared/schedule-tools.ts";
+import { type Tier, tierAtLeast } from "../../speakers.ts";
+import { timeZone, zonedStamp } from "../../time.ts";
+import {
+	describeRecurrence,
+	nextRun,
+	parseRecurrence,
+	type Recurrence,
+	type RecurrenceInput,
+} from "./recurrence.ts";
+import type {
+	Schedule,
+	ScheduleMode,
+	ScheduleStore,
+} from "./schedule-store.ts";
+
+/** Party channels are open to anyone, so their roles get tighter limits than the owner's agent. */
+export const SCHEDULE_LIMITS: Readonly<
+	Record<
+		ScheduleMode,
+		{ perChannel: number; promptChars: number; aheadDays: number }
+	>
+> = {
+	owner: { perChannel: 20, promptChars: 8_000, aheadDays: 366 },
+	party: { perChannel: 5, promptChars: 2_000, aheadDays: 90 },
+};
+const TITLE_CHARS = 80;
+const LIST_PROMPT_PREVIEW = 200;
+const DAY_MS = 86_400_000;
+
+export interface ScheduleToolContext {
+	store: Pick<
+		ScheduleStore,
+		"create" | "get" | "forChannel" | "update" | "remove"
+	>;
+	channel: ChannelKey;
+	mode: ScheduleMode;
+	/** Who asked, recorded on created schedules; a scheduled run speaks for its creator. */
+	author: { id: string; name: string; tier?: Tier };
+	now: Date;
+}
+
+type Input = Record<string, unknown> & RecurrenceInput;
+
+function text(input: Input, name: string, max: number): string {
+	const value = input[name];
+	if (typeof value !== "string" || !value.trim())
+		throw new ScheduleError(`${name} is required`);
+	if (value.length > max)
+		throw new ScheduleError(
+			`${name} is ${value.length} characters; keep it within ${max}`,
+		);
+	return value.trim();
+}
+
+function id(input: Input): number {
+	const value = input.id;
+	if (typeof value !== "number" || !Number.isInteger(value))
+		throw new ScheduleError("id is required; schedule_list shows the ids");
+	return value;
+}
+
+function hasTiming(input: Input): boolean {
+	return [
+		"in_minutes",
+		"at",
+		"time",
+		"every_days",
+		"start_date",
+		"weekdays",
+	].some((name) => input[name] !== undefined);
+}
+
+/** The recurrence and its first run, refusing a past or too distant one-time run. */
+function timing(ctx: ScheduleToolContext, input: Input): [Recurrence, Date] {
+	const recurrence = parseRecurrence(input, ctx.now);
+	const next = nextRun(recurrence, ctx.now);
+	if (!next)
+		throw new ScheduleError(
+			`that time has already passed; it is ${zonedStamp(ctx.now)} in ${messages().zoneName(timeZone())} now`,
+		);
+	const { aheadDays } = SCHEDULE_LIMITS[ctx.mode];
+	if (next.getTime() - ctx.now.getTime() > aheadDays * DAY_MS)
+		throw new ScheduleError(`the first run must be within ${aheadDays} days`);
+	return [recurrence, next];
+}
+
+function line(schedule: Schedule): string {
+	const prompt =
+		schedule.prompt.length > LIST_PROMPT_PREVIEW
+			? `${schedule.prompt.slice(0, LIST_PROMPT_PREVIEW)}…`
+			: schedule.prompt;
+	const last = schedule.lastRun
+		? `; last run ${zonedStamp(schedule.lastRun)} (${schedule.lastStatus ?? "?"})`
+		: "";
+	return `- #${schedule.id} ${schedule.title}: ${describeRecurrence(schedule.recurrence)}, next ${zonedStamp(schedule.nextRun)}; set by ${schedule.createdByName}${last}\n  ${prompt.replace(/\n/g, " ")}`;
+}
+
+async function own(ctx: ScheduleToolContext, input: Input): Promise<Schedule> {
+	const schedule = await ctx.store.get(id(input));
+	if (!schedule || schedule.channel !== ctx.channel)
+		throw new ScheduleError(
+			`this channel has no schedule #${String(input.id)}`,
+		);
+	return schedule;
+}
+
+/** A schedule runs at its creator's tier, so someone of a lower tier may not rewrite it. */
+function changeable(ctx: ScheduleToolContext, schedule: Schedule): Schedule {
+	if (ctx.author.tier && !tierAtLeast(ctx.author.tier, schedule.createdTier))
+		throw new ScheduleError(
+			`schedule #${schedule.id} was set by a higher tier; only that tier or above can change it`,
+		);
+	return schedule;
+}
+
+/** Runs one schedule tool against the channel's schedules and returns the answer for the model. */
+export async function callScheduleTool(
+	ctx: ScheduleToolContext,
+	name: ScheduleToolName,
+	input: Input,
+): Promise<string> {
+	const limits = SCHEDULE_LIMITS[ctx.mode];
+	switch (name) {
+		case "schedule_create": {
+			const title = text(input, "title", TITLE_CHARS);
+			const prompt = text(input, "prompt", limits.promptChars);
+			const [recurrence, next] = timing(ctx, input);
+			const existing = await ctx.store.forChannel(ctx.channel);
+			if (existing.length >= limits.perChannel)
+				throw new ScheduleError(
+					`this channel already has ${existing.length} schedules, the most it may have; cancel one first`,
+				);
+			const created = await ctx.store.create({
+				channel: ctx.channel,
+				mode: ctx.mode,
+				title,
+				prompt,
+				recurrence,
+				nextRun: next,
+				createdById: ctx.author.id,
+				createdByName: ctx.author.name,
+				createdTier: ctx.author.tier ?? "owner",
+			});
+			return `Scheduled #${created.id} "${title}": ${describeRecurrence(recurrence)}, first run ${zonedStamp(next)} ${messages().zoneTime(timeZone())}.`;
+		}
+		case "schedule_list": {
+			if (input.id !== undefined) {
+				const schedule = await own(ctx, input);
+				return `${line(schedule).split("\n")[0]}\n\nPrompt:\n${schedule.prompt}`;
+			}
+			const all = await ctx.store.forChannel(ctx.channel);
+			return all.length === 0
+				? "This channel has no schedules."
+				: `It is ${zonedStamp(ctx.now)} in ${messages().zoneName(timeZone())}.\n${all.map(line).join("\n")}`;
+		}
+		case "schedule_update": {
+			const schedule = changeable(ctx, await own(ctx, input));
+			const change: Parameters<ScheduleToolContext["store"]["update"]>[2] = {};
+			if (input.title !== undefined)
+				change.title = text(input, "title", TITLE_CHARS);
+			if (input.prompt !== undefined)
+				change.prompt = text(input, "prompt", limits.promptChars);
+			if (hasTiming(input)) {
+				const [recurrence, next] = timing(ctx, input);
+				change.recurrence = recurrence;
+				change.nextRun = next;
+			}
+			if (Object.keys(change).length === 0)
+				throw new ScheduleError("give a title, prompt, or timing to change");
+			const updated = await ctx.store.update(ctx.channel, schedule.id, change);
+			if (!updated) throw new ScheduleError(`schedule #${schedule.id} is gone`);
+			return `Updated #${updated.id} "${updated.title}": ${describeRecurrence(updated.recurrence)}, next run ${zonedStamp(updated.nextRun)}.`;
+		}
+		case "schedule_cancel": {
+			const schedule = changeable(ctx, await own(ctx, input));
+			await ctx.store.remove(schedule.id, ctx.channel);
+			return `Cancelled #${schedule.id} "${schedule.title}".`;
+		}
+		default:
+			throw new ScheduleError("unknown schedule tool");
+	}
+}
+
+/** What a scheduled run receives as its message. */
+export function scheduledTurnText(schedule: Schedule, firedAt: Date): string {
+	return [
+		`## Scheduled task #${schedule.id}: ${schedule.title}`,
+		`${schedule.createdByName} set this schedule (${describeRecurrence(schedule.recurrence)}). It is due now, ${zonedStamp(firedAt)} ${messages().zoneTime(timeZone())}. Nobody wrote a new message: carry out the task below and write what you would post in this channel. If the task keeps a record for later runs, update it with schedule_update on #${schedule.id}.`,
+		"",
+		schedule.prompt,
+	].join("\n");
+}