pi-roundtable 0.1.0

package/src/core/tool-tiers.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import { ConfigError } from "./domain/errors.ts";
+import {
+	CORE_TOOL_TIERS,
+	parseToolTiers,
+	toolsForTier,
+	toolTiers,
+} from "./tool-tiers.ts";
+
+describe("default tiers", () => {
+	const tiers = toolTiers();
+
+	test("members may look, read, and message agents", () => {
+		for (const tool of [
+			"agent_list",
+			"agent_get",
+			"message_agent",
+			"channel_read",
+			"ask_user",
+			"web_search",
+		])
+			expect(tiers.minTier(tool)).toBe("member");
+	});
+
+	test("every speaker may keep a memory of their own", () => {
+		for (const tool of ["memory_add", "memory_search", "memory_remove"])
+			expect(tiers.minTier(tool)).toBe("member");
+	});
+
+	test("creating, editing, archiving, and arranging agents and groups need an admin", () => {
+		for (const tool of [
+			"agent_create",
+			"agent_update",
+			"agent_avatar",
+			"group_create",
+			"group_update",
+			"archive",
+			"channel_arrange",
+			"agent_skills",
+			"schedule_create",
+			"delegate_task",
+		])
+			expect(tiers.minTier(tool)).toBe("admin");
+	});
+
+	test("the shell, notifying the owner, Discord administration, and any tool nobody named stay with the owner", () => {
+		for (const tool of [
+			"bash",
+			"write",
+			"notify_owner",
+			"discord_ban",
+			"some_plugin_tool",
+		])
+			expect(tiers.minTier(tool)).toBe("owner");
+	});
+
+	test("every tool an agent carries from the core is named on purpose", () => {
+		expect(Object.keys(CORE_TOOL_TIERS)).toEqual(
+			expect.arrayContaining(["agent_create", "skill_create", "schedule_list"]),
+		);
+	});
+});
+
+describe("toolsForTier", () => {
+	const tiers = toolTiers();
+	const all = ["agent_list", "agent_create", "bash", "some_plugin_tool"];
+
+	test("each tier gets the tools at or below it, in order", () => {
+		expect(toolsForTier(all, "member", tiers)).toEqual(["agent_list"]);
+		expect(toolsForTier(all, "admin", tiers)).toEqual([
+			"agent_list",
+			"agent_create",
+		]);
+		expect(toolsForTier(all, "owner", tiers)).toEqual(all);
+	});
+
+	test("an operator's map lowers or raises a tool", () => {
+		const custom = toolTiers({ bash: "admin", agent_list: "owner" });
+		expect(toolsForTier(all, "member", custom)).toEqual([]);
+		expect(toolsForTier(all, "admin", custom)).toEqual([
+			"agent_create",
+			"bash",
+		]);
+	});
+
+	test("a plugin's declared tier is read at use time; the operator's still wins", () => {
+		const table = toolTiers({ plugin_b: "owner" });
+		expect(table.minTier("plugin_a")).toBe("owner");
+		table.declare("a", { plugin_a: "member" });
+		table.declare("b", { plugin_b: "member" });
+		expect(table.minTier("plugin_a")).toBe("member");
+		expect(table.minTier("plugin_b")).toBe("owner");
+	});
+
+	test("a tool two plugins declare names both plugins and the fix", () => {
+		const table = toolTiers();
+		table.declare("a", { shared_tool: "member" });
+		expect(() => table.declare("b", { shared_tool: "member" })).toThrow(
+			"plugin b: tool shared_tool is already defined by plugin a. Rename one of the two tools.",
+		);
+	});
+});
+
+describe("parseToolTiers", () => {
+	test("reads tool=tier pairs", () => {
+		expect(parseToolTiers("bash=admin, web_search=member", "X")).toEqual({
+			bash: "admin",
+			web_search: "member",
+		});
+		expect(parseToolTiers(undefined, "X")).toEqual({});
+	});
+
+	test("refuses a pair that is not a tier", () => {
+		expect(() => parseToolTiers("bash=root", "X")).toThrow(ConfigError);
+		expect(() => parseToolTiers("bash", "X")).toThrow(ConfigError);
+	});
+});

