pi-roundtable 0.1.0

package/src/core/define.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "bun:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { definePlugin, defineTool, ToolRefusal } from "./define.ts";
+import { PluginError } from "./errors.ts";
+import type { SessionContext } from "./sessions.ts";
+import type { Speaker } from "./speakers.ts";
+
+const speaker: Speaker = { id: "1", name: "Ann", tier: "admin" };
+
+const note = {
+	name: "note_add",
+	description: "Save a note.",
+	parameters: Type.Object({ text: Type.String() }),
+	minTier: "member" as const,
+	run: (args: { text: string }) => `saved ${args.text}`,
+};
+
+type Registered = {
+	name: string;
+	execute(
+		id: string,
+		params: unknown,
+		signal?: AbortSignal,
+	): Promise<{ content: { text: string }[]; isError?: boolean }>;
+};
+
+/** Registers the tool in a fake Pi session the way the runtime does, and returns what it registered. */
+function register(tool: ReturnType<typeof defineTool>): Registered {
+	const registered: Registered[] = [];
+	const context = {
+		speaker: () => speaker,
+		turnChannel: "discord:2",
+		agent: { name: "helper", session: "discord:2", home: "discord:2" },
+	} as unknown as SessionContext;
+	const factory = tool.session.snapshot().factory(context);
+	factory?.({
+		registerTool: (def: Registered) => registered.push(def),
+	} as unknown as ExtensionAPI);
+	const [one] = registered;
+	if (!one) throw new Error("nothing was registered");
+	return one;
+}
+
+describe("defineTool", () => {
+	test("registers the tool in a session and runs it with the turn's speaker", async () => {
+		let seen: unknown;
+		const tool = defineTool({
+			...note,
+			run: (args, turn) => {
+				seen = { args, speaker: turn.speaker, channel: turn.channel };
+				return "ok";
+			},
+		});
+		const result = await register(tool).execute("call", { text: "milk" });
+		expect(result.content[0]?.text).toBe("ok");
+		expect(seen).toEqual({
+			args: { text: "milk" },
+			speaker,
+			channel: "discord:2",
+		});
+		expect(tool.session.snapshot().requiredTools).toEqual(["note_add"]);
+		expect(tool.minTier).toBe("member");
+		expect(tool.agent).toBe(true);
+	});
+
+	test("a ToolRefusal becomes an error result the model reads; any other error fails the call", async () => {
+		const refuse = defineTool({
+			...note,
+			run: () => {
+				throw new ToolRefusal("no empty notes");
+			},
+		});
+		const refused = await register(refuse).execute("c", { text: "" });
+		expect(refused.isError).toBe(true);
+		expect(refused.content[0]?.text).toBe("no empty notes");
+		const fail = defineTool({
+			...note,
+			run: () => {
+				throw new Error("disk gone");
+			},
+		});
+		await expect(register(fail).execute("c", { text: "x" })).rejects.toThrow(
+			"disk gone",
+		);
+	});
+
+	test("its hold rule describes the tool's own calls and no other", () => {
+		const tool = defineTool({
+			...note,
+			hold: (args) => (args.text === "rm" ? "delete everything" : undefined),
+		});
+		const rule = tool.hold;
+		expect(rule?.name).toBe("tool:note_add");
+		expect(rule?.describe("note_add", { text: "rm" }, {})).toBe(
+			"delete everything",
+		);
+		expect(rule?.describe("note_add", { text: "hi" }, {})).toBeUndefined();
+		expect(rule?.describe("other", { text: "rm" }, {})).toBeUndefined();
+	});
+
+	test("each mistake is refused with the tool's name and the fix", () => {
+		const refused = (change: Record<string, unknown>) => () =>
+			defineTool({ ...note, ...change } as typeof note);
+		expect(refused({ name: "NoteAdd" })).toThrow(PluginError);
+		expect(refused({ name: "NoteAdd" })).toThrow(
+			'tool "NoteAdd": the name must be lowercase words joined by underscores, such as note_add. Rename the tool.',
+		);
+		expect(refused({ name: "bash" })).toThrow(
+			"tool bash: the agents already have a tool of this name. Rename the tool.",
+		);
+		expect(refused({ minTier: undefined })).toThrow(
+			"tool note_add: minTier must be one of member, admin, owner; got undefined. Set the lowest tier that may use it.",
+		);
+		expect(refused({ description: " " })).toThrow(
+			"tool note_add: the description is empty. Tell the model when to call the tool.",
+		);
+		expect(refused({ run: undefined })).toThrow(
+			"tool note_add: run is missing. Give the function the tool runs.",
+		);
+	});
+});
+
+describe("definePlugin", () => {
+	const setup = () => ({});
+
+	test("returns the plugin it was given", () => {
+		const plugin = { name: "my-notes", setup };
+		expect(definePlugin(plugin)).toBe(plugin);
+	});
+
+	test("refuses a name that is not lowercase words joined by dashes, and a missing setup", () => {
+		expect(() => definePlugin({ name: "My Notes", setup })).toThrow(
+			'plugin "My Notes": the name must be lowercase words joined by dashes, such as my-notes. Rename the plugin.',
+		);
+		expect(() =>
+			definePlugin({ name: "notes" } as unknown as Parameters<
+				typeof definePlugin
+			>[0]),
+		).toThrow(
+			"plugin notes: setup is missing. Give the function that returns what the plugin adds.",
+		);
+	});
+});

