pi-roundtable 0.30.0 → 0.30.3

package/CHANGELOG.md

@@ -5,6 +5,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.30.3] - 2026-11-01
+
+- 0.30.2 was tagged but never published: its release run stopped on lint (a hook's dependency suppression the change had dropped) before any package was published. 0.30.3 carries 0.30.2's changes. No core behavior changes.
+
+## [0.30.2] - 2026-11-01
+
+- Release for the web package's changes (see its changelog); no core behavior changes.
+
+## [0.30.1] - 2026-11-01
+
+### Fixed
+
+- A declared chat command is listed (`PluginContext.chatCommands()`, the web command menu) only after a session the host built has loaded it from an extension of the declaring plugin: a package in its own `piPackages` or one of its own session tools. A declaration nothing registers, or that another plugin's extension registers, is no longer listed, so a plugin cannot label another package's command with its own description. `LinkedSessions` has a new optional `chatCommands` part that the runtime tells of each built session's commands; a hand-built `LinkedSessions` without it still works and lists no declared command. An extension belongs to the package whose folder is nearest to it (the nearest `package.json`), so a package installed inside another's folder is not taken for the outer one.
+
 ## [0.30.0] - 2026-11-01
 
 ### Added

package/docs/plugins.md

@@ -2351,9 +2351,10 @@ export default {
 
 - `name` is lowercase letters, digits, dashes and underscores, starting with a letter, written without the slash. `clear`, `new` and `skill` are the app's own (`/clear` and `/new` start a room over, `/skill:<name>` runs a skill the agent carries) and a plugin cannot take them; a name declared twice, by one plugin or two, is a `PluginError`.
 - `description` is one line for the menu.
+- A declaration is a label until a session proves it: a command is listed only after a session the host built has loaded it from an extension of the declaring plugin itself, that is a package in the plugin's own `piPackages` or one of its own `sessionTools` (or `tools`). A name nothing registers is never listed, and neither is a name that another plugin's extension registers: declare a command from the plugin that carries it. The host's startup check builds the first sessions, so the list is complete before any service starts; an extension that only a later session loads joins the list when that session is built. The host does not refuse such a declaration, it only leaves it out. An extension belongs to the package of the nearest folder above it with a `package.json`, so a package installed inside another package's folder counts as its own. Until the first session is built the list is empty (so is it under `testPlugin`, which builds no session), and a command stays listed for the life of the process once a session has loaded it.
 - Only an owner sees the entry, and only an owner's message can run the command: the text of any other speaker is prefixed with who wrote it (`(Message from …, at the member tier.)`), so Pi never reads it as a command. A schedule's text follows its own header and a delegated task's text is sent to its worker as plain text (templates, skills and commands are not expanded), so neither can reach a command. The handler runs in the host process with the owner's authority, so declare only what you would let any owner trigger from a phone.
 - A command is sent as a normal message. While a turn runs it is not steered into the turn (Pi refuses to queue a command): it waits for its own turn, as a message from another speaker does, and Pi runs the handler then.
-- `context.chatCommands()` returns every plugin's declarations in contribution order, once linked; during `setup` it throws `NotLinkedError`. The web app reads it for `GET api/rooms/<room>/commands`.
+- `context.chatCommands()` returns the declarations that are listed (see above) in contribution order, once linked; during `setup` it throws `NotLinkedError`. The web app reads it for `GET api/rooms/<room>/commands`.
 
 ### `sessionTools`: the raw form of `tools`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.30.0",
+	"version": "0.30.3",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/host-registration.ts

@@ -218,7 +218,7 @@ export class Linkage {
 						throw new NotLinkedError(
 							"chat commands are linked once every plugin is set up. Call chatCommands() from a service's start or from a handler, not during setup.",
 						);
-					return this.registry.chatCommands;
+					return this.registry.chatCommandSources.listed();
 				},
 				observe: (filter, observer) => this.observers.add(filter, observer),
 				apiKey: async (provider) => this.#options.apiKey?.(provider),

package/src/core/plugin.ts

@@ -37,10 +37,7 @@ import type {
 import type { Speaker, Tier } from "./speakers.ts";
 import type { ToolTiers } from "./tool-tiers.ts";
 
-/**
- * A long-lived part of a plugin. Services start in registration order and stop in reverse,
- * so one registered earlier outlives those registered after it.
- */
+/** A long-lived part of a plugin. Services start in registration order and stop in reverse, so one registered earlier outlives those after it. */
 export interface Service {
 	name: string;
 	start?(): Promise<void> | void;
@@ -291,12 +288,18 @@ export interface LinkedSessions {
 	agentTools: readonly string[];
 	/** Every plugin's agent selection merged, read before each agent turn. */
 	agentSelection(): ToolSelection;
+	/** Told which commands each built session registers, so only declared commands that exist are listed; a host that links sessions by hand may leave it out, and then no declared command is listed. */
+	chatCommands?: {
+		loaded(
+			commands: readonly {
+				invocationName: string;
+				sourceInfo: { path: string; baseDir?: string };
+			}[],
+		): void;
+	};
 }
 
-/**
- * What the agents' turns may use of the machine: "full" gives them the shell and file tools, and
- * "chat-only" none of them, as `agentServer: { tools: "chat-only" }` configures.
- */
+/** What the agents' turns may use of the machine: "full" has the shell and file tools, "chat-only" none (`agentServer: { tools: "chat-only" }`). */
 export type AgentTools = "full" | "chat-only";
 
 /** The host's own locale and time zone, as its plugins read them. */
@@ -378,7 +381,7 @@ export interface PluginContext {
 	providers: ResolvedProviders;
 	/** Every plugin's dashboard lines, in contribution order; throws NotLinkedError during setup. */
 	dashboard(): readonly string[];
-	/** Every plugin's declared chat commands, in contribution order; throws NotLinkedError during setup. */
+	/** The declared chat commands a loaded extension of the declaring plugin registers, in contribution order; throws NotLinkedError during setup. */
 	chatCommands(): readonly ChatCommand[];
 	/**
 	 * The credential the host's model login holds for a provider, such as `openai-codex`: the same
@@ -395,10 +398,7 @@ export interface PluginContext {
 	listener(id: string): Readonly<ListenerAddress> | undefined;
 }
 
-/**
- * An identity a plugin's own credential stands for, such as the bearer token of an endpoint it
- * serves, and the principal it speaks as.
- */
+/** An identity a plugin's own credential stands for, such as the bearer token of an endpoint it serves, and the principal it speaks as. */
 export interface PluginIdentity {
 	/**
 	 * Written `token:<subject>`, such as `token:remote-mcp`. Only the `token` provider is accepted:

package/src/core/registry/chat-commands.ts

@@ -1,5 +1,8 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 import type { ChatCommand } from "../contract/chat-command.ts";
 import { PluginError } from "../errors.ts";
+import { packageDir } from "../shared/package-dir.ts";
 
 const CHAT_COMMAND_NAME = /^[a-z][a-z0-9_-]*$/;
 /** The commands the web app answers itself, so a declared command cannot take their names. */
@@ -31,3 +34,99 @@ export function claimChatCommand(
 		);
 	names.set(name, plugin);
 }
+
+/** Where a plugin's extensions come from: its Pi packages, and the names of its session tools. */
+export interface ChatCommandOrigin {
+	packages: readonly string[];
+	sessionTools: readonly string[];
+}
+
+/** A command a loaded Pi session registers, with the extension that registered it (Pi's `sourceInfo`). */
+export interface LoadedCommand {
+	/** What a message starts with after the slash. */
+	invocationName: string;
+	sourceInfo: { path: string; baseDir?: string };
+}
+
+/**
+ * Tells which declared chat commands are real. A declaration is only a label; a command is listed
+ * once a session the host built has loaded it from an extension of the plugin that declared it: a
+ * package that plugin lists in `piPackages`, or one of its session tools. A declaration nothing
+ * registers, or one that another plugin's extension registers, is never listed.
+ */
+export class ChatCommandSources {
+	readonly #declared = new Map<
+		string,
+		{ command: ChatCommand; origin: ChatCommandOrigin }
+	>();
+	/** Each command name a session registered, with the extensions that registered it. */
+	readonly #loaded = new Map<string, LoadedCommand["sourceInfo"][]>();
+	readonly #dirs = new Map<string, string | undefined>();
+	readonly #roots = new Map<string, string | undefined>();
+
+	/** `resolve` finds a package's folder by name; tests give their own. */
+	readonly #resolve: (name: string) => string;
+
+	constructor(resolve: (name: string) => string = packageDir) {
+		this.#resolve = resolve;
+	}
+
+	declare(command: ChatCommand, origin: ChatCommandOrigin): void {
+		this.#declared.set(command.name, { command, origin });
+	}
+
+	/** Records the commands a built session registered; called for every session, so the list grows as extensions load. */
+	loaded(commands: readonly LoadedCommand[]): void {
+		for (const { invocationName, sourceInfo } of commands) {
+			const seen = this.#loaded.get(invocationName) ?? [];
+			if (!seen.some((one) => one.path === sourceInfo.path))
+				this.#loaded.set(invocationName, [...seen, sourceInfo]);
+		}
+	}
+
+	/** The declared commands a loaded extension of the declaring plugin registers, in declaration order. */
+	listed(): ChatCommand[] {
+		return [...this.#declared.values()].flatMap(({ command, origin }) =>
+			(this.#loaded.get(command.name) ?? []).some((source) =>
+				this.#owns(origin, source),
+			)
+				? [command]
+				: [],
+		);
+	}
+
+	#owns(origin: ChatCommandOrigin, source: LoadedCommand["sourceInfo"]) {
+		if (origin.sessionTools.some((name) => source.path === `<inline:${name}>`))
+			return true;
+		return origin.packages.some((name) => {
+			const dir = this.#dir(name);
+			// The extension's own package is the nearest folder with a package.json, so a package
+			// installed inside another's folder (nested node_modules) is not taken for the outer one.
+			return dir !== undefined && this.#root(source.path) === dir;
+		});
+	}
+
+	#root(path: string): string | undefined {
+		if (!this.#roots.has(path)) {
+			let dir = existsSync(join(path, "package.json")) ? path : dirname(path);
+			while (!existsSync(join(dir, "package.json")) && dirname(dir) !== dir)
+				dir = dirname(dir);
+			this.#roots.set(
+				path,
+				existsSync(join(dir, "package.json")) ? dir : undefined,
+			);
+		}
+		return this.#roots.get(path);
+	}
+
+	#dir(name: string): string | undefined {
+		if (!this.#dirs.has(name)) {
+			try {
+				this.#dirs.set(name, this.#resolve(name));
+			} catch {
+				this.#dirs.set(name, undefined);
+			}
+		}
+		return this.#dirs.get(name);
+	}
+}

package/src/core/registry/contributions.ts

@@ -34,7 +34,7 @@ import {
 } from "../sessions.ts";
 import { TIERS } from "../speakers.ts";
 import type { ToolTierTable } from "../tool-tiers.ts";
-import { claimChatCommand } from "./chat-commands.ts";
+import { ChatCommandSources, claimChatCommand } from "./chat-commands.ts";
 import { ServiceRegistry } from "./services.ts";
 import { surfaceService } from "./surface-service.ts";
 
@@ -57,6 +57,8 @@ export interface Registry {
 	directChannels: DirectChannelProvider[];
 	dashboard: string[];
 	chatCommands: ChatCommand[];
+	/** Which of the declared chat commands a loaded extension really registers. */
+	chatCommandSources: ChatCommandSources;
 	tools: ToolContribution[];
 	seeds: AgentSeed[];
 	prompt: PromptSection[];
@@ -79,6 +81,7 @@ export const emptyRegistry = (): Registry => ({
 	directChannels: [],
 	dashboard: [],
 	chatCommands: [],
+	chatCommandSources: new ChatCommandSources(),
 	tools: [],
 	seeds: [],
 	prompt: [],
@@ -451,8 +454,16 @@ export async function collectContributions(
 		registry.backgroundTargets.push(...backgroundTargets);
 		registry.directChannels.push(...directChannels);
 		registry.dashboard.push(...dashboard);
-		for (const command of chatCommands)
+		for (const command of chatCommands) {
 			claimChatCommand(chatCommandNames, plugin.name, command);
+			registry.chatCommandSources.declare(command, {
+				packages: piPackages,
+				sessionTools: [
+					...(contribution.sessionTools ?? []),
+					...tools.map((tool) => tool.session),
+				].map((tool) => tool.name),
+			});
+		}
 		registry.chatCommands.push(...chatCommands);
 		checkSeedCharacters(plugin.name, seeds);
 		registry.seeds.push(...seeds);
@@ -481,5 +492,6 @@ export function linkSessions(registry: Registry): LinkedSessions {
 		requiredTools: [...new Set(registry.requiredTools)],
 		agentTools: registry.tools.flatMap((t) => (t.agent ? [t.name] : [])),
 		agentSelection: () => mergeSelections(registry.agentSelections),
+		chatCommands: registry.chatCommandSources,
 	};
 }

package/src/core/runtime/session-factory.ts

@@ -485,6 +485,9 @@ export class SessionFactory {
 		}
 		await session.setModel(resolved);
 		await this.#awaitTools(session, awaited);
+		this.link().chatCommands?.loaded(
+			session.extensionRunner.getRegisteredCommands(),
+		);
 		session.subscribe((event) => {
 			if (event.type === "compaction_end")
 				this.#logCompaction(channel, event, session, tiers);

package/src/testing.ts

@@ -557,7 +557,7 @@ export async function testPlugin(
 		providers,
 		dashboard: () => (linked ? registry.dashboard : unlinked("dashboard")),
 		chatCommands: () =>
-			linked ? registry.chatCommands : unlinked("chatCommands"),
+			linked ? registry.chatCommandSources.listed() : unlinked("chatCommands"),
 		apiKey: async (provider) =>
 			Object.hasOwn(options.apiKeys ?? {}, provider)
 				? options.apiKeys?.[provider]