package/src/core/tool-tiers.ts

@@ -0,0 +1,127 @@
+import { AGENT_TOOLS } from "./agents/agent-tools.ts";
+import { ConfigError } from "./domain/errors.ts";
+import { PluginError } from "./errors.ts";
+import { SKILL_LIST_TOOL, SKILL_TOOLS } from "./modules/skills/skill-tools.ts";
+import { ASK_USER_TOOL } from "./runtime/extensions/ask-user.ts";
+import { COMPACT_TOOL } from "./runtime/extensions/self-compact-guard.ts";
+import { DELEGATE_TOOL } from "./shared/delegate-tool.ts";
+import { SCHEDULE_TOOLS } from "./shared/schedule-tools.ts";
+import { TIERS, type Tier, tierAtLeast } from "./speakers.ts";
+
+/** The lowest tier that may use each tool; a tool that is not named needs the owner. */
+export interface ToolTiers {
+	minTier(tool: string): Tier;
+	/** Whether a speaker of `tier` may use the tool. */
+	allows(tier: Tier, tool: string): boolean;
+}
+
+const set = (tier: Tier, tools: readonly string[]) =>
+	Object.fromEntries(tools.map((tool) => [tool, tier]));
+
+/**
+ * The core's default tiers. Members talk, read, look things up, and message agents; admins
+ * also create and edit agents, groups, skills, schedules, and delegated work; everything else,
+ * such as the shell, the owner's notes, Discord administration, and every plugin's tools,
+ * stays with the owner until an operator lowers it.
+ */
+export const CORE_TOOL_TIERS: Readonly<Record<string, Tier>> = {
+	...set("admin", [
+		...AGENT_TOOLS,
+		...SKILL_TOOLS,
+		...SCHEDULE_TOOLS,
+		DELEGATE_TOOL,
+	]),
+	...set("member", [
+		"agent_list",
+		"agent_get",
+		"message_agent",
+		"channel_read",
+		"schedule_list",
+		SKILL_LIST_TOOL,
+		"read_attachment",
+		// Each speaker keeps their own; the owner's reaches only the owner's turns.
+		"memory_add",
+		"memory_search",
+		"memory_remove",
+		"web_search",
+		"fetch_content",
+		"get_search_content",
+	]),
+	// The core's own tools serve any turn that can ask or compact.
+	...set("member", [ASK_USER_TOOL, COMPACT_TOOL]),
+};
+
+/**
+ * What each tool needs: the operator's setting first, then the tier its plugin declared, then
+ * the core's default, and the owner for a tool nobody named. Plugins declare theirs when the
+ * host links them, so a reader asks at use time and sees the final table.
+ */
+export class ToolTierTable implements ToolTiers {
+	readonly #operator: ReadonlyMap<string, Tier>;
+	readonly #declared = new Map<string, { plugin: string; tier: Tier }>();
+	readonly #core = new Map(Object.entries(CORE_TOOL_TIERS));
+
+	constructor(operator: Readonly<Record<string, Tier>> = {}) {
+		this.#operator = new Map(Object.entries(operator));
+	}
+
+	/** Records the tiers a plugin's tools need; a tool two plugins declare is a PluginError. */
+	declare(plugin: string, tiers: Readonly<Record<string, Tier>>): void {
+		for (const [tool, tier] of Object.entries(tiers)) {
+			const other = this.#declared.get(tool);
+			if (other)
+				throw new PluginError(
+					`plugin ${plugin}: tool ${tool} is already defined by plugin ${other.plugin}. Rename one of the two tools.`,
+				);
+			this.#declared.set(tool, { plugin, tier });
+		}
+	}
+
+	minTier(tool: string): Tier {
+		return (
+			this.#operator.get(tool) ??
+			this.#declared.get(tool)?.tier ??
+			this.#core.get(tool) ??
+			"owner"
+		);
+	}
+
+	allows(tier: Tier, tool: string): boolean {
+		return tierAtLeast(tier, this.minTier(tool));
+	}
+}
+
+/** The core's tiers with the operator's on top; plugins add theirs through `declare`. */
+export function toolTiers(
+	operator: Readonly<Record<string, Tier>> = {},
+): ToolTierTable {
+	return new ToolTierTable(operator);
+}
+
+/** The tools a tier may use, in order; a turn nobody spoke in has the owner's tier. */
+export function toolsForTier(
+	tools: readonly string[],
+	tier: Tier,
+	tiers: ToolTiers,
+): string[] {
+	return tools.filter((tool) => tiers.allows(tier, tool));
+}
+
+/** Reads `tool=tier` pairs, comma-separated; unset means no changes. */
+export function parseToolTiers(
+	text: string | undefined,
+	name: string,
+): Record<string, Tier> {
+	const result: Record<string, Tier> = {};
+	for (const item of (text ?? "").split(",")) {
+		const pair = item.trim();
+		if (pair === "") continue;
+		const [tool, tier] = pair.split("=").map((part) => part.trim());
+		if (!tool || !tier || !(TIERS as readonly string[]).includes(tier))
+			throw new ConfigError(
+				`${name} must list tool=owner|admin|member pairs, got ${pair}`,
+			);
+		result[tool] = tier as Tier;
+	}
+	return result;
+}

