pi-roundtable 0.8.0 → 0.9.1

package/src/core/speakers.ts

@@ -1,4 +1,8 @@
 import { freeze } from "./freeze.ts";
+import {
+	rulesOfSpeakerMap,
+	speakerPolicyOf,
+} from "./identity/access-policy.ts";
 import type { OwnerIdentity } from "./identity.ts";
 
 /** How much a speaker may do: `owner` above `admin` above `member`. */
@@ -12,9 +16,16 @@ export function tierAtLeast(tier: Tier, least: Tier): boolean {
 
 /** A person whose message starts a turn, and the tier the policy gave them. */
 export interface Speaker {
+	/** The id the surface knows them by: a Discord user id, a web chat's `oidc:<issuer>:<subject>`. */
 	id: string;
 	name: string;
 	tier: Tier;
+	/**
+	 * The principal they are, whose memory, schedules, and conversations are theirs on every
+	 * surface. For a person carried over from 0.8 it equals `id`. The identity service sets it;
+	 * whoever starts a turn for someone else takes it from `IDENTITY.speakerFor`.
+	 */
+	principalId: string;
 }
 
 /**
@@ -59,7 +70,10 @@ export function attributed(speaker: Speaker, text: string): string {
 	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. */
+/**
+ * What a surface reports about the author of a message; the policy decides the rest. The 0.8
+ * form of `ActorFacts` from the identity service, with the surface's own ids and role ids.
+ */
 export interface SpeakerFacts {
 	id: string;
 	name: string;
@@ -92,23 +106,11 @@ export interface SpeakerMap {
 	members?: TierMembers;
 }
 
-/** The policy of an operator's map; the highest tier an author qualifies for wins. */
+/**
+ * The policy of an operator's map; the highest tier an author qualifies for wins. It evaluates
+ * the access rules the map means on one surface, so it decides as the identity service's rules
+ * do; each speaker's principal is their own id, as for a person carried over from 0.8.
+ */
 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 };
-		},
-	};
+	return speakerPolicyOf(rulesOfSpeakerMap(map));
 }

package/src/core/testing/background.ts

@@ -0,0 +1,31 @@
+import type { BackgroundRunsAs, BackgroundTurn } from "../contract/channels.ts";
+import type { Schedule } from "../modules/schedules/schedule-store.ts";
+
+/** A conversation port's `runsAs` for tests: every turn runs as its author, at its own tier. */
+export async function runsAsAuthor(
+	turn: BackgroundTurn,
+): Promise<BackgroundRunsAs> {
+	const { author, tier } = turn;
+	return {
+		speaker: {
+			id: author.id,
+			name: author.name,
+			tier,
+			principalId: author.principalId,
+		},
+	};
+}
+
+/** A scheduled runner's `runsAs` for tests: every schedule runs as its creator, at the tier it was set at. */
+export async function runsAsCreator(
+	schedule: Schedule,
+): Promise<BackgroundRunsAs> {
+	return {
+		speaker: {
+			id: schedule.createdById,
+			name: schedule.createdByName,
+			tier: schedule.createdTier,
+			principalId: schedule.createdById,
+		},
+	};
+}

package/src/core/testing/fixture-database.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { SQL } from "bun";
+import { testDatabaseUrl } from "./database.ts";
+
+/** A scratch database on the test server; drop it when the test ends. */
+export interface ScratchDatabase {
+	url: string;
+	sql: SQL;
+	drop(): Promise<void>;
+}
+
+/**
+ * A new, empty database on the test server, or one loaded from a recorded fixture such as
+ * `"0.8.0"` (src/core/testing/fixtures/db-<version>.sql, written by scripts/fixture-db.ts). It
+ * needs PostgreSQL: run it under `describeDb`.
+ */
+export async function scratchDatabase(
+	fixture?: string,
+): Promise<ScratchDatabase> {
+	const name = `roundtable_scratch_${crypto.randomUUID().replaceAll("-", "")}`;
+	let url: URL;
+	try {
+		url = new URL(testDatabaseUrl);
+	} catch {
+		throw new Error(
+			`ROUNDTABLE_TEST_DATABASE_URL is not a postgres url: ${testDatabaseUrl}`,
+		);
+	}
+	url.pathname = `/${name}`;
+	const server = new SQL(testDatabaseUrl, { max: 1 });
+	await server.unsafe(`CREATE DATABASE ${name}`);
+	await server.close();
+	const sql = new SQL(url.href, { max: 4 });
+	if (fixture)
+		await sql.unsafe(
+			readFileSync(
+				join(import.meta.dir, "fixtures", `db-${fixture}.sql`),
+				"utf8",
+			),
+		);
+	return {
+		url: url.href,
+		sql,
+		drop: async () => {
+			await sql.close();
+			const admin = new SQL(testDatabaseUrl, { max: 1 });
+			try {
+				await admin.unsafe(`DROP DATABASE IF EXISTS ${name} WITH (FORCE)`);
+			} finally {
+				await admin.close();
+			}
+		},
+	};
+}