package/src/core/define.ts

@@ -0,0 +1,154 @@
+import type { Static, TObject } from "typebox";
+import { PluginError } from "./errors.ts";
+import type { HoldRule } from "./holds.ts";
+import type { RoundtablePlugin } from "./plugin.ts";
+import type { AgentTurnScope, ChannelKey, SessionTool } from "./sessions.ts";
+import { toolError, toolText } from "./shared/tool-result.ts";
+import { type Speaker, TIERS, type Tier } from "./speakers.ts";
+
+/** Tool names are lowercase words joined by underscores, like every tool the core ships. */
+const TOOL_NAME = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+/** Plugin names are lowercase words joined by dashes. */
+const PLUGIN_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** Tools the agents and the shell already have; a plugin's tool may not take their names. */
+const RESERVED_TOOLS = ["bash", "read", "edit", "write"];
+
+/** What a tool knows about the turn that calls it. */
+export interface ToolTurn {
+	/** Who the turn is for; undefined for a turn nobody spoke in. */
+	speaker: Speaker | undefined;
+	/** The channel the turn runs in. */
+	channel: ChannelKey;
+	/** The agent whose turn it is. */
+	agent: AgentTurnScope | undefined;
+	signal: AbortSignal | undefined;
+}
+
+/**
+ * Thrown by a tool's `run` for a call the model should correct: the message becomes the tool's
+ * error result, which the model reads. Any other error fails the call.
+ */
+export class ToolRefusal extends Error {
+	override name = "ToolRefusal";
+}
+
+export interface ToolSpec<Schema extends TObject> {
+	/** Lowercase words joined by underscores; unique across every plugin. */
+	name: string;
+	/** What the model reads to decide when to call the tool. */
+	description: string;
+	/** The arguments, as a Typebox object; `run` receives them typed. */
+	parameters: Schema;
+	/** The lowest tier of speaker whose turns may call the tool; the operator's settings may change it. */
+	minTier: Tier;
+	/** Whether agents carry the tool in their turns; default true. */
+	agent?: boolean;
+	/** A short description of what the call would do when it must wait for approval; undefined lets it run. */
+	hold?: (args: Static<Schema>) => string | undefined;
+	run(args: Static<Schema>, turn: ToolTurn): Promise<string> | string;
+}
+
+/** A tool a plugin adds, as `defineTool` builds it. */
+export interface ToolContribution {
+	readonly name: string;
+	readonly minTier: Tier;
+	readonly agent: boolean;
+	/** The extension that registers the tool in a session. */
+	readonly session: SessionTool;
+	/** The hold rule for the tool's `hold`, when it has one. */
+	readonly hold?: HoldRule;
+}
+
+/**
+ * Defines one tool: its name, what the model reads about it, its arguments, the tier that may
+ * use it, and what it does. A missing or unknown tier, or a name that is not a tool name, is
+ * refused here with the tool's name, before anything starts.
+ */
+export function defineTool<Schema extends TObject>(
+	spec: ToolSpec<Schema>,
+): ToolContribution {
+	const { name } = spec;
+	if (typeof name !== "string" || !TOOL_NAME.test(name))
+		throw new PluginError(
+			`tool ${JSON.stringify(name)}: the name must be lowercase words joined by underscores, such as note_add. Rename the tool.`,
+		);
+	if (RESERVED_TOOLS.includes(name))
+		throw new PluginError(
+			`tool ${name}: the agents already have a tool of this name. Rename the tool.`,
+		);
+	if (!TIERS.includes(spec.minTier))
+		throw new PluginError(
+			`tool ${name}: minTier must be one of ${TIERS.join(", ")}; got ${JSON.stringify(spec.minTier)}. Set the lowest tier that may use it.`,
+		);
+	if (typeof spec.description !== "string" || !spec.description.trim())
+		throw new PluginError(
+			`tool ${name}: the description is empty. Tell the model when to call the tool.`,
+		);
+	if (typeof spec.run !== "function")
+		throw new PluginError(
+			`tool ${name}: run is missing. Give the function the tool runs.`,
+		);
+	const session: SessionTool = {
+		name: `tool:${name}`,
+		phase: "tools",
+		snapshot: () => ({
+			revision: 0,
+			requiredTools: [name],
+			factory: (context) => (pi) => {
+				pi.registerTool({
+					name,
+					label: name,
+					description: spec.description,
+					parameters: spec.parameters,
+					execute: async (_toolCallId, params, signal) => {
+						try {
+							return toolText(
+								await spec.run(params as Static<Schema>, {
+									speaker: context.speaker(),
+									channel: context.turnChannel,
+									agent: context.agent,
+									signal,
+								}),
+							);
+						} catch (error) {
+							if (error instanceof ToolRefusal) return toolError(error.message);
+							throw error;
+						}
+					},
+				});
+			},
+		}),
+	};
+	const hold = spec.hold;
+	return {
+		name,
+		minTier: spec.minTier,
+		agent: spec.agent ?? true,
+		session,
+		...(hold
+			? {
+					hold: {
+						name: `tool:${name}`,
+						describe: (tool, input) =>
+							tool === name ? hold(input as Static<Schema>) : undefined,
+					},
+				}
+			: {}),
+	};
+}
+
+/**
+ * Defines a plugin. It returns the plugin it was given, typed, after checking its name, so a
+ * mistake shows where the plugin is written.
+ */
+export function definePlugin(plugin: RoundtablePlugin): RoundtablePlugin {
+	if (typeof plugin.name !== "string" || !PLUGIN_NAME.test(plugin.name))
+		throw new PluginError(
+			`plugin ${JSON.stringify(plugin.name)}: the name must be lowercase words joined by dashes, such as my-notes. Rename the plugin.`,
+		);
+	if (typeof plugin.setup !== "function")
+		throw new PluginError(
+			`plugin ${plugin.name}: setup is missing. Give the function that returns what the plugin adds.`,
+		);
+	return plugin;
+}