package/src/entries.test.ts

@@ -0,0 +1,112 @@
+import { expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import * as main from "./index.ts";
+import * as testing from "./testing.ts";
+
+// Types disappear at runtime. Update this list AND the changelog for every entry change.
+export const MAIN_EXPORTS = [
+	"NotLinkedError",
+	"PluginError",
+	"Roundtable",
+	"ToolRefusal",
+	"definePlugin",
+	"defineRoundtable",
+	"defineTool",
+];
+export const MAIN_TYPE_EXPORTS = [
+	"AgentSeed",
+	"ChannelClaim",
+	"Contribution",
+	"DefinedRoundtable",
+	"EventHandlers",
+	"HoldRule",
+	"InteractionContribution",
+	"Migration",
+	"PluginContext",
+	"PromptSection",
+	"PromptTurn",
+	"RoundtableConfig",
+	"RoundtableOptions",
+	"RoundtablePlugin",
+	"Service",
+	"SessionTool",
+	"Speaker",
+	"Tier",
+	"ToolContribution",
+	"ToolSpec",
+	"ToolTurn",
+	"TurnEndEvent",
+	"TurnEvent",
+];
+export const TESTING_EXPORTS = ["testPlugin"];
+export const TESTING_TYPE_EXPORTS = [
+	"RecordedEvent",
+	"TestPluginOptions",
+	"TestPluginResult",
+];
+
+/** Source-level names include type-only exports, which Object.keys cannot observe. */
+function entryNames(path: string): string[] {
+	const source = readFileSync(path, "utf8");
+	if (path.endsWith("index.ts"))
+		return [...source.matchAll(/export(?: type)?\s*\{([^}]+)\}/gs)]
+			.flatMap((match) =>
+				(match[1] ?? "")
+					.split(",")
+					.map((name) => name.trim())
+					.filter(Boolean),
+			)
+			.sort();
+	return [
+		...source.matchAll(
+			/export (?:async )?(?:interface|function|type|class|const) (\w+)/g,
+		),
+	]
+		.map((match) => match[1] ?? "")
+		.sort();
+}
+
+test("the public entries have exactly the snapshotted runtime exports", () => {
+	expect(Object.keys(main).sort()).toEqual(MAIN_EXPORTS);
+	expect(Object.keys(testing).sort()).toEqual(TESTING_EXPORTS);
+});
+
+test("type-only names are snapshotted and every public name is in the changelog", () => {
+	expect(entryNames(resolve(import.meta.dir, "index.ts"))).toEqual(
+		[...MAIN_EXPORTS, ...MAIN_TYPE_EXPORTS].sort(),
+	);
+	expect(entryNames(resolve(import.meta.dir, "testing.ts"))).toEqual(
+		[...TESTING_EXPORTS, ...TESTING_TYPE_EXPORTS].sort(),
+	);
+	const local = resolve(import.meta.dir, "../packaging/CHANGELOG.md");
+	const changelog = readFileSync(
+		existsSync(local) ? local : resolve(import.meta.dir, "../CHANGELOG.md"),
+		"utf8",
+	);
+	for (const name of [
+		...MAIN_EXPORTS,
+		...MAIN_TYPE_EXPORTS,
+		...TESTING_EXPORTS,
+		...TESTING_TYPE_EXPORTS,
+	])
+		expect(changelog).toContain(`\`${name}\``);
+});
+
+test("the package export map names exactly the existing entries", () => {
+	const template = resolve(import.meta.dir, "../packaging/package.json.tmpl");
+	const packageFile = existsSync(template)
+		? template
+		: resolve(import.meta.dir, "../package.json");
+	const manifest = JSON.parse(readFileSync(packageFile, "utf8")) as {
+		exports: Record<string, string>;
+	};
+	expect(manifest.exports).toEqual({
+		".": "./src/index.ts",
+		"./testing": "./src/testing.ts",
+	});
+	for (const target of Object.values(manifest.exports))
+		expect(
+			Bun.file(resolve(import.meta.dir, "..", target)).size,
+		).toBeGreaterThan(0);
+});