package/src/core/testing/map-identity.ts

@@ -0,0 +1,76 @@
+import { IdentityError } from "../domain/errors.ts";
+import type { ActorFacts } from "../identity/actor-facts.ts";
+import type { ContactAssessor } from "../identity/contact.ts";
+import type { IdentityService } from "../identity/identity-service.ts";
+import type { IdentityLink, Principal } from "../identity/principal-store.ts";
+import { type SpeakerMap, speakerPolicy, tierAtLeast } from "../speakers.ts";
+
+/**
+ * Who a 0.8 speaker map serves, for a test without a database: each person their own principal,
+ * as one carried over from 0.8 is, and nothing written; a background turn runs as the person of
+ * its principal id at the map's tier for their id with no roles. It resolves as the router's assessor
+ * and as the `resolve` of `IDENTITY`; its owners are the map's, and a person has a Discord
+ * identity once the map names their user id or they have been resolved through it.
+ */
+export function mapIdentity(
+	map: SpeakerMap,
+): ContactAssessor &
+	Pick<IdentityService, "resolve" | "owners" | "identities" | "speakerFor"> {
+	const policy = speakerPolicy(map);
+	const linked = new Set([
+		...map.owners,
+		...(map.admins?.users ?? []),
+		...(map.members?.users ?? []),
+	]);
+	const resolve = async (facts: ActorFacts) => {
+		const speaker = policy.resolve({
+			id: facts.subject,
+			name: facts.name,
+			roleIds: (facts.roles ?? []).map((role) =>
+				role.replace(/^discord:role:/, ""),
+			),
+		});
+		if (speaker) linked.add(speaker.id);
+		return speaker;
+	};
+	const principal = (id: string): Principal => ({
+		id,
+		displayName: id,
+		disabled: false,
+	});
+	return {
+		resolve,
+		assess: async (facts) => {
+			const speaker = await resolve(facts);
+			return speaker && { speaker, take: async () => speaker };
+		},
+		owners: async () => map.owners.map(principal),
+		// Whom a background turn runs as: the person of the id at the map's tier for them, or lower.
+		speakerFor: async (principalId, tier) => {
+			const own = policy.resolve({
+				id: principalId,
+				name: principalId,
+				roleIds: [],
+			})?.tier;
+			if (!own) throw new IdentityError(`there is no principal ${principalId}`);
+			return {
+				id: principalId,
+				name: principalId,
+				tier: tier && tierAtLeast(own, tier) ? tier : own,
+				principalId,
+			};
+		},
+		identities: async (principalId): Promise<IdentityLink[]> =>
+			linked.has(principalId)
+				? [
+						{
+							provider: "discord",
+							subject: principalId,
+							principalId,
+							source: "legacy",
+							linkedAt: new Date(0),
+						},
+					]
+				: [],
+	};
+}

package/src/core/testing/module-sessions.ts

