pi-roundtable 0.7.19 → 0.9.0

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 { modulesPlugin } from "../builtin/modules.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,16 +41,66 @@ 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: { agentChannelOf?: (name: string) => ChannelKey } = {},
+	options: {
+		agentChannelOf?: (name: string) => ChannelKey;
+		/** Whether Discord is there; default true. A host without it has no owner's messages. */
+		discord?: boolean;
+		/** Whether a plugin contributes the owner's background target, as the agent server does; default true. */
+		ownerTarget?: boolean;
+		/** Whether a claim owns a channel; by default the Discord channels are owned and no other. */
+		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;
 	contribution: Contribution;
 	record: ModuleRecord;
 	services: ServiceRegistry;
@@ -44,13 +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,
@@ -61,58 +144,86 @@ export async function setUpModules(
 			thinking: "low",
 			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);
-	// SAFETY: the schedule tools ask the agent team for a channel and nothing else.
+	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, {
 			team: { channelOf: options.agentChannelOf },
 		} as unknown as AgentServer);
-	// SAFETY: the tools under test use the connection's owner channel and the threads' open only.
-	services.preset(DISCORD, {
-		connection: {
-			ownerChannel: async () => {
-				record.ownerChannelAsked += 1;
-				return OWNER_CHANNEL;
+	if (options.discord !== false)
+		// SAFETY: the tools under test use the connection's owner channel and the threads' open only.
+		services.preset(DISCORD, {
+			connection: {
+				ownerChannel: async () => {
+					record.ownerChannelAsked += 1;
+					return OWNER_CHANNEL;
+				},
+				ownerOperations: () => ({}),
 			},
-			ownerOperations: () => ({}),
-		},
-		threads: {
-			open: async (origin: ChannelKey | undefined) => {
-				record.threadOrigins.push(origin);
-				return undefined;
+			threads: {
+				open: async (origin: ChannelKey | undefined) => {
+					record.threadOrigins.push(origin);
+					return undefined;
+				},
 			},
+			guard: {},
+			commands: { add: () => undefined },
+		} as unknown as DiscordServices);
+	const owns =
+		options.owns ?? ((channel: ChannelKey) => channel.startsWith("discord:"));
+	// 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("") }),
 		},
-		guard: {},
-		commands: { add: () => undefined },
-	} as unknown as DiscordServices);
-	// SAFETY: setup reads only the logger, the conversations' background and targets, the surfaces, and the services.
+	]);
+	// 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) =>
-				name === OWNER_TARGET.name ? OWNER_TARGET : undefined,
+				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 () => undefined,
-			},
-		]),
+		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))),
 	);
-	return { contribution, record, services };
+	return { plugin, contribution, record, services };
 }
 
 /** What each addon plugin contributes, set up over stand-ins as far as setup reads them. */

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,
 };