package/src/index.ts

@@ -0,0 +1,28 @@
+// The plugin author's stable entry; internals remain behind package exports.
+
+export type { AgentSeed } from "./core/agents/agent-store.ts";
+export type { RoundtableConfig } from "./core/config/config.ts";
+export type { ChannelClaim } from "./core/contract/channels.ts";
+export type { InteractionContribution } from "./core/contract/discord.ts";
+export type { Migration } from "./core/db/migrations.ts";
+export type { ToolContribution, ToolSpec, ToolTurn } from "./core/define.ts";
+export { definePlugin, defineTool, ToolRefusal } from "./core/define.ts";
+export type { DefinedRoundtable } from "./core/define-roundtable.ts";
+export { defineRoundtable } from "./core/define-roundtable.ts";
+export { NotLinkedError, PluginError } from "./core/errors.ts";
+export type { HoldRule } from "./core/holds.ts";
+export type { RoundtableOptions } from "./core/host.ts";
+export { Roundtable } from "./core/host.ts";
+export type {
+	Contribution,
+	EventHandlers,
+	PluginContext,
+	PromptSection,
+	PromptTurn,
+	RoundtablePlugin,
+	Service,
+	TurnEndEvent,
+	TurnEvent,
+} from "./core/plugin.ts";
+export type { SessionTool } from "./core/sessions.ts";
+export type { Speaker, Tier } from "./core/speakers.ts";

package/src/testing.test.ts

