pi-roundtable 0.5.2 → 0.6.1

package/CHANGELOG.md

@@ -5,6 +5,22 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-10-02
+
+### Fixed
+
+- `add plugin` and `add package` kept a one-line `plugins` list on one line however long it grew, so a project's `biome check` failed once the line passed 80 columns. A list that would pass 80 columns is now put one element a line, as the formatter writes it; a list already over several lines keeps its layout, and one holding a comment stays as it was.
+
+## [0.6.0] - 2026-10-02
+
+### Added
+
+- `roundtable add package <spec>` installs a Pi package with `bun add`, loads its extensions to find the tools they register, and writes `plugins/<name>.ts` and its test: the plugin lists the package in `piPackages`, selects its tools for every agent turn with `agentSelection`, and requires them with `requiredTools`. It gives no tool a tier, so a tool no other plugin tiers stays the owner's until the operator's `toolTiers` lowers it. It refuses before installing when the plugin file exists or the config cannot take the plugin, and after installing when the package declares no Pi extensions or they fail to load, naming the `bun remove` command.
+
+### Changed
+
+- The `piPackages` guide and its example now say that loading a package only registers its tools: a turn uses the tools it selects, so a plugin also lists them in `agentSelection`. The example used to list `piPackages` alone, which loaded `pi-web-access` without any turn being able to call its tools.
+
 ## [0.5.2] - 2026-10-02
 
 ### Changed

package/README.md

@@ -82,6 +82,7 @@ On `SIGTERM` or `SIGINT` it finishes running work before it stops.
 ## A plugin
 
 `roundtable add plugin <name>` creates `plugins/<name>.ts` and its test and lists it in `roundtable.config.ts`.
+`roundtable add package <spec>` does the same for a Pi package from npm: it installs the package and writes a plugin that loads its extensions and selects its tools.
 A plugin is an object with a name and a `setup` function that returns what it adds; this one gives every agent a tool:
 
 ```ts
@@ -165,6 +166,7 @@ export default {
 | `roundtable doctor [--reachable]` | Checks the setup and says how to fix what is wrong |
 | `roundtable start` | Runs the checks that need no network, then the bot |
 | `roundtable add plugin <name>` | Adds `plugins/<name>.ts` and its test, and lists it in the config |
+| `roundtable add package <spec>` | Installs a Pi package with `bun add` and adds a plugin that loads it and gives its tools to every agent turn |
 
 ## Changes and license
 

package/README.zh-TW.md

@@ -76,6 +76,7 @@ Bun 會自己讀 `.env`，`.gitignore` 也已經擋掉它。
 ## 外掛
 
 `roundtable add plugin <name>` 會建立 `plugins/<name>.ts` 和它的測試，並把它列進 `roundtable.config.ts`。
+`roundtable add package <spec>` 對 npm 上的 Pi package 做同樣的事：安裝套件，並寫好一個載入它的擴充、選用它的工具的外掛。
 外掛是一個有名稱和 `setup` 函式的物件，`setup` 回傳它要新增的東西；下面這個外掛給每個智慧體一個工具：
 
 ```ts
