pi-roundtable 0.1.0

package/src/core/modules/memory/owner-memory-store.ts

@@ -0,0 +1,228 @@
+import type { SQL } from "bun";
+import type { Migration } from "../../db/migrations.ts";
+import { MemoryError } from "../../domain/errors.ts";
+
+export const OWNER_MEMORY_KINDS = ["core", "note", "event"] as const;
+export type OwnerMemoryKind = (typeof OWNER_MEMORY_KINDS)[number];
+
+export interface OwnerMemory {
+	id: number;
+	kind: OwnerMemoryKind;
+	fact: string;
+	/** YYYY-MM-DD; set for events only. */
+	eventDate: string | null;
+}
+
+/** What every owner turn carries: all core facts, and events that have not passed yet. */
+export interface OwnerPromptMemory {
+	core: OwnerMemory[];
+	events: OwnerMemory[];
+}
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const SEARCH_LIMIT = 20;
+
+interface Row {
+	id: string | number;
+	kind: OwnerMemoryKind;
+	fact: string;
+	event_date: string | null;
+}
+
+function toMemory(row: Row): OwnerMemory {
+	return {
+		id: Number(row.id),
+		kind: row.kind,
+		fact: row.fact,
+		eventDate: row.event_date,
+	};
+}
+
+/** Whitespace-separated query terms, deduplicated; Chinese needs no tokenizer this way. */
+export function searchTerms(query: string): string[] {
+	return [
+		...new Set(
+			query
+				.toLowerCase()
+				.split(/\s+/)
+				.filter((term) => term.length > 0),
+		),
+	];
+}
+
+/** The trimmed fact, after the rules every stored memory follows. */
+function checkedFact(
+	fact: string,
+	kind: OwnerMemoryKind,
+	eventDate: string | undefined,
+): string {
+	const trimmed = fact.trim();
+	if (!trimmed) throw new MemoryError("a memory fact cannot be empty");
+	if (!(OWNER_MEMORY_KINDS as readonly string[]).includes(kind))
+		throw new MemoryError(`unknown memory kind: ${kind}`);
+	if (kind === "event" && !(eventDate && DATE.test(eventDate)))
+		throw new MemoryError("an event needs its date as YYYY-MM-DD");
+	if (kind !== "event" && eventDate)
+		throw new MemoryError("only an event has a date");
+	return trimmed;
+}
+
+/**
+ * One speaker's remembered facts in the database: core facts, searchable notes, and
+ * dated events. The store is bound to a speaker and never reads or changes another's; every
+ * agent shares the memory of whoever is speaking.
+ */
+export class OwnerMemoryStore {
+	readonly #sql: SQL;
+	/** Whose memory this is: a Discord user id. */
+	readonly speakerId: string;
+
+	private constructor(sql: SQL, speakerId: string) {
+		this.#sql = sql;
+		this.speakerId = speakerId;
+	}
+
+	/** Connects, and creates or upgrades the table; rows from before kinds existed become core facts. */
+	/** The store's tables; the host runs this before any store attaches. */
+	static readonly migration: Migration = {
+		name: "owner-memory",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS owner_memory (
+					id bigserial PRIMARY KEY,
+					fact text NOT NULL CHECK (length(btrim(fact)) > 0),
+					created_at timestamptz NOT NULL DEFAULT now()
+				)`;
+			await sql`
+				ALTER TABLE owner_memory
+					ADD COLUMN IF NOT EXISTS kind text NOT NULL DEFAULT 'core'
+						CHECK (kind IN ('core', 'note', 'event')),
+					ADD COLUMN IF NOT EXISTS event_date date,
+					ADD COLUMN IF NOT EXISTS updated_at timestamptz NOT NULL DEFAULT now()`;
+		},
+	};
+
+	/**
+	 * The store's table, then each fact's speaker, with the facts stored before speakers
+	 * existed given to `ownerId`, whose they were.
+	 */
+	static migrations(ownerId: string): Migration[] {
+		return [
+			OwnerMemoryStore.migration,
+			{
+				name: "owner-memory-speaker",
+				up: async (sql) => {
+					await sql.begin(async (tx) => {
+						await tx`SELECT pg_advisory_xact_lock(7284912302)`;
+						await tx`ALTER TABLE owner_memory ADD COLUMN IF NOT EXISTS speaker_id text`;
+						await tx`UPDATE owner_memory SET speaker_id = ${ownerId} WHERE speaker_id IS NULL`;
+						await tx`ALTER TABLE owner_memory ALTER COLUMN speaker_id SET NOT NULL`;
+						await tx`CREATE INDEX IF NOT EXISTS owner_memory_speaker ON owner_memory (speaker_id, id)`;
+					});
+				},
+			},
+		];
+	}
+
+	/** The store over the host's migrated pool, holding one speaker's memory. */
+	static attach(sql: SQL, speakerId: string): OwnerMemoryStore {
+		return new OwnerMemoryStore(sql, speakerId);
+	}
+
+	/** Another speaker's memory in the same database. */
+	forSpeaker(speakerId: string): OwnerMemoryStore {
+		return speakerId === this.speakerId
+			? this
+			: new OwnerMemoryStore(this.#sql, speakerId);
+	}
+
+	async list(): Promise<OwnerMemory[]> {
+		const rows: Row[] = await this.#sql`
+			SELECT id, kind, fact, to_char(event_date, 'YYYY-MM-DD') AS event_date
+			FROM owner_memory WHERE speaker_id = ${this.speakerId} ORDER BY id`;
+		return rows.map(toMemory);
+	}
+
+	async forPrompt(today: string): Promise<OwnerPromptMemory> {
+		const rows: Row[] = await this.#sql`
+			SELECT id, kind, fact, to_char(event_date, 'YYYY-MM-DD') AS event_date
+			FROM owner_memory
+			WHERE speaker_id = ${this.speakerId}
+				AND (kind = 'core' OR (kind = 'event' AND event_date >= ${today}::date))
+			ORDER BY event_date NULLS FIRST, id`;
+		const memories = rows.map(toMemory);
+		return {
+			core: memories.filter((memory) => memory.kind === "core"),
+			events: memories.filter((memory) => memory.kind === "event"),
+		};
+	}
+
+	async add(
+		fact: string,
+		kind: OwnerMemoryKind = "core",
+		eventDate?: string,
+	): Promise<OwnerMemory> {
+		const trimmed = checkedFact(fact, kind, eventDate);
+		const [row]: Row[] = await this.#sql`
+			INSERT INTO owner_memory (speaker_id, fact, kind, event_date)
+			VALUES (${this.speakerId}, ${trimmed}, ${kind}, ${eventDate ?? null}::date)
+			RETURNING id, kind, fact, to_char(event_date, 'YYYY-MM-DD') AS event_date`;
+		if (!row) throw new MemoryError("the memory was not saved");
+		return toMemory(row);
+	}
+
+	/**
+	 * Memories containing any query term, case-insensitively, most terms matched first,
+	 * then newest first.
+	 */
+	async search(query: string, limit = SEARCH_LIMIT): Promise<OwnerMemory[]> {
+		const terms = searchTerms(query);
+		if (terms.length === 0) throw new MemoryError("the search query is empty");
+		const rows: (Row & { hits: number })[] = await this.#sql`
+			SELECT id, kind, fact, to_char(event_date, 'YYYY-MM-DD') AS event_date, hits
+			FROM (
+				SELECT *, (
+					SELECT count(*) FROM jsonb_array_elements_text(${terms}::jsonb) AS term
+					WHERE strpos(lower(fact), term) > 0
+				) AS hits
+				FROM owner_memory WHERE speaker_id = ${this.speakerId}
+			) AS scored
+			WHERE hits > 0
+			ORDER BY hits DESC, updated_at DESC, id DESC
+			LIMIT ${limit}`;
+		return rows.map(toMemory);
+	}
+
+	/** Replaces one memory's text, kind, and date under `add`'s rules; undefined when the id is unknown. */
+	async update(
+		id: number,
+		change: { fact: string; kind: OwnerMemoryKind; eventDate?: string },
+	): Promise<OwnerMemory | undefined> {
+		const trimmed = checkedFact(change.fact, change.kind, change.eventDate);
+		const [row]: Row[] = await this.#sql`
+			UPDATE owner_memory
+			SET fact = ${trimmed}, kind = ${change.kind},
+				event_date = ${change.eventDate ?? null}::date, updated_at = now()
+			WHERE speaker_id = ${this.speakerId} AND id = ${id}
+			RETURNING id, kind, fact, to_char(event_date, 'YYYY-MM-DD') AS event_date`;
+		return row ? toMemory(row) : undefined;
+	}
+
+	/** Deletes one memory; false when the id is unknown. */
+	async removeById(id: number): Promise<boolean> {
+		const rows = await this.#sql`DELETE FROM owner_memory
+			WHERE speaker_id = ${this.speakerId} AND id = ${id} RETURNING id`;
+		return rows.length > 0;
+	}
+
+	/** Deletes every memory containing the text, case-insensitively; returns the removed facts. */
+	async remove(text: string): Promise<string[]> {
+		const needle = text.trim();
+		if (!needle) throw new MemoryError("the text to forget cannot be empty");
+		const rows: { fact: string }[] = await this.#sql`
+			DELETE FROM owner_memory
+			WHERE speaker_id = ${this.speakerId} AND strpos(lower(fact), lower(${needle})) > 0
+			RETURNING fact`;
+		return rows.map((row) => row.fact);
+	}
+}

package/src/core/modules/memory/owner-memory.ts

@@ -0,0 +1,153 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { messages } from "../../i18n/index.ts";
+import { type OwnerIdentity, ownerWords } from "../../identity.ts";
+import { toolError, toolText } from "../../shared/tool-result.ts";
+import type { Speaker } from "../../speakers.ts";
+import { timeZone, zonedToday } from "../../time.ts";
+import type {
+	OwnerMemory,
+	OwnerMemoryStore,
+	OwnerPromptMemory,
+} from "./owner-memory-store.ts";
+
+function line(memory: OwnerMemory): string {
+	return memory.eventDate
+		? `- ${memory.eventDate}: ${memory.fact}`
+		: `- ${memory.fact}`;
+}
+
+export function ownerMemorySection(
+	memory: OwnerPromptMemory,
+	today: string,
+	/** Whose memory it is, when not the owner's. */
+	speaker?: Speaker,
+): string {
+	const core =
+		memory.core.length > 0
+			? memory.core.map(line).join("\n")
+			: "(nothing remembered yet)";
+	const events =
+		memory.events.length > 0 ? memory.events.map(line).join("\n") : "(none)";
+	return [
+		speaker ? `## Memory of ${speaker.name}` : "## Owner memory",
+		`Today in ${messages().zoneName(timeZone())} is ${today}. What is stored right now, including anything you added earlier in this conversation; each appears once.`,
+		`### Core facts\n${core}`,
+		`### Upcoming events\n${events}`,
+		"Notes (projects, people, references, past events) are not listed here. Use memory_search when a request may depend on them.",
+	].join("\n\n");
+}
+
+/**
+ * Adds the owner's core facts and upcoming events to every run, and registers
+ * memory_add, memory_search, and memory_remove. The section goes into appendSystemPrompt
+ * because claude-bridge forwards only the prompt's option sections to Claude Code, not a
+ * replaced system prompt.
+ */
+export function ownerMemoryExtension(
+	ownerStore: OwnerMemoryStore,
+	owner: OwnerIdentity,
+	/**
+	 * The person the running turn is for, in a session that serves several. Their memory, not
+	 * the owner's, is what the turn reads and changes; without it every turn is the owner's.
+	 */
+	speaker?: () => Speaker | undefined,
+): ExtensionFactory {
+	const o = ownerWords(owner);
+	/** The running turn's other speaker; undefined when the owner's own memory applies. */
+	const other = (): Speaker | undefined => {
+		const current = speaker?.();
+		return current && current.id !== ownerStore.speakerId ? current : undefined;
+	};
+	const storeOf = () => {
+		const current = other();
+		return current ? ownerStore.forSpeaker(current.id) : ownerStore;
+	};
+	const shared = speaker
+		? " Whoever is speaking has a memory of their own, shared by every agent; this reads and changes theirs, not someone else's."
+		: "";
+	return (pi) => {
+		pi.on("before_agent_start", async (event) => {
+			const today = zonedToday();
+			const section = ownerMemorySection(
+				await storeOf().forPrompt(today),
+				today,
+				other(),
+			);
+			const appended = event.systemPromptOptions.appendSystemPrompt;
+			event.systemPromptOptions.appendSystemPrompt = appended
+				? `${appended}\n\n${section}`
+				: section;
+		});
+
+		pi.registerTool({
+			name: "memory_add",
+			label: "Remember",
+			description: `Remember one fact about ${o.name} for future conversations, when ${o.he} asks you to or when it will clearly matter later. Search first and do not store what is already there. kind core: a stable fact about who ${o.he} is or how ${o.he} wants things done; it is shown in every conversation, so keep core facts few and short. kind note: projects, people, references, and other details worth finding later with memory_search. kind event: something happening on a date, shown until that date passes.${shared}`,
+			parameters: Type.Object({
+				fact: Type.String({
+					description:
+						"One self-contained fact, written so it makes sense on its own later.",
+				}),
+				kind: Type.Union(
+					[Type.Literal("core"), Type.Literal("note"), Type.Literal("event")],
+					{ description: "core, note, or event." },
+				),
+				date: Type.Optional(
+					Type.String({
+						description: "For an event: its date as YYYY-MM-DD.",
+					}),
+				),
+			}),
+			execute: async (_toolCallId, params) => {
+				const saved = await storeOf().add(
+					params.fact,
+					params.kind,
+					params.date,
+				);
+				return toolText(`Remembered as ${saved.kind}: ${line(saved).slice(2)}`);
+			},
+		});
+
+		pi.registerTool({
+			name: "memory_search",
+			label: "Search memory",
+			description: `Search everything remembered about ${o.name}, including notes and past events. Give a few short keywords separated by spaces, in the language the memory is likely written in; results contain any of them, best matches first.${shared}`,
+			parameters: Type.Object({
+				query: Type.String({ description: "Keywords separated by spaces." }),
+			}),
+			execute: async (_toolCallId, params) => {
+				const found = await storeOf().search(params.query);
+				return toolText(
+					found.length === 0
+						? `Nothing remembered matches "${params.query}".`
+						: found
+								.map((memory) => `- [${memory.kind}] ${line(memory).slice(2)}`)
+								.join("\n"),
+				);
+			},
+		});
+
+		pi.registerTool({
+			name: "memory_remove",
+			label: "Forget",
+			description: `Forget remembered facts about ${o.name}. Removes every remembered fact that contains the given text.${shared}`,
+			parameters: Type.Object({
+				text: Type.String({
+					description: "Text contained in the fact or facts to forget.",
+				}),
+			}),
+			execute: async (_toolCallId, params) => {
+				const removed = await storeOf().remove(params.text);
+				if (removed.length === 0) {
+					return toolError(
+						`No remembered fact contains "${params.text}". Nothing was forgotten.`,
+					);
+				}
+				return toolText(
+					`Forgot:\n${removed.map((fact) => `- ${fact}`).join("\n")}`,
+				);
+			},
+		});
+	};
+}