@@ -0,0 +1,156 @@
+import { expect, test } from "bun:test";
+import { Type } from "typebox";
+import { definePlugin, defineTool, ToolRefusal } from "./index.ts";
+import { testPlugin } from "./testing.ts";
+
+const note = defineTool({
+	name: "note_add",
+	description: "Write a note",
+	parameters: Type.Object({ text: Type.String() }),
+	minTier: "member",
+	hold: (args) => (args.text === "danger" ? "Confirm note" : undefined),
+	run: (args, turn) => {
+		if (!args.text) throw new ToolRefusal("empty note");
+		return `${turn.speaker?.name ?? "anonymous"}: ${args.text}`;
+	},
+});
+
+test("the harness registers tools through their session factories and records tiers and holds", async () => {
+	const harness = await testPlugin(
+		definePlugin({ name: "notes", setup: () => ({ tools: [note] }) }),
+	);
+	expect(harness.tools).toEqual(["note_add"]);
+	expect(harness.tiers.minTier("note_add")).toBe("member");
+	expect(
+		harness.contribution.holdRules?.[0]?.describe(
+			"note_add",
+			{ text: "danger" },
+			{},
+		),
+	).toBe("Confirm note");
+	expect(
+		await harness.runTool(
+			"note_add",
+			{ text: "hello" },
+			{ speaker: { id: "1", name: "Alice", tier: "owner" } },
+		),
+	).toBe("Alice: hello");
+	expect(await harness.runTool("note_add", { text: "" })).toBe("empty note");
+	await harness.stop();
+});
+
+test("ordinary tool errors reject the call rather than becoming model-visible refusals", async () => {
+	const broken = defineTool({
+		name: "broken_tool",
+		description: "Fail",
+		parameters: Type.Object({}),
+		minTier: "owner",
+		run: () => {
+			throw new Error("disk unavailable");
+		},
+	});
+	const harness = await testPlugin(
+		definePlugin({ name: "broken", setup: () => ({ tools: [broken] }) }),
+	);
+	await expect(harness.runTool("broken_tool", {})).rejects.toThrow(
+		"disk unavailable",
+	);
+	await harness.stop();
+});
+
+test("database and built-in services fail with the host's errors until provided", async () => {
+	let databaseError = "";
+	let coreError = "";
+	const harness = await testPlugin(
+		definePlugin({
+			name: "ports",
+			setup: (context) => {
+				try {
+					context.database();
+				} catch (error) {
+					databaseError = String(error);
+				}
+				try {
+					context.core.stores;
+				} catch (error) {
+					coreError = String(error);
+				}
+				return { events: {} };
+			},
+		}),
+	);
+	expect(databaseError).toBe("PluginError: no database is configured");
+	expect(coreError).toContain("core service stores is not provided yet");
+	await harness.stop();
+});
+
+test("events reach the plugin and are recorded", async () => {
+	const received: string[] = [];
+	const harness = await testPlugin(
+		definePlugin({
+			name: "listener",
+			setup: (context) => {
+				context.events.turnStarted({
+					agent: "helper",
+					channel: "test:1",
+					speaker: undefined,
+				});
+				return {
+					events: {
+						shutdown: () => {
+							received.push("shutdown");
+						},
+					},
+				};
+			},
+		}),
+	);
+	expect(harness.events).toEqual([
+		{
+			name: "turnStarted",
+			turn: { agent: "helper", channel: "test:1", speaker: undefined },
+		},
+	]);
+	await harness.stop();
+	expect(received).toEqual(["shutdown"]);
+});
+
+test("a plugin that adds nothing gets the host's exact refusal", async () => {
+	await expect(
+		testPlugin(definePlugin({ name: "empty", setup: () => ({}) })),
+	).rejects.toThrow(
+		"plugin empty adds nothing. Give it a part (tools, services, channels, and so on), a migration, or a provider, or remove it.",
+	);
+});
+
+test("sessions read during setup carry the host's NotLinkedError text", async () => {
+	await expect(
+		testPlugin(
+			definePlugin({
+				name: "early",
+				setup: (context) => {
+					context.sessions();
+					return { events: {} };
+				},
+			}),
+		),
+	).rejects.toThrow(
+		"session parts are linked once every plugin is set up. Call sessions() from a service's start or from a handler, not during setup.",
+	);
+});
+
+test("the harness returns the agent selection a plugin contributes", async () => {
+	const harness = await testPlugin(
+		definePlugin({
+			name: "selecting",
+			setup: () => ({
+				agentSelection: () => ({ tools: ["note_add"], groups: [] }),
+			}),
+		}),
+	);
+	expect(harness.contribution.agentSelection?.()).toEqual({
+		tools: ["note_add"],
+		groups: [],
+	});
+	await harness.stop();
+});