@@ -0,0 +1,134 @@
+import type {
+	ExtensionAPI,
+	ExtensionFactory,
+} from "@earendil-works/pi-coding-agent";
+import type { OwnerIdentity } from "../identity.ts";
+import type {
+	AgentTurnScope,
+	ChannelKey,
+	SessionContext,
+} from "../sessions.ts";
+import { type Speaker, THE_SPEAKER } from "../speakers.ts";
+import { OWNER_CHANNEL, type setUpModules } from "./modules.ts";
+import { OWNER_SPEAKER } from "./owner.ts";
+
+/** Sessions, people, and tool calls the modules' tests share. */
+export const HOME: ChannelKey = "discord:scout";
+export const GROUP: ChannelKey = "discord:war-room";
+export const OUTSIDE: ChannelKey = "other:table-1";
+
+export const scout: AgentTurnScope = {
+	name: "scout",
+	session: HOME,
+	home: HOME,
+};
+export const seat: AgentTurnScope = {
+	name: "scout",
+	session: GROUP,
+	home: HOME,
+	group: "war-room",
+};
+
+export function context(
+	agent?: AgentTurnScope,
+	home?: ChannelKey,
+): SessionContext {
+	const session: SessionContext = {
+		kind: agent ? "agent" : "owner",
+		homeChannel: home ?? agent?.home ?? OWNER_CHANNEL,
+		turnChannel: agent?.session ?? home ?? OWNER_CHANNEL,
+		compaction: { wrap: (compactor) => compactor },
+		// Shared, as the host makes a session it has no record of; `privateTo` makes it someone's.
+		conversation: { visibility: "shared" },
+		addressee: THE_SPEAKER,
+		memory: "speaker",
+		// A turn of the owner's runs, as every tool call is part of one.
+		speaker: () => OWNER_SPEAKER,
+		runTask: async () => "report",
+	};
+	if (agent) session.agent = agent;
+	return session;
+}
+
+/** A session of a conversation of the owner's kind whose turns are someone else's. */
+export function contextOf(speaker: Speaker, home: ChannelKey): SessionContext {
+	return { ...context(undefined, home), speaker: () => speaker };
+}
+
+/** An admin who is not the primary owner, such as one a remote MCP token is bound to. */
+export const ANN: Speaker = {
+	id: "p_ann",
+	name: "Ann",
+	tier: "admin",
+	principalId: "p_ann",
+};
+
+export interface Registered {
+	name: string;
+	parameters: { properties: Record<string, unknown> };
+	execute(
+		id: string,
+		params: unknown,
+	): Promise<{ content: { text: string }[]; isError?: boolean }>;
+}
+
+/** The extension one of the modules' session tools gives a session; null when it gives none. */
+export function factoryOf(
+	setup: Awaited<ReturnType<typeof setUpModules>>,
+	name: string,
+	session: SessionContext,
+): ExtensionFactory | null | undefined {
+	return setup.contribution.sessionTools
+		?.find((tool) => tool.name === name)
+		?.snapshot()
+		.factory(session);
+}
+
+/** The tools one of the modules' extensions registers in a session. */
+export async function registered(
+	setup: Awaited<ReturnType<typeof setUpModules>>,
+	session: SessionContext,
+	extension: string,
+): Promise<Registered[]> {
+	const tool = setup.contribution.sessionTools?.find(
+		(candidate) => candidate.name === extension,
+	);
+	const factory: ExtensionFactory | null | undefined = tool
+		?.snapshot()
+		.factory(session);
+	if (!factory) throw new Error(`no ${extension} extension`);
+	const tools: Registered[] = [];
+	await factory({
+		registerTool: (definition: Registered) => tools.push(definition),
+		on: () => undefined,
+	} as unknown as ExtensionAPI);
+	return tools;
+}
+
+/** The session of a conversation private to `principalId`, its tools addressing them as given. */
+export function privateTo(
+	session: SessionContext,
+	principalId: string,
+	addressee: OwnerIdentity = THE_SPEAKER,
+): SessionContext {
+	return {
+		...session,
+		conversation: { visibility: "private", principalId },
+		addressee,
+	};
+}
+
+/** Runs notify in a session; the tool's answer and whether it was an error. */
+export async function notifyIn(
+	setup: Awaited<ReturnType<typeof setUpModules>>,
+	session: SessionContext,
+	text = "the build is green",
+) {
+	const [notify] = await registered(setup, session, "notify");
+	if (!notify) return undefined;
+	const answer = await notify.execute("1", { text });
+	return {
+		text: answer.content[0]?.text ?? "",
+		error: answer.isError === true,
+	};
+}

package/src/core/testing/modules.ts

@@ -1,13 +1,16 @@
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import type { SQL } from "bun";
-import { OWNER_TARGET } from "../agents/agent-claim.ts";
 import { DISCORD, type DiscordServices } from "../builtin/discord.ts";
 import { discordAdminPlugin } from "../builtin/discord-admin.ts";
 import { type ModulesOptions, modulesPlugin } from "../builtin/modules.ts";
 import { skillsPlugin } from "../builtin/skills.ts";
 import { memoryPlugin } from "../builtin/stores.ts";
+import type { ConversationRegistry } from "../conversations/conversation-registry.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
+import type { IdentityService } from "../identity/identity-service.ts";
+import type { Principal } from "../identity/principal-store.ts";
 import { silentLogger } from "../log.ts";