package/src/core/modules/notify/notify.ts

@@ -0,0 +1,26 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { OwnerNotifier } from "../../domain/ports.ts";
+import { type OwnerIdentity, ownerWords } from "../../identity.ts";
+import { toolText } from "../../shared/tool-result.ts";
+
+export function notifyExtension(
+	notifier: OwnerNotifier,
+	owner: OwnerIdentity,
+): ExtensionFactory {
+	const o = ownerWords(owner);
+	return (pi) => {
+		pi.registerTool({
+			name: "notify_owner",
+			label: "Notify owner",
+			description: `Send ${o.name} a direct message on Discord. Use only when ${o.he} asks to be notified or reminded by DM; your normal reply already reaches ${o.him}.`,
+			parameters: Type.Object({
+				text: Type.String({ description: "The message to send." }),
+			}),
+			execute: async (_toolCallId, params) => {
+				await notifier.notifyOwner(params.text);
+				return toolText("Sent.");
+			},
+		});
+	};
+}

package/src/core/modules/schedules/recurrence.ts

@@ -0,0 +1,206 @@
+import { ScheduleError } from "../../domain/errors.ts";
+import { messages } from "../../i18n/index.ts";
+import { timeZone, zonedDate, zonedInstant, zonedStamp } from "../../time.ts";
+
+export const WEEKDAYS = [
+	"sun",
+	"mon",
+	"tue",
+	"wed",
+	"thu",
+	"fri",
+	"sat",
+] as const;
+export type Weekday = (typeof WEEKDAYS)[number];
+
+/** When a schedule runs, in the configured wall-clock time. */
+export type Recurrence =
+	| { kind: "once"; date: string; time: string; instant?: string }
+	| { kind: "every"; time: string; everyDays: number; startDate: string }
+	| { kind: "weekly"; time: string; weekdays: Weekday[] };
+
+const DAY_MS = 86_400_000;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TIME = /^([01]\d|2[0-3]):[0-5]\d$/;
+
+function dayIndex(date: string): number {
+	return Date.parse(`${date}T00:00:00Z`) / DAY_MS;
+}
+
+function addDays(date: string, days: number): string {
+	return new Date((dayIndex(date) + days) * DAY_MS).toISOString().slice(0, 10);
+}
+
+function weekday(date: string): Weekday {
+	return WEEKDAYS[new Date(`${date}T00:00:00Z`).getUTCDay()] ?? "sun";
+}
+
+/** The first run strictly after `after`, or undefined when a one-time schedule has passed. */
+export function nextRun(recurrence: Recurrence, after: Date): Date | undefined {
+	switch (recurrence.kind) {
+		case "once": {
+			const at = recurrence.instant
+				? new Date(recurrence.instant)
+				: zonedInstant(recurrence.date, recurrence.time);
+			return at > after ? at : undefined;
+		}
+		case "every": {
+			const { startDate, everyDays, time } = recurrence;
+			const behind = dayIndex(zonedDate(after)) - dayIndex(startDate);
+			let step = Math.max(0, Math.ceil(behind / everyDays));
+			for (;;) {
+				const at = zonedInstant(addDays(startDate, step * everyDays), time);
+				if (at > after) return at;
+				step += 1;
+			}
+		}
+		case "weekly": {
+			const today = zonedDate(after);
+			for (let offset = 0; offset <= 7; offset += 1) {
+				const date = addDays(today, offset);
+				if (!recurrence.weekdays.includes(weekday(date))) continue;
+				const at = zonedInstant(date, recurrence.time);
+				if (at > after) return at;
+			}
+			throw new ScheduleError("a weekly schedule needs at least one weekday");
+		}
+		default:
+			throw new ScheduleError("unknown recurrence kind");
+	}
+}
+
+/** The recurrence in the owner's words, for tool answers and panels. */
+export function describeRecurrence(recurrence: Recurrence): string {
+	const text = messages();
+	switch (recurrence.kind) {
+		case "once":
+			return text.scheduleOnce(recurrence.date, recurrence.time);
+		case "every":
+			return recurrence.everyDays === 1
+				? text.scheduleDaily(recurrence.time)
+				: text.scheduleEveryDays(
+						recurrence.everyDays,
+						recurrence.time,
+						recurrence.startDate,
+					);
+		case "weekly":
+			return text.scheduleWeekly(
+				recurrence.weekdays.map((d) => text.scheduleWeekday(d)),
+				recurrence.time,
+			);
+		default:
+			throw new ScheduleError("unknown recurrence kind");
+	}
+}
+
+export interface RecurrenceInput {
+	in_minutes?: unknown;
+	at?: unknown;
+	time?: unknown;
+	every_days?: unknown;
+	start_date?: unknown;
+	weekdays?: unknown;
+}
+
+function validDate(value: string): boolean {
+	return (
+		DATE.test(value) &&
+		new Date(`${value}T00:00:00Z`).toISOString().startsWith(value)
+	);
+}
+
+const MAX_MINUTES = 366 * 24 * 60;
+
+/**
+ * Reads the tool fields that set timing: `in_minutes` or `at` for one run, or `time` with either
+ * `every_days` (and an optional `start_date`) or `weekdays`. Throws ScheduleError with a
+ * message the model can act on.
+ */
+export function parseRecurrence(input: RecurrenceInput, now: Date): Recurrence {
+	const { in_minutes, at, time, every_days, start_date, weekdays } = input;
+	if (in_minutes !== undefined) {
+		if (
+			[at, time, every_days, start_date, weekdays].some((v) => v !== undefined)
+		)
+			throw new ScheduleError(
+				"in_minutes sets one run on its own; do not combine it with other timing",
+			);
+		if (
+			typeof in_minutes !== "number" ||
+			!Number.isInteger(in_minutes) ||
+			in_minutes < 1 ||
+			in_minutes > MAX_MINUTES
+		)
+			throw new ScheduleError(
+				"in_minutes must be a whole number of minutes, at least 1",
+			);
+		// Rounded up to the minute, so the run is never earlier than asked.
+		const target = new Date(
+			Math.ceil((now.getTime() + in_minutes * 60_000) / 60_000) * 60_000,
+		);
+		const [date = "", clock = ""] = zonedStamp(target).split(" ");
+		// A relative request in the second occurrence of a fall-back hour must not
+		// silently move to the first occurrence of that same wall-clock minute.
+		const first = zonedInstant(date, clock);
+		return first.getTime() === target.getTime()
+			? { kind: "once", date, time: clock }
+			: { kind: "once", date, time: clock, instant: target.toISOString() };
+	}
+	if (at !== undefined) {
+		if (
+			time !== undefined ||
+			every_days !== undefined ||
+			weekdays !== undefined
+		)
+			throw new ScheduleError(
+				"give either at (one run) or time (repeating), not both",
+			);
+		const match =
+			typeof at === "string"
+				? /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2})$/.exec(at.trim())
+				: null;
+		const [, date = "", clock = ""] = match ?? [];
+		if (!match || !validDate(date) || !TIME.test(clock))
+			throw new ScheduleError(messages().atTimeError(timeZone()));
+		return { kind: "once", date, time: clock };
+	}
+	if (typeof time !== "string" || !TIME.test(time.trim()))
+		throw new ScheduleError(messages().repeatingTimeError(timeZone()));
+	const clock = time.trim();
+	if (weekdays !== undefined) {
+		if (every_days !== undefined || start_date !== undefined)
+			throw new ScheduleError(
+				"weekdays cannot be combined with every_days or start_date",
+			);
+		const days = Array.isArray(weekdays)
+			? weekdays.map((d) => String(d).trim().toLowerCase().slice(0, 3))
+			: [];
+		if (
+			days.length === 0 ||
+			!days.every((d): d is Weekday =>
+				(WEEKDAYS as readonly string[]).includes(d),
+			)
+		)
+			throw new ScheduleError(
+				`weekdays must be a list of ${WEEKDAYS.join(", ")}`,
+			);
+		return {
+			kind: "weekly",
+			time: clock,
+			weekdays: WEEKDAYS.filter((d) => days.includes(d)),
+		};
+	}
+	const everyDays = every_days === undefined ? 1 : every_days;
+	if (
+		typeof everyDays !== "number" ||
+		!Number.isInteger(everyDays) ||
+		everyDays < 1 ||
+		everyDays > 365
+	)
+		throw new ScheduleError("every_days must be a whole number from 1 to 365");
+	const startDate =
+		start_date === undefined ? zonedDate(now) : String(start_date).trim();
+	if (!validDate(startDate))
+		throw new ScheduleError('start_date must be "YYYY-MM-DD"');
+	return { kind: "every", time: clock, everyDays, startDate };
+}