@@ -158,6 +159,7 @@ export default {
 | `roundtable doctor [--reachable]` | 檢查設定，並說明如何修正有問題的地方 |
 | `roundtable start` | 先執行不需要網路的檢查，再啟動 bot |
 | `roundtable add plugin <name>` | 新增 `plugins/<name>.ts` 和它的測試，並列進設定 |
+| `roundtable add package <spec>` | 用 `bun add` 安裝 Pi package，並新增一個載入它、把它的工具交給每一輪 agent 的外掛 |
 
 ## 變更與授權
 

package/docs/plugins.md

@@ -67,6 +67,8 @@ Use the kit's building blocks for a plugin that runs Pi itself, such as a coding
 The name is lowercase words joined by dashes, such as `my-notes`.
 Two names are reserved for the [official plugins](#official-plugins): `codex-images` and `dice` copy a ready-made plugin into the project.
 
+`roundtable add package <spec>` adds a Pi package from npm: it runs `bun add <spec>`, loads the package's extensions to find the tools they register, and writes `plugins/<name>.ts` and its test, named after the package without its scope, as [`piPackages`](#pipackages-pi-extensions-every-session-loads) describes.
+
 ## The plugin object
 
 ```ts
@@ -1268,6 +1270,17 @@ export function alwaysOn(tools: () => string[]) {
 
 List npm packages whose Pi extensions every conversation session should load, and install them in your project (`bun add pi-web-access`).
 Two plugins that name the same package load it once.
+Sessions load only these packages: the Pi packages in the host's own Pi settings, and its extension folders, stay out.
+
+Loading a package registers its tools, but a turn uses only the tools it selects, so list them in [`agentSelection`](#agentselection-tools-every-agent-carries) too, and in `requiredTools` so startup fails when a package version drops one.
+A tool no plugin gives a tier is the owner's alone; the operator lowers it with `toolTiers` in `roundtable.config.ts`.
+Give a package's tools a tier in the plugin only when no other plugin does: the built-in `modules` plugin already gives `web_search`, `fetch_content`, and `get_search_content` the member tier, and a second plugin naming them is a `PluginError`.
+
+`roundtable add package <spec>` writes such a plugin for you.
+It accepts a registry name, optionally scoped and versioned (`pi-web-access`, `@scope/name@1.2.3`), and refuses before installing when the config cannot take the plugin or `plugins/<name>.ts` exists.
+After `bun add`, it refuses a package whose `package.json` lists no extensions under `pi` and that has no `extensions` folder, and a package whose extensions fail to load; the package stays installed, and the message names the `bun remove` command.
+The plugin it writes lists every tool the package registers when it loads, gives none a tier, and its test checks that every listed tool is selected.
+A tool a package registers later, such as after a connection, is not found; add it to the list by hand.
 
 The built-in delegation worker also loads `pi-web-access` to search and read the web.
 `pi-roundtable` lists it as a peer dependency (`>=0.35.0 <0.36.0`), so `bun add pi-roundtable` installs it for you.
@@ -1278,11 +1291,19 @@ A project that has none installed stops at the `modules` plugin's setup with a `
 ```ts
 import { definePlugin } from "pi-roundtable";
 
-/** Pi packages are npm packages whose Pi extensions every session loads; install each one in your project first. */
+/**
+ * Pi packages are npm packages whose Pi extensions every session loads; install each one in your
+ * project first. Loading a package registers its tools, and a turn uses only the tools it
+ * selects, so the plugin selects them too. `roundtable add package <name>` writes this for you.
+ */
+const WEB_TOOLS = ["web_search", "fetch_content", "get_search_content"];
+
 export const webSearch = definePlugin({
 	name: "web-search",
 	setup: () => ({
 		piPackages: ["pi-web-access"],
+		agentSelection: () => ({ tools: WEB_TOOLS, groups: [] }),
+		requiredTools: WEB_TOOLS,
 	}),
 });
 ```

package/examples/packages.test.ts

@@ -2,8 +2,13 @@ import { expect, test } from "bun:test";
 import { testPlugin } from "pi-roundtable/testing";
 import { webSearch } from "./packages.ts";
 
-test("the plugin asks every session to load pi-web-access", async () => {
+test("the plugin asks every session to load pi-web-access and gives every agent turn its tools", async () => {
 	const harness = await testPlugin(webSearch);
 	expect(harness.contribution.piPackages).toEqual(["pi-web-access"]);
+	expect(harness.contribution.agentSelection?.().tools).toEqual([
+		"web_search",
+		"fetch_content",
+		"get_search_content",
+	]);
 	await harness.stop();
 });

package/examples/packages.ts

@@ -1,9 +1,17 @@
 import { definePlugin } from "pi-roundtable";
 
-/** Pi packages are npm packages whose Pi extensions every session loads; install each one in your project first. */
+/**
+ * Pi packages are npm packages whose Pi extensions every session loads; install each one in your
+ * project first. Loading a package registers its tools, and a turn uses only the tools it
+ * selects, so the plugin selects them too. `roundtable add package <name>` writes this for you.
+ */
+const WEB_TOOLS = ["web_search", "fetch_content", "get_search_content"];
+
 export const webSearch = definePlugin({
 	name: "web-search",
 	setup: () => ({
 		piPackages: ["pi-web-access"],
+		agentSelection: () => ({ tools: WEB_TOOLS, groups: [] }),
+		requiredTools: WEB_TOOLS,
 	}),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.5.2",
+	"version": "0.6.1",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",

package/src/cli/add-package.ts

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { addPluginToConfig, ConfigEditError } from "./config-edit.ts";
+import type { PackagePorts } from "./pi-packages.ts";
+import {
+	isPluginName,
+	pluginNames,
+	renderPackagePlugin,
+	writeRendered,
+} from "./templates.ts";
+
+const CONFIG = "roundtable.config.ts";
+
+export interface AddPackageInputs {
+	cwd: string;
+	/** What `bun add` takes from the registry: a name, optionally scoped, optionally with `@<version>`. */
+	spec: string;
+	ports: PackagePorts;
+	/** Where the templates are; default the package's own. */
+	templates?: string;
+}
+
+export interface AddPackageReport {
+	ok: boolean;
+	problems: string[];
+	/** Paths written or changed, relative to `cwd`; `package.json` once the package is installed. */
+	changed: string[];
+	/** The tools the package registers, in the order its extensions register them. */
+	tools: string[];
+}
+
+const refused = (
+	problems: string[],
+	changed: string[] = [],
+): AddPackageReport => ({ ok: false, problems, changed, tools: [] });
+
+/** A registry spec: an optional `@scope/`, the name, and an optional `@<version or tag>`. */
+const SPEC = /^((?:@[a-z0-9][a-z0-9._-]*\/)?([a-z0-9][a-z0-9._-]*))(?:@(.+))?$/;
+
+/**
+ * Installs the Pi package `spec`, finds the tools its extensions register, and writes
+ * `plugins/<name>.ts` and its test, named after the package without its scope: the plugin loads
+ * the package in every session and gives every agent turn its tools, which stay the owner's
+ * until the operator's `toolTiers` lowers one. Everything that can be checked without the package is checked before `bun add` runs,
+ * so those refusals leave the project untouched; a package that fails to load after it is
+ * installed is reported with the command that removes it.
+ */
+export async function addPackage(
+	inputs: AddPackageInputs,
+): Promise<AddPackageReport> {
+	const { cwd, spec, ports } = inputs;
+	const parsed = SPEC.exec(spec);
+	if (!parsed?.[1] || !parsed[2])
+		return refused([
+			`${JSON.stringify(spec)} is not a package from the registry. Give its name, such as pi-web-access or @scope/name@1.2.3; install any other kind with bun add and list it in a plugin's piPackages by hand.`,
+		]);
+	const pkg = parsed[1];
+	const name = parsed[2];
+	if (!isPluginName(name))
+		return refused([
+			`the plugin would be named ${JSON.stringify(name)}, which is not lowercase words joined by dashes. Install it with bun add and list it in a plugin's piPackages by hand.`,
+		]);
+	const configPath = join(cwd, CONFIG);
+	if (!existsSync(configPath))
+		return refused([
+			`${CONFIG} is not in ${cwd}. Run this in the project directory, or create the project with \`roundtable init\`.`,
+		]);
+	const names = pluginNames(name);
+	const paths = [`plugins/${name}.ts`, `plugins/${name}.test.ts`];
+	const existing = paths.filter((path) => existsSync(join(cwd, path)));
+	if (existing.length > 0)
+		return refused([
+			`${existing.join(" and ")} already ${existing.length === 1 ? "exists" : "exist"}. Remove the file, or list ${pkg} in that plugin's piPackages by hand.`,
+		]);
+	let edited: string;
+	try {
+		edited = addPluginToConfig(readFileSync(configPath, "utf8"), names, CONFIG);
+	} catch (error) {
+		if (error instanceof ConfigEditError) return refused([error.message]);
+		throw error;
+	}
+	const installed = await ports.install(cwd, spec);
+	if (!installed.ok)
+		return refused([
+			`bun add ${spec} failed; nothing was written.`,
+			...(installed.output ? [installed.output] : []),
+		]);
+	let tools: string[];
+	try {
+		tools = await ports.tools(cwd, pkg);
+	} catch (error) {
+		return refused(
+			[
+				`${error instanceof Error ? error.message : String(error)} No plugin was written; run \`bun remove ${pkg}\` to uninstall it.`,
+			],
+			["package.json"],
+		);
+	}
+	const files = renderPackagePlugin(names, pkg, tools, inputs.templates);
+	writeRendered(cwd, files);
+	writeFileSync(configPath, edited);
+	return {
+		ok: true,
+		problems: [],
+		changed: ["package.json", ...files.map((file) => file.path), CONFIG],
+		tools,
+	};
+}

package/src/cli/cli.ts

@@ -2,12 +2,14 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { DefinedRoundtable } from "../core/define-roundtable.ts";
 import { Roundtable } from "../core/host.ts";
+import { addPackage } from "./add-package.ts";
 import { addPlugin } from "./add-plugin.ts";
 import type { BunFacts } from "./checks/bun.ts";
 import { postgres } from "./checks/database.ts";
 import { doctor } from "./doctor.ts";
 import { fetchHttp } from "./http.ts";
 import { init } from "./init.ts";
+import { type PackagePorts, piPackagePorts } from "./pi-packages.ts";
 import { loadConfigFile, type Ports } from "./project.ts";
 import { formatOutcomes } from "./report.ts";
 import { assemble, providerLogin } from "./runtime.ts";
@@ -21,6 +23,8 @@ export interface CliEnvironment {
 	bun: () => BunFacts;
 	version: () => string;
 	ports: Ports;
+	/** Installs Pi packages and reads the tools they register, for `add package`. */
+	packages: PackagePorts;
 	launch(defined: DefinedRoundtable): Promise<void>;
 	out(line: string): void;
 	err(line: string): void;
@@ -34,6 +38,8 @@ const USAGE = `roundtable: a Discord agent server on Pi
   roundtable add plugin <name>  add plugins/<name>.ts and its test, and list it in the config
                                 the names ${OFFICIAL_PLUGINS.join(" and ")} are reserved for the official plugins,
                                 which are copied in ready to run instead of the template
+  roundtable add package <spec> install a Pi package with bun add, and add plugins/<name>.ts that
+                                loads it and gives its tools to every agent turn
 `;
 
 /** The package's own version and the Bun range it needs, from the package.json beside the source. */
@@ -74,6 +80,7 @@ export function processEnvironment(): CliEnvironment {
 			define: assemble,
 			login: providerLogin,
 		},
+		packages: piPackagePorts,
 		launch: async (defined) => {
 			const roundtable = new Roundtable(defined.options, defined.plugins);
 			roundtable.listen();
@@ -122,8 +129,30 @@ export async function runCli(
 	}
 	if (command === "add") {
 		const [what, name, ...extra] = rest;
+		if (what === "package" && name !== undefined && extra.length === 0) {
+			const report = await addPackage({
+				cwd: io.cwd,
+				spec: name,
+				ports: io.packages,
+			});
+			if (!report.ok) {
+				for (const line of report.problems) io.err(line);
+				return 1;
+			}
+			io.out(`Added the Pi package ${name}:`);
+			for (const path of report.changed) io.out(`  ${path}`);
+			io.out(
+				report.tools.length > 0
+					? `Its tools: ${report.tools.join(", ")}. One no plugin gives a tier is the owner's alone; lower it with toolTiers in roundtable.config.ts.`
+					: "It registers no tools when it loads; the plugin still loads it in every session.",
+			);
+			return 0;
+		}
 		if (what !== "plugin" || name === undefined || extra.length > 0)
-			return usage(io, "usage: roundtable add plugin <name>");
+			return usage(
+				io,
+				"usage: roundtable add plugin <name>, or roundtable add package <spec>",
+			);
 		const report = addPlugin({ cwd: io.cwd, name });
 		if (!report.ok) {
 			for (const line of report.problems) io.err(line);

package/src/cli/config-edit.ts

@@ -115,6 +115,50 @@ function pluginList(object: Node): Node | undefined {
 interface Insertion {
 	at: number;
 	text: string;
+	/** How many characters from `at` the text replaces; none when it only inserts. */
+	replaces?: number;
+}
+
+/** The width the formatter gives a line: a tab counts as its default indent width of 2. */
+const LINE_WIDTH = 80;
+const width = (line: string): number => line.replaceAll("\t", "  ").length;
+
+/**
+ * The one-line list with `ident` added, put one element a line when the line it sits on would
+ * pass the formatter's width, as the project's formatter would; undefined when the list already
+ * spans lines, holds anything besides its elements and commas, or still fits.
+ */
+function expandedList(
+	source: string,
+	list: Node,
+	elements: readonly Node[],
+	ident: string,
+): Insertion | undefined {
+	const inner = source.slice(list.start + 1, list.end - 1);
+	if (inner.includes("\n")) return undefined;
+	const items = elements.map((element) =>
+		source.slice(element.start, element.end),
+	);
+	// The text around and between the elements, which must be only commas and spaces.
+	const edges = [
+		list.start + 1,
+		...elements.flatMap((element) => [element.start, element.end]),
+		list.end - 1,
+	];
+	let gaps = "";
+	for (let index = 0; index < edges.length; index += 2)
+		gaps += source.slice(edges[index], edges[index + 1]);
+	if (!/^[\s,]*$/.test(gaps)) return undefined;
+	const lineStart = source.lastIndexOf("\n", list.start) + 1;
+	const lineEnd = source.indexOf("\n", list.end);
+	const line = `${source.slice(lineStart, list.start)}[${[...items, ident].join(", ")}]${source.slice(list.end, lineEnd === -1 ? undefined : lineEnd)}`;
+	if (width(line) <= LINE_WIDTH) return undefined;
+	const indent = /^[ \t]*/.exec(source.slice(lineStart, list.start))?.[0] ?? "";
+	return {
+		at: list.start,
+		replaces: list.end - list.start,
+		text: `[\n${[...items, ident].map((item) => `${indent}\t${item},\n`).join("")}${indent}]`,
+	};
 }
 
 /** The text to add so `ident` joins the list, in the list's own layout. */
@@ -122,6 +166,8 @@ function listInsertion(source: string, list: Node, ident: string): Insertion {
 	const elements = (list.elements as (Node | null)[]).filter(
 		(element): element is Node => element !== null,
 	);
+	const expanded = expandedList(source, list, elements, ident);
+	if (expanded) return expanded;
 	const last = elements.at(-1);
 	if (!last) return { at: list.start + 1, text: ident };
 	const between = source.slice(last.end, list.end - 1);
@@ -161,8 +207,9 @@ function importInsertion(
 
 /**
  * Adds the plugin's import line and lists it in the `plugins` array of the default export, in the
- * file's own layout. It refuses, changing nothing, a file that does not parse, a default export
- * with no `plugins` list it can find, and a name already bound.
+ * file's own layout; a one-line list that would pass 80 columns is put one element a line. It
+ * refuses, changing nothing, a file that does not parse, a default export with no `plugins` list
+ * it can find, and a name already bound.
  */
 export function addPluginToConfig(
 	source: string,
@@ -192,7 +239,10 @@ export function addPluginToConfig(
 	].sort((a, b) => b.at - a.at);
 	let edited = source;
 	for (const edit of edits)
-		edited = edited.slice(0, edit.at) + edit.text + edited.slice(edit.at);
+		edited =
+			edited.slice(0, edit.at) +
+			edit.text +
+			edited.slice(edit.at + (edit.replaces ?? 0));
 	// A result that does not parse is a bug here; never write it.
 	parseModule(edited, file);
 	return edited;

package/src/cli/pi-packages.ts

@@ -0,0 +1,79 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, sep } from "node:path";
+import { discoverAndLoadExtensions } from "@earendil-works/pi-coding-agent";
+import { packageDir } from "../core/shared/package-dir.ts";
+
+/** What `add package` asks of the world outside the project's files; tests replace both. */
+export interface PackagePorts {
+	/** Installs `spec` into the project at `cwd`, as `bun add` does. */
+	install(cwd: string, spec: string): Promise<{ ok: boolean; output: string }>;
+	/**
+	 * The tools the Pi extensions of the installed package `name` register when they load, looked
+	 * up from the project at `cwd`. Throws when the package has no Pi extension or one fails to load.
+	 */
+	tools(cwd: string, name: string): Promise<string[]>;
+}
+
+async function bunAdd(cwd: string, spec: string) {
+	const child = Bun.spawn(["bun", "add", spec], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const [stdout, stderr, code] = await Promise.all([
+		new Response(child.stdout).text(),
+		new Response(child.stderr).text(),
+		child.exited,
+	]);
+	return { ok: code === 0, output: `${stdout}${stderr}`.trim() };
+}
+
+/** Whether the package says it holds Pi extensions: a `pi.extensions` list, or an `extensions` folder. */
+function declaresExtensions(dir: string): boolean {
+	const manifest: { pi?: { extensions?: unknown } } = JSON.parse(
+		readFileSync(join(dir, "package.json"), "utf8"),
+	);
+	const listed = manifest.pi?.extensions;
+	return Array.isArray(listed)
+		? listed.length > 0
+		: existsSync(join(dir, "extensions"));
+}
+
+/**
+ * Loads the package's extensions as a session would, from an empty Pi agent directory so no
+ * extension of the user's own joins in, and keeps only the ones inside the package.
+ */
+async function registeredTools(cwd: string, name: string): Promise<string[]> {
+	const dir = packageDir(name, join(cwd, "package.json"));
+	// Pi would load a plain package's index file as an extension; a library is not a Pi package.
+	if (!declaresExtensions(dir))
+		throw new Error(
+			`${name} is not a Pi package: its package.json lists no extensions under "pi", and it has no extensions folder.`,
+		);
+	const agentDir = mkdtempSync(join(tmpdir(), "roundtable-package-"));
+	try {
+		const loaded = await discoverAndLoadExtensions([dir], cwd, agentDir);
+		const failed = loaded.errors.filter((error) => error.path.startsWith(dir));
+		if (failed.length > 0)
+			throw new Error(
+				`${name} failed to load: ${failed.map((error) => error.error).join("; ")}`,
+			);
+		const own = loaded.extensions.filter((extension) =>
+			`${extension.resolvedPath}${sep}`.startsWith(`${dir}${sep}`),
+		);
+		if (own.length === 0)
+			throw new Error(`${name} declares Pi extensions, but none loaded.`);
+		return [
+			...new Set(own.flatMap((extension) => [...extension.tools.keys()])),
+		];
+	} finally {
+		rmSync(agentDir, { recursive: true, force: true });
+	}
+}
+
+/** The real installer and loader. */
+export const piPackagePorts: PackagePorts = {
+	install: bunAdd,
+	tools: registeredTools,
+};

package/src/cli/templates.ts

@@ -16,6 +16,9 @@ const PLUGIN_DIR = "plugin";
 /** The directory of the official plugins, one directory each, named as `add plugin` names them. */
 const OFFICIAL_DIR = "official";
 
+/** The directory of the plugin `add package` writes around a Pi package. */
+const PACKAGE_DIR = "package";
+
 /** The plugins the package ships ready-made: `add plugin <name>` copies these instead of the `hello` template, so the names are reserved. */
 export const OFFICIAL_PLUGINS = ["codex-images", "dice"] as const;
 
@@ -102,6 +105,40 @@ export function renderPlugin(
 	}));
 }
 
+/** The `TOOLS` constant as the project's formatter writes it: on one line when it fits in 80 columns. */
+function toolsConstant(tools: readonly string[]): string {
+	const items = tools.map((tool) => JSON.stringify(tool));
+	const line = `const TOOLS: string[] = [${items.join(", ")}];`;
+	return line.length <= 80
+		? line
+		: `const TOOLS: string[] = [\n${items.map((item) => `\t${item},\n`).join("")}];`;
+}
+
+/** The plugin `add package` writes around the Pi package `pkg`, and its test, with the tools the package registers. */
+export function renderPackagePlugin(
+	names: PluginNames,
+	pkg: string,
+	tools: readonly string[],
+	dir = TEMPLATES_DIR,
+): Rendered[] {
+	const values = {
+		NAME: names.name,
+		IDENT: names.ident,
+		PACKAGE: pkg,
+		TOOLS: toolsConstant(tools),
+	};
+	return [
+		["plugin.ts.tmpl", `plugins/${names.name}.ts`],
+		["plugin.test.ts.tmpl", `plugins/${names.name}.test.ts`],
+	].map(([file, path]) => ({
+		path: path as string,
+		content: fill(
+			readFileSync(join(dir, PACKAGE_DIR, file as string), "utf8"),
+			values,
+		),
+	}));
+}
+
 /** Every file of a new project: the skeleton and the `hello` plugin, paths relative to the project. */
 export function renderProject(
 	substitutions: Substitutions,
@@ -115,7 +152,9 @@ export function renderProject(
 	const skeleton = filesUnder(dir)
 		.map((file) => relative(dir, file))
 		.flatMap((path) =>
-			path.startsWith(`${PLUGIN_DIR}/`) || path.startsWith(`${OFFICIAL_DIR}/`)
+			[PLUGIN_DIR, OFFICIAL_DIR, PACKAGE_DIR].some((sub) =>
+				path.startsWith(`${sub}/`),
+			)
 				? []
 				: [
 						{

package/templates/README.md

@@ -8,4 +8,5 @@ A Discord agent server built on [pi-roundtable](https://www.npmjs.com/package/pi
 
 `roundtable.config.ts` holds the settings and lists the plugins; `plugins/` holds yours.
 Add another with `bunx roundtable add plugin <name>`, and test it with `bun test`.
+Add a Pi package from npm with `bunx roundtable add package <name>`; it installs the package and writes the plugin that loads it.
 The plugin guide is in `node_modules/pi-roundtable/docs/plugins.md` and on the package's page.

package/templates/package/plugin.test.ts.tmpl

@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { __IDENT__ } from "./__NAME__.ts";
+
+test("__NAME__ loads __PACKAGE__ and gives every agent turn its tools", async () => {
+	const harness = await testPlugin(__IDENT__);
+	const { piPackages, agentSelection, requiredTools } = harness.contribution;
+	expect(piPackages).toEqual(["__PACKAGE__"]);
+	expect(agentSelection?.().tools).toEqual([...(requiredTools ?? [])]);
+	await harness.stop();
+});

package/templates/package/plugin.ts.tmpl

@@ -0,0 +1,18 @@
+import { definePlugin } from "pi-roundtable";
+
+/** The tools __PACKAGE__ registered when `roundtable add package` installed it. */
+__TOOLS__
+
+/**
+ * Loads the Pi package __PACKAGE__ in every conversation session and gives every agent turn its
+ * tools. A tool no plugin gives a tier is the owner's alone; lower one with `toolTiers` in
+ * roundtable.config.ts, such as `toolTiers: { web_search: "member" }`.
+ */
+export const __IDENT__ = definePlugin({
+	name: "__NAME__",
+	setup: () => ({
+		piPackages: ["__PACKAGE__"],
+		agentSelection: () => ({ tools: [...TOOLS], groups: [] }),
+		requiredTools: TOOLS,
+	}),
+});