pi-roundtable 0.1.0

package/src/core/domain/owner-prompts.ts

@@ -0,0 +1,45 @@
+import type { Tier } from "../speakers.ts";
+/**
+ * The owner answering inside a running turn: a card in the turn's channel that only he may
+ * answer. Unanswered cards expire; a stopped turn cancels its open cards.
+ */
+export type Approval = "approved" | "declined" | "expired" | "cancelled";
+
+export interface AskOption {
+	label: string;
+	description?: string;
+}
+
+export interface OwnerQuestion {
+	question: string;
+	/** Up to 25; none means a free-text answer. */
+	options: readonly AskOption[];
+	/** More than one option may be chosen. */
+	multi: boolean;
+	/** He may write an answer of his own besides the options. */
+	allowOther: boolean;
+}
+
+export interface OwnerAnswer {
+	/** The chosen options' labels, in the order they were offered. */
+	choices: string[];
+	/** What he wrote himself, if anything. */
+	text?: string;
+}
+
+export interface OwnerPrompts {
+	/** Asks him to approve an action; `signal` cancels the card when the turn stops. */
+	confirm(
+		title: string,
+		message: string,
+		signal?: AbortSignal,
+		/** The lowest tier that may approve; the owner only when absent. */
+		minTier?: Tier,
+	): Promise<Approval>;
+	/** Asks him a question; undefined when it expired or was cancelled. */
+	ask(
+		title: string,
+		question: OwnerQuestion,
+		signal?: AbortSignal,
+	): Promise<OwnerAnswer | undefined>;
+}

package/src/core/domain/ports.ts