+import { PERSONAL_TARGET } from "../modules/background/personal-target.ts";
 import type { SkillStore } from "../modules/skills/skill-store.ts";
 import {
 	type Contribution,
@@ -15,10 +18,22 @@ import {
 	pluginContext,
 	type RoundtablePlugin,
 } from "../plugin.ts";
+import {
+	type DirectChannelProvider,
+	directChannelsPort,
+} from "../presence/direct-channels.ts";
 import { ServiceRegistry } from "../registry/services.ts";
 import { surfacePort } from "../routing/surface-port.ts";
 import type { AgentServer, MemoryStore, ScheduleStore } from "../services.ts";
-import { AGENTS, MEMORY, SCHEDULES } from "../services.ts";
+import {
+	AGENTS,
+	CONVERSATIONS,
+	IDENTITY,
+	MEMORY,
+	SCHEDULES,
+} from "../services.ts";
+import type { Tier } from "../speakers.ts";
+import { toolTiers } from "../tool-tiers.ts";
 
 /** What the modules' tools did, for a test to read. */
 export interface ModuleRecord {
@@ -26,14 +41,28 @@ export interface ModuleRecord {
 	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. */
+	/** How often anything asked the connection for the primary owner's messages, which the modules no longer read. */
 	ownerChannelAsked: number;
+	/** Whose direct channel was asked for, in order. */
+	directAsked: string[];
+	/** The notices sent through a direct channel, by principal. */
+	notified: { principalId: string; text: string }[];
 	/** What was posted on the surface, by channel. */
 	posted: { channel: ChannelKey; text: string }[];
 }
 
 export const OWNER_CHANNEL: ChannelKey = "discord:owner-dm";
 
+/** The primary owner the modules serve: principal "1". */
+export const MODULES_OWNER = {
+	id: "1",
+	name: "Owner",
+	pronouns: { subject: "they", object: "them", possessive: "their" },
+};
+
+/** The direct messages the stand-in Discord provider reaches by default: the owner's, principal "1". */
+const DIRECT: Readonly<Record<string, ChannelKey>> = { "1": OWNER_CHANNEL };
+
 /** The modules plugin set up over stand-in stores and surface; returns its contribution and the record. */
 export async function setUpModules(
 	options: {
@@ -46,7 +75,29 @@ export async function setUpModules(
 		owns?: (channel: ChannelKey) => boolean;
 		/** Whether the claim owning a channel takes background turns; by default every owned channel's does. */
 		takesBackground?: (channel: ChannelKey) => boolean;
+		/** Whether the claim owning a channel takes the host's own turns; by default every owned channel's does. */
+		takesSystemReports?: (channel: ChannelKey) => boolean;
 		errorReporter?: ModulesOptions["errorReporter"];
+		/** The schedules the tools keep; by default a stub that answers nothing. */
+		schedules?: ScheduleStore;
+		/** The conversations the host records, which say whose a conversation is; by default none is recorded. */
+		conversations?: Pick<ConversationRegistry, "get">;
+		/**
+		 * Each principal's direct messages on the stand-in Discord provider, the host's only direct
+		 * channel; by default the owner's are `OWNER_CHANNEL`, and without Discord there is none.
+		 */
+		direct?: Readonly<Record<string, ChannelKey>>;
+		/**
+		 * Whether the stand-in provider reaches the network, read at each `reaches`, which throws
+		 * while it does not; `knows` answers from its records either way. Default always.
+		 */
+		online?: () => boolean;
+		/** The host's owners, as `IDENTITY` lists them; by default there is no identity service. */
+		owners?: readonly Principal[];
+		/** The operator's tool tiers; by default none, so notify stays the owners'. */
+		toolTiers?: Readonly<Record<string, Tier>>;
+		/** The modules' options besides the test's own. */
+		modules?: Partial<ModulesOptions>;
 	} = {},
 ): Promise<{
 	plugin: RoundtablePlugin;
@@ -58,14 +109,31 @@ export async function setUpModules(
 		threadOrigins: [],
 		reportChannels: [],
 		ownerChannelAsked: 0,
+		directAsked: [],
+		notified: [],
 		posted: [],
 	};
+	const direct =
+		options.direct ?? (options.discord === false ? undefined : DIRECT);
+	const providers: DirectChannelProvider[] = direct
+		? [
+				{
+					name: "discord",
+					label: "a direct message on Discord",
+					knows: async (principalId) => direct[principalId] !== undefined,
+					reaches: async (principalId) => {
+						record.directAsked.push(principalId);
+						if (options.online?.() === false)
+							throw new Error("Discord is unreachable");
+						return direct[principalId];
+					},
+					deliver: async (principalId, text) =>
+						void record.notified.push({ principalId, text }),
+				},
+			]
+		: [];
 	const plugin = modulesPlugin({
-		owner: {
-			id: "1",
-			name: "Owner",
-			pronouns: { subject: "they", object: "them", possessive: "their" },
-		},
+		owner: MODULES_OWNER,
 		assistant: "Assistant",
 		// SAFETY: a worker of the test's own replaces the one that would read the runtime.
 		modelRuntime: {} as ModelRuntime,
@@ -77,11 +145,26 @@ export async function setUpModules(
 			worker: { run: async () => "found it" },
 		},
 		...(options.errorReporter ? { errorReporter: options.errorReporter } : {}),
+		...options.modules,
 	});
 	const services = new ServiceRegistry([plugin]);
 	// SAFETY: the tools under test read no store; each stub is asked for nothing else.
 	services.preset(MEMORY, {} as MemoryStore);
-	services.preset(SCHEDULES, {} as ScheduleStore);
+	services.preset(SCHEDULES, options.schedules ?? ({} as ScheduleStore));
+	if (options.conversations)
+		// SAFETY: the schedule tools only read a conversation's record.
+		services.preset(
+			CONVERSATIONS,
+			options.conversations as unknown as ConversationRegistry,
+		);
+	if (options.owners) {
+		const owners = options.owners;
+		// SAFETY: the modules ask the identity service for the owners and a principal by id only.
+		services.preset(IDENTITY, {
+			owners: async () => owners,
+			principal: async (id: string) => owners.find((owner) => owner.id === id),
+		} as unknown as IdentityService);
+	}
 	if (options.agentChannelOf)
 		// SAFETY: the schedule tools ask the agent team for a channel and nothing else.
 		services.preset(AGENTS, {
@@ -108,30 +191,34 @@ export async function setUpModules(
 		} as unknown as DiscordServices);
 	const owns =
 		options.owns ?? ((channel: ChannelKey) => channel.startsWith("discord:"));
-	// SAFETY: setup and the preflight read only the logger, the conversations' background, targets and owners, the surfaces, and the services.
+	// Only Discord's channels have a surface; any other conversation has none to report in.
+	const surfaces = surfacePort(() => [
+		{
+			surface: "discord",
+			start: async () => undefined,
+			sendReply: async (channel, reply) =>
+				void record.posted.push({ channel, text: reply.chunks.join("") }),
+		},
+	]);
+	// SAFETY: setup and the preflight read only the logger, the conversations' background, targets and owners, the surfaces, the direct channels, and the services.
 	const context = {
 		logger: silentLogger(),
 		conversations: {
 			target: (name: string) =>
-				options.ownerTarget !== false && name === OWNER_TARGET.name
-					? OWNER_TARGET
+				options.ownerTarget !== false && name === PERSONAL_TARGET.name
+					? PERSONAL_TARGET
 					: undefined,
 			owns,
 			takesBackground: options.takesBackground ?? owns,
+			takesSystemReports: options.takesSystemReports ?? owns,
 			background: async (turn: { channel: ChannelKey }) => {
 				record.reportChannels.push(turn.channel);
 				return { status: "ran" };
 			},
 		},
-		// Only Discord's channels have a surface; any other conversation has none to report in.
-		surfaces: surfacePort(() => [
-			{
-				surface: "discord",
-				start: async () => undefined,
-				sendReply: async (channel, reply) =>
-					void record.posted.push({ channel, text: reply.chunks.join("") }),
-			},
-		]),
+		surfaces,
+		directChannels: directChannelsPort(() => providers, surfaces),
+		toolTiers: toolTiers(options.toolTiers),
 	} as unknown as Omit<PluginContext, "services">;
 	const contribution = await services.setUp(plugin, () =>
 		plugin.setup(pluginContext(plugin, context, services.forPlugin(plugin))),

package/src/core/testing/owner.ts

@@ -1,3 +1,4 @@
+import type { Principal } from "../identity/principal-store.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import type { Speaker } from "../speakers.ts";
 
@@ -7,9 +8,25 @@ export const TEST_OWNER: OwnerIdentity = {
 	pronouns: { subject: "he", object: "him", possessive: "his" },
 };
 
+/** The owner as a principal of the tests, its id the owner speaker's, as for an owner carried over from 0.8. */
+export const OWNER_PRINCIPAL: Principal = {
+	id: "1",
+	displayName: TEST_OWNER.name,
+	pronouns: "he",
+	disabled: false,
+};
+
+/** A member as a principal of the tests. */
+export const MEMBER_PRINCIPAL: Principal = {
+	id: "2",
+	displayName: "Bo",
+	disabled: false,
+};
+
 /** The owner as a speaker of the tests. */
 export const OWNER_SPEAKER: Speaker = {
 	id: "1",
 	name: TEST_OWNER.name,
 	tier: "owner",
+	principalId: OWNER_PRINCIPAL.id,
 };