package/src/core/discord/agent-commands.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { messages } from "../i18n/index.ts";
+import { formModels, skillsText } from "./agent-commands.ts";
+
+describe("formModels", () => {
+	const usable = [
+		"claude-bridge/claude-opus-5-5",
+		"claude-bridge/claude-haiku-4-5",
+		"claude-bridge/claude-sonnet-5-5",
+		"openai-codex/gpt-6-luna",
+		"openai-codex/gpt-6-sol",
+		"openai-codex/gpt-6-astra",
+	];
+
+	test("offers the five form models in order, leaving out other usable ones", () => {
+		expect(formModels(usable)).toEqual([
+			"openai-codex/gpt-6-astra",
+			"openai-codex/gpt-6-sol",
+			"openai-codex/gpt-6-luna",
+			"claude-bridge/claude-sonnet-5-5",
+			"claude-bridge/claude-opus-5-5",
+		]);
+	});
+
+	test("leaves out form models the host cannot run", () => {
+		expect(
+			formModels(["claude-bridge/claude-opus-5-5", "openai-codex/gpt-6-sol"]),
+		).toEqual(["openai-codex/gpt-6-sol", "claude-bridge/claude-opus-5-5"]);
+	});
+
+	test("puts the agent's current model first when the form does not offer it", () => {
+		expect(formModels(usable, "claude-bridge/claude-haiku-4-5")[0]).toBe(
+			"claude-bridge/claude-haiku-4-5",
+		);
+		expect(formModels(usable, "openai-codex/gpt-6-sol")).toEqual(
+			formModels(usable),
+		);
+	});
+});
+
+describe("skillsText", () => {
+	test("lists carried skills with the built-in one marked, and missing ones with their reason", () => {
+		const skill = (name: string) => ({
+			name,
+			description: "Use when x.",
+			file: `/s/${name}/SKILL.md`,
+		});
+		const text = messages();
+		expect(
+			skillsText({
+				skills: [skill("writing-skills"), skill("example-skill")],
+				missing: [{ name: "gone", reason: "file not found" }],
+			}),
+		).toBe(
+			`${text.agentSkills([text.agentSkillBuiltin("writing-skills"), "`example-skill`"])}\n${text.agentSkillMissing("gone", "file not found")}`,
+		);
+	});
+});