pi-roundtable 0.8.0 → 0.9.0

package/src/core/runtime/tool-call-scope.ts

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type {
+	ExtensionAPI,
+	ExtensionFactory,
+	ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+/** The ids of the tool calls whose code is running, outermost first. */
+const calls = new AsyncLocalStorage<readonly string[]>();
+
+/**
+ * The ids of the tool calls the code asking runs within, outermost first: the call of a session
+ * part's tool, and the calls it runs within in turn, such as a worker's call inside the call that
+ * started the worker. Empty outside every such call.
+ */
+export function runningCalls(): readonly string[] {
+	return calls.getStore() ?? [];
+}
+
+/**
+ * A session part's extension whose tools each run within their call's id, so what a call starts,
+ * a task's worker among them, knows which call it serves rather than every call running at once.
+ */
+export function scopedCalls(factory: ExtensionFactory): ExtensionFactory {
+	return (pi) =>
+		factory(
+			new Proxy(pi, {
+				get(target, key) {
+					if (key === "registerTool")
+						return (tool: ToolDefinition) =>
+							target.registerTool({
+								...tool,
+								execute: (toolCallId, ...rest) =>
+									calls.run([...runningCalls(), toolCallId], () =>
+										tool.execute(toolCallId, ...rest),
+									),
+							});
+					const value: unknown = Reflect.get(target, key, target);
+					return typeof value === "function" ? value.bind(target) : value;
+				},
+			}) satisfies ExtensionAPI,
+		);
+}

package/src/core/runtime/turn-answer.ts

@@ -1,7 +1,8 @@
-import type { TurnResult } from "../domain/conversation.ts";
+import type { TranscriptEntry, TurnResult } from "../domain/conversation.ts";
 import { AgentRunError } from "../domain/errors.ts";
 import { hasReplyFiles } from "../reply-files.ts";
 import { lastAssistant, textOf } from "../shared/session-messages.ts";
+import { TRANSCRIPT_ENTRY_CHARS } from "./runtime-types.ts";
 
 interface MessagePart {
 	type?: unknown;
@@ -20,6 +21,34 @@ type Assistant = Message & {
 const isAssistant = (message: Message): message is Assistant =>
 	message.role === "assistant";
 
+/** The answer to a turn sent without a speaker: refused, never run as the owner's by default. */
+export function unspokenTurn(): TurnResult {
+	return {
+		ok: false,
+		error: new AgentRunError(
+			"a turn needs a speaker: pass TurnRequest.speaker, the person the turn is for; for a turn started on someone's behalf, get theirs from IDENTITY.speakerFor",
+		),
+	};
+}
+
+/** The last `limit` user and assistant messages as transcript entries, each cut to its first characters. */
+export function transcriptOf(
+	messages: readonly (Message & { content?: unknown })[],
+	limit: number,
+): TranscriptEntry[] {
+	const entries: TranscriptEntry[] = [];
+	for (const message of messages) {
+		if (message.role !== "user" && message.role !== "assistant") continue;
+		const text = textOf(message.content).trim();
+		if (text)
+			entries.push({
+				role: message.role,
+				text: text.slice(0, TRANSCRIPT_ENTRY_CHARS),
+			});
+	}
+	return entries.slice(-limit);
+}
+
 /** The session's last answer, which tells the judge what a short follow-up continues. */
 export function lastReply(messages: readonly Message[]): string | undefined {
 	const last = messages.findLast(isAssistant);

package/src/core/services.ts

@@ -1,12 +1,16 @@
 import type { Agent, AgentGroup } from "./agents/agent-rules.ts";
 import type { AvatarMode } from "./agents/agent-tools.ts";
 import type { TeamStatus } from "./agents/team-status.ts";
-import type { ScheduledOutcome } from "./contract/channels.ts";
+import type {
+	BackgroundRunsAs,
+	ScheduledOutcome,
+} from "./contract/channels.ts";
 import type { AgentRuntime } from "./contract/runtime.ts";
 import { type ServiceKey, serviceKey } from "./contract/services.ts";
 import type { ConversationRegistry } from "./conversations/conversation-registry.ts";
 import type { PendingConfirmation } from "./domain/conversation.ts";
 import type { HttpRoute } from "./http/listeners.ts";
+import type { IdentityService } from "./identity/identity-service.ts";
 import type { ThinkingSetting } from "./models.ts";
 import type {
 	DelegationJob,
@@ -36,6 +40,12 @@ import type { AgentTurnScope, ChannelKey } from "./sessions.ts";
 // interface, so an object with the same methods satisfies it without being one of the built-in
 // classes; a plugin replaces a built-in by providing its own under the same key.
 
+/**
+ * Who the host serves: its principals, the identities linked to each, and their lasting roles.
+ * Provided by the `identity` plugin, which every host registers first, so every plugin may read it.
+ */
+export const IDENTITY: ServiceKey<IdentityService> =
+	serviceKey<IdentityService>("roundtable.identity");
 /**
  * The runtime every conversation turn runs on: the agent server's, and each turn run through
  * `context.turns`. The `runtime` provider slot's when a plugin fills it, Pi's otherwise. Provided
@@ -178,6 +188,16 @@ export interface AgentTeam {
 /** Scheduled turns, stored. A one-time schedule is deleted once it fires. */
 export interface ScheduleStore {
 	create(schedule: NewSchedule): Promise<Schedule>;
+	/**
+	 * Creates a schedule unless its creator already has `limit.max` of its target's schedules,
+	 * counting those whose creator id is one of `limit.creators`; resolves the count reached instead.
+	 * Two calls for one creator never count at once, so creates at once in many conversations stay
+	 * within the limit.
+	 */
+	createWithin(
+		schedule: NewSchedule,
+		limit: { creators: readonly string[]; max: number },
+	): Promise<{ created: Schedule } | { reached: number }>;
 	get(id: number): Promise<Schedule | undefined>;
 	forChannel(channel: ChannelKey): Promise<Schedule[]>;
 	all(): Promise<Schedule[]>;
@@ -208,6 +228,12 @@ export interface BackgroundTurns {
 		firedAt: Date,
 		finding?: PrecheckFinding,
 	): Promise<ScheduledOutcome>;
+	/**
+	 * Who a due schedule's turn would run as now, checked as the turn is: asked before its
+	 * precheck, which runs only for a creator who may run the turn, at the tier it would run at.
+	 * Throws when the identity service cannot tell.
+	 */
+	runsAs(schedule: Schedule): Promise<BackgroundRunsAs>;
 	/** A delegated task's report, answered in its channel under the same rules as a schedule. */
 	runDelegated(job: DelegationJob, result: DelegationOutcome): Promise<void>;
 	/** The process's own logged error, reported to an agent in its channel as a report turn. */

package/src/core/sessions.ts

@@ -1,5 +1,7 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { PluginError } from "./errors.ts";
+import type { Principal } from "./identity/principal-store.ts";
+import type { OwnerIdentity } from "./identity.ts";
 import type { Speaker } from "./speakers.ts";
 
 /** `<surface>:<channel id>`, for example `discord:1234`. A DM is one channel. */
@@ -41,6 +43,15 @@ export interface TransientTask {
 	onFinished?(toolCalls: readonly string[]): void;
 }
 
+/**
+ * Whom a session's conversation serves, fixed when the session is made: `private` to one
+ * principal, whose name and pronouns are known when the host has a record of them, or `shared`
+ * by whoever its claim admits, as an agent's session always is.
+ */
+export type SessionConversation =
+	| { visibility: "private"; principalId: string; principal?: Principal }
+	| { visibility: "shared" };
+
 /** What one Pi session is for, as a session tool's factory sees it. */
 export interface SessionContext {
 	/** "agent" for an agent's session; otherwise the kind of conversation, which the claim that owns the channel names. */
@@ -53,6 +64,25 @@ export interface SessionContext {
 	agent?: AgentTurnScope;
 	/** Wraps a compactor so the core's compaction tiers decide when it may answer. */
 	compaction: { wrap(compactor: ExtensionFactory): ExtensionFactory };
+	/**
+	 * Whom the conversation serves, as `TurnRequest.conversation` or the host's record says when the
+	 * session is made; shared when neither says. A private conversation's tools serve its person:
+	 * their memory, their notices. A shared one's serve each turn's speaker.
+	 */
+	conversation: SessionConversation;
+	/**
+	 * Whom the session's tool descriptions address, fixed when it is made: a private conversation's
+	 * person by their name and pronouns, the primary owner exactly as 0.8 wrote them, and
+	 * `THE_SPEAKER` in a shared conversation, where each turn's prompt says who speaks.
+	 */
+	addressee: OwnerIdentity;
+	/**
+	 * Whose memory the session's turns may read: `"speaker"` (the default), as `conversation` and
+	 * each turn's speaker decide, or `"none"`, for a persona that declares it; then no memory loads.
+	 * While the running turn is one the agent server keeps out of memory (`AgentSessions.memory`),
+	 * it reads `"none"` for that turn alone.
+	 */
+	memory: "speaker" | "none";
 	/** The person the session's running turn is for; undefined between turns. */
 	speaker(): Speaker | undefined;
 	/** Runs a task beside this session, under its confirmation gate. */

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