@@ -0,0 +1,91 @@
+import type { AgentTurnScope, TurnSelection } from "../sessions.ts";
+import type { Speaker } from "../speakers.ts";
+import type { TurnAttachments } from "./attachment.ts";
+import type {
+	ChannelKey,
+	InboundMessage,
+	OutboundReply,
+	PendingConfirmation,
+	TranscriptEntry,
+	TurnResult,
+} from "./conversation.ts";
+
+export interface ChatSurface {
+	start(onMessage: (message: InboundMessage) => void): Promise<void>;
+	sendReply(channel: ChannelKey, reply: OutboundReply): Promise<void>;
+	/** Shows the typing indicator until the returned function is called. */
+	startTyping(channel: ChannelKey): () => void;
+	/**
+	 * Shows the owner a stop button once the turn has run a few seconds, until the returned
+	 * function is called.
+	 */
+	showStop(channel: ChannelKey): () => void;
+	/** Adds or removes the bot's reaction on a message; failures are logged, never thrown. */
+	react(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
+	unreact(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
+}
+
+export type { AgentTurnScope };
+
+export interface TurnRequest {
+	/** Where the turn's message arrived and its attachments are saved. */
+	channel: ChannelKey;
+	/** The turn's tools; the owner's conversations pick a profile's, an agent's are the agent union. */
+	selection: TurnSelection;
+	text: string;
+	/** Files and images the message carries; none when absent. */
+	attachments?: TurnAttachments;
+	/** The owner confirmed the channel's pending actions, so they may run in this turn. */
+	confirmed?: boolean;
+	/** Set for a turn of an agent-server agent. */
+	agent?: AgentTurnScope;
+	/** The person the turn is for: who wrote the message, or who set up the work. */
+	speaker?: Speaker;
+	/** The owner's own chat turn, which his next messages may steer. */
+	steerable?: boolean;
+	/**
+	 * The owner started the turn by writing in its channel, or it delivers a dispatch's report,
+	 * so it may ask him there on cards: approvals of held actions and ask_user questions. A
+	 * schedule's turn is not.
+	 */
+	interactive?: boolean;
+}
+
+export interface AgentRuntime {
+	runTurn(request: TurnRequest): Promise<TurnResult>;
+	/** Held actions of a conversation: a channel, or an agent's session key. */
+	pendingConfirmation(channel: ChannelKey): PendingConfirmation | undefined;
+	recentTranscript(
+		channel: ChannelKey,
+		limit: number,
+	): Promise<TranscriptEntry[]>;
+	/** Archives a conversation (a channel, or an agent's session key) and drops its held actions; call between turns. */
+	startFresh(channel: ChannelKey): Promise<void>;
+	/** Like `startFresh`, but removes the conversation and every archive of it for good; call between turns. */
+	deleteConversation(channel: ChannelKey): Promise<void>;
+	/**
+	 * Adds the message to the conversation's running turn when that turn is steerable and holds
+	 * no actions; false when the message must wait for its own turn.
+	 */
+	steer(
+		channel: ChannelKey,
+		text: string,
+		attachments: TurnAttachments,
+		/** The message's author; a turn another speaker started takes no steering from them. */
+		speakerId?: string,
+	): Promise<boolean>;
+	/** Aborts the conversation's running turn and drops what was steered into it; false when none runs. */
+	stop(channel: ChannelKey): boolean;
+}
+
+/** The judge's question and answer shapes. */
+export type {
+	ChoiceAnswer,
+	ChoiceQuestion,
+	ScoreQuestion,
+	YesNoQuestion,
+} from "../contract/providers.ts";
+
+export interface OwnerNotifier {
+	notifyOwner(text: string): Promise<void>;
+}

package/src/core/domain/profile.ts

@@ -0,0 +1,32 @@
+/** The built-in coordinator profiles; each owner connector adds one more at runtime. */
+export const STATIC_PROFILE_IDS = [
+	"general",
+	"research",
+	"workspace",
+	"discord",
+	"coding",
+] as const;
+
+export type StaticProfileId = (typeof STATIC_PROFILE_IDS)[number];
+
+/** A built-in profile id, or `connector:<name>` for an owner connector. */
+export type ProfileId = string;
+
+export const DEFAULT_PROFILE: StaticProfileId = "general";
+
+/** A coordinator profile: the same persona with a different set of active tools. */
+export interface Profile {
+	id: ProfileId;
+	/** What the judge reads to decide whether a message belongs to this profile. */
+	criterion: string;
+	/** Exact names of the assistant's own and Pi package tools active while this profile handles a turn. */
+	tools: readonly string[];
+	/** MCP gateway virtual servers whose every tool is also active. */
+	mcpServers: readonly string[];
+}
+
+/** The profiles a turn can be routed to right now. */
+export interface ProfileCatalog {
+	list(): Profile[];
+	get(id: ProfileId): Profile | undefined;
+}

package/src/core/drain.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { waitUntilIdle } from "./drain.ts";
+import { ChannelQueue } from "./routing/channel-queue.ts";
+
+describe("waitUntilIdle", () => {
+	test("returns at once when nothing runs", async () => {
+		expect(await waitUntilIdle({ busy: () => [] })).toEqual([]);
+	});
+
+	test("waits for queued work, including work that arrives while waiting", async () => {
+		const queue = new ChannelQueue();
+		const done: string[] = [];
+		let release = () => {};
+		void queue.run("discord:1", async () => {
+			await new Promise<void>((r) => {
+				release = r;
+			});
+			done.push("first");
+		});
+		const waiting = waitUntilIdle({ busy: () => queue.busy(), intervalMs: 5 });
+		await Bun.sleep(20);
+		void queue.run("discord:2", async () => {
+			await Bun.sleep(30);
+			done.push("second");
+		});
+		release();
+		expect(await waiting).toEqual([]);
+		expect(done).toEqual(["first", "second"]);
+		expect(queue.busy()).toEqual([]);
+	});
+
+	test("gives up at the limit and says what is still busy", async () => {
+		let clock = 0;
+		const left = await waitUntilIdle({
+			busy: () => ["discord:1", "discord:1"],
+			limitMs: 3_000,
+			intervalMs: 1_000,
+			now: () => clock,
+			sleep: async (ms) => {
+				clock += ms;
+			},
+		});
+		expect(left).toEqual(["discord:1", "discord:1"]);
+		expect(clock).toBe(3_000);
+	});
+});

package/src/core/drain.ts

@@ -0,0 +1,33 @@
+/** How long a shutdown waits for running work before aborting it (self-maintenance spec behavior 11). */
+export const DRAIN_LIMIT_MS = 60 * 60_000;
+
+export interface DrainOptions {
+	/** What still runs or waits, one entry per piece of work; empty when idle. */
+	busy: () => string[];
+	limitMs?: number;
+	intervalMs?: number;
+	sleep?: (ms: number) => Promise<void>;
+	now?: () => number;
+}
+
+/**
+ * Waits until nothing runs or waits, checking every interval, for at most the limit. Work that
+ * arrives meanwhile is served as usual and waited for too. Returns what was still busy when the
+ * limit ran out, or an empty list once idle.
+ */
+export async function waitUntilIdle(options: DrainOptions): Promise<string[]> {
+	const {
+		busy,
+		limitMs = DRAIN_LIMIT_MS,
+		intervalMs = 1_000,
+		sleep = (ms) => Bun.sleep(ms),
+		now = Date.now,
+	} = options;
+	const deadline = now() + limitMs;
+	for (;;) {
+		const left = busy();
+		if (left.length === 0) return [];
+		if (now() >= deadline) return left;
+		await sleep(intervalMs);
+	}
+}

package/src/core/errors.ts

@@ -0,0 +1,29 @@
+/** A plugin that cannot be registered: it adds nothing, or clashes with another. */
+export class PluginError extends Error {
+	override name = "PluginError";
+}
+
+/** A core port read during setup, before the host has linked every plugin's contributions. */
+export class NotLinkedError extends Error {
+	override name = "NotLinkedError";
+}
+
+/** A plugin's migration failed, so the host stops before any plugin is set up. */
+export class MigrationError extends Error {
+	override name = "MigrationError";
+	readonly migration: string;
+	constructor(migration: string, cause: unknown) {
+		super(`migration ${migration} failed: ${String(cause)}`, { cause });
+		this.migration = migration;
+	}
+}
+
+/** A judge could not answer: its model failed or said something other than the asked JSON. */
+export class JudgeError extends Error {
+	override name = "JudgeError";
+}
+
+/** A provider slot nobody filled, read by a part that needs it. */
+export class ProviderError extends Error {
+	override name = "ProviderError";
+}

package/src/core/events.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { EventBus } from "./events.ts";
+import { silentLogger } from "./log.ts";
+import type { EventHandlers } from "./plugin.ts";
+
+const turn = {
+	agent: "infra",
+	channel: "discord:1" as const,
+	speaker: undefined,
+};
+
+describe("EventBus", () => {
+	test("delivers to every plugin's handler in registration order", async () => {
+		const log: string[] = [];
+		const bus = new EventBus(silentLogger());
+		const handlers = (name: string): EventHandlers => ({
+			turnStarted: (event) => {
+				log.push(`${name} ${event.agent}`);
+			},
+		});
+		bus.link([
+			{ plugin: "a", events: handlers("a") },
+			{ plugin: "b", events: handlers("b") },
+		]);
+		await bus.deliver("turnStarted", turn);
+		expect(log).toEqual(["a infra", "b infra"]);
+	});
+
+	test("a handler that throws is logged with its plugin and never stops the others", async () => {
+		const logged: { plugin: string; event: string }[] = [];
+		const bus = new EventBus({
+			...silentLogger(),
+			error: (fields: unknown) => {
+				logged.push(fields as { plugin: string; event: string });
+			},
+		});
+		const reached: string[] = [];
+		bus.link([
+			{
+				plugin: "bad",
+				events: {
+					changed: () => {
+						throw new Error("boom");
+					},
+				},
+			},
+			{
+				plugin: "good",
+				events: {
+					changed: () => {
+						reached.push("good");
+					},
+				},
+			},
+		]);
+		await bus.deliver("changed");
+		expect(reached).toEqual(["good"]);
+		expect(logged).toMatchObject([{ plugin: "bad", event: "changed" }]);
+	});
+
+	test("reports to the sink before the handlers are linked are dropped", async () => {
+		const log: string[] = [];
+		const bus = new EventBus(silentLogger());
+		bus.sink.changed();
+		bus.link([
+			{
+				plugin: "a",
+				events: {
+					changed: () => {
+						log.push("changed");
+					},
+				},
+			},
+		]);
+		await Bun.sleep(1);
+		expect(log).toEqual([]);
+		bus.sink.changed();
+		await Bun.sleep(1);
+		expect(log).toEqual(["changed"]);
+	});
+});

package/src/core/events.ts

@@ -0,0 +1,55 @@
+import type { Logger } from "./log.ts";
+import type { EventHandlers, EventSink } from "./plugin.ts";
+
+/** One registered plugin's handlers. */
+interface Registered {
+	plugin: string;
+	events: EventHandlers;
+}
+
+/**
+ * Delivers the core's events to the plugins' handlers, in registration order. A handler runs
+ * apart from the code that reported the event, and one that throws is logged with its plugin's
+ * name and never stops the others. Nothing is delivered until the host has linked the handlers.
+ */
+export class EventBus {
+	readonly #logger: Logger;
+	#handlers: readonly Registered[] = [];
+
+	constructor(logger: Logger) {
+		this.#logger = logger;
+	}
+
+	/** Starts delivering to these handlers. */
+	link(handlers: readonly Registered[]): void {
+		this.#handlers = handlers;
+	}
+
+	/** Delivers one event and waits for every handler; used where the caller must not go on before. */
+	async deliver<Name extends keyof EventHandlers>(
+		name: Name,
+		...args: Parameters<NonNullable<EventHandlers[Name]>>
+	): Promise<void> {
+		for (const { plugin, events } of this.#handlers) {
+			const handler = events[name] as
+				| ((...values: unknown[]) => Promise<void> | void)
+				| undefined;
+			if (!handler) continue;
+			try {
+				await handler.apply(events, args);
+			} catch (error) {
+				this.#logger.error(
+					{ plugin, event: name, err: error },
+					"event handler failed",
+				);
+			}
+		}
+	}
+
+	/** What the core reports to; each call returns at once. */
+	readonly sink: EventSink = {
+		turnStarted: (turn) => void this.deliver("turnStarted", turn),
+		turnEnded: (turn) => void this.deliver("turnEnded", turn),
+		changed: () => void this.deliver("changed"),
+	};
+}

package/src/core/holds.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { PluginError } from "./errors.ts";
+import { type HoldRule, holdChain } from "./holds.ts";
+
+/** A rule that holds every call to `tool`, saying `said`. */
+const rule = (name: string, tool: string, said: string): HoldRule => ({
+	name,
+	describe: (called) => (called === tool ? said : undefined),
+});
+
+describe("holdChain", () => {
+	test("lets a call run when no rule holds it", () => {
+		const holds = holdChain([rule("a", "x", "do x")]);
+		expect(holds("y", {}, {})).toBeUndefined();
+		expect(holdChain([])("x", {}, {})).toBeUndefined();
+	});
+
+	test("the first rule that describes a call holds it", () => {
+		const holds = holdChain([
+			rule("first", "x", "first says x"),
+			rule("second", "x", "second says x"),
+			rule("third", "y", "third says y"),
+		]);
+		expect(holds("x", {}, {})).toBe("first says x");
+		expect(holds("y", {}, {})).toBe("third says y");
+	});
+
+	test("hands each rule the call's input and the session's workspace", () => {
+		const seen: unknown[] = [];
+		const holds = holdChain([
+			{
+				name: "spy",
+				describe: (tool, input, context) => {
+					seen.push({ tool, input, context });
+					return undefined;
+				},
+			},
+		]);
+		holds("bash", { command: "ls" }, { workspace: "/work" });
+		expect(seen).toEqual([
+			{
+				tool: "bash",
+				input: { command: "ls" },
+				context: { workspace: "/work" },
+			},
+		]);
+	});
+
+	test("refuses two rules with one name", () => {
+		expect(() =>
+			holdChain([rule("same", "x", "a"), rule("same", "y", "b")]),
+		).toThrow(PluginError);
+	});
+});

package/src/core/holds.ts

@@ -0,0 +1,46 @@
+import { PluginError } from "./errors.ts";
+
+/** What a hold rule knows about the session making the call. */
+export interface HoldContext {
+	/** The shared workspace of a session with a shell; calls reaching outside it may be held. */
+	workspace?: string;
+}
+
+/**
+ * Decides whether a tool call waits for the owner's approval. A rule answers with a short
+ * description of what the call would do, or undefined when it has no opinion on the call.
+ */
+export interface HoldRule {
+	name: string;
+	describe(
+		tool: string,
+		input: Record<string, unknown>,
+		context: HoldContext,
+	): string | undefined;
+}
+
+/** The description of a call that must be approved first, or undefined to let it run. */
+export type HoldCheck = (
+	tool: string,
+	input: Record<string, unknown>,
+	context: HoldContext,
+) => string | undefined;
+
+/** Asks the rules in order; the first description holds the call. */
+export function holdChain(rules: readonly HoldRule[]): HoldCheck {
+	const names = new Set<string>();
+	for (const rule of rules) {
+		if (names.has(rule.name))
+			throw new PluginError(
+				`hold rule ${rule.name} is registered twice. Rename one of the two.`,
+			);
+		names.add(rule.name);
+	}
+	return (tool, input, context) => {
+		for (const rule of rules) {
+			const description = rule.describe(tool, input, context);
+			if (description !== undefined) return description;
+		}
+		return undefined;
+	};
+}