pi-roundtable 0.24.2 → 0.26.0

package/src/core/modules/skills/skill-tools.ts

@@ -81,11 +81,12 @@ export function skillListExtension(
 	);
 }
 
-/** The skill tools of an agent session. */
+/** The skill tools of an agent session; a skill the agent writes or edits is kept under `by`, the agent's name. */
 export function skillToolsExtension(
 	registry: StoredSkillRegistry,
 	/** Throws AgentError unless the name is an active agent. */
 	checkAgent: (name: string) => void,
+	by: string,
 ): ExtensionFactory {
 	return textToolsExtension(
 		[
@@ -127,11 +128,14 @@ export function skillToolsExtension(
 					body: BODY,
 				}),
 				run: (i) =>
-					registry.create({
-						name: requiredString(i, "name"),
-						description: requiredString(i, "description"),
-						body: requiredString(i, "body"),
-					}),
+					registry.create(
+						{
+							name: requiredString(i, "name"),
+							description: requiredString(i, "description"),
+							body: requiredString(i, "body"),
+						},
+						by,
+					),
 			},
 			{
 				name: "skill_update",
@@ -146,10 +150,14 @@ export function skillToolsExtension(
 				run: (i) => {
 					const description = optionalString(i, "description");
 					const body = optionalString(i, "body");
-					return registry.update(requiredString(i, "name"), {
-						...(description !== undefined ? { description } : {}),
-						...(body !== undefined ? { body } : {}),
-					});
+					return registry.update(
+						requiredString(i, "name"),
+						{
+							...(description !== undefined ? { description } : {}),
+							...(body !== undefined ? { body } : {}),
+						},
+						by,
+					);
 				},
 			},
 			{

package/src/core/plugin.ts

@@ -107,10 +107,30 @@ export interface EventHandlers {
 	turnProgress?(event: TurnProgressEvent): Promise<void> | void;
 	/** The team changed: an agent or group was created, edited, arranged, archived, or started over. */
 	changed?(): Promise<void> | void;
+	/**
+	 * Something a person did through a plugin's surface, reported by any plugin through
+	 * `context.events.action`: for example a support inbox's "assign", "reply" or "close". It names
+	 * the kind, who did it and whether it worked, never the content.
+	 */
+	action?(event: ActionEvent): Promise<void> | void;
 	/** The shutdown drain ended, before any service stops; `left` is the work it gave up on. */
 	shutdown?(left: readonly string[]): Promise<void> | void;
 }
 
+/** One thing a person did through a plugin's surface, as a handler hears of it. */
+export interface ActionEvent {
+	/** What was done, in the reporting plugin's words, such as "assign" or "close". */
+	kind: string;
+	/** The `Speaker.id` of who did it. */
+	actor: string;
+	principalId: string;
+	/** The conversation or page it concerns, when there is one. */
+	channel?: ChannelKey | `page:${string}`;
+	/** Whether it worked. */
+	ok: boolean;
+	at: Date;
+}
+
 /** What the core reports to the plugins' handlers. */
 export interface EventSink {
 	turnStarted(turn: TurnEvent): void;
@@ -118,6 +138,8 @@ export interface EventSink {
 	/** Optional, so a sink of your own written before it still fits. */
 	turnProgress?(event: TurnProgressEvent): void;
 	changed(): void;
+	/** Optional, as `turnProgress` is: a sink of your own written before it still fits. */
+	action?(event: ActionEvent): void;
 }
 
 /** What a prompt section is built for: one agent's turn. */
@@ -265,6 +287,12 @@ export interface LinkedSessions {
 	agentSelection(): ToolSelection;
 }
 
+/**
+ * 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.
+ */
+export type AgentTools = "full" | "chat-only";
+
 /** The host's own locale and time zone, as its plugins read them. */
 export interface HostEnv {
 	readonly locale: Locale;
@@ -284,6 +312,12 @@ export interface HostEnv {
 	 * agent wears the same ones.
 	 */
 	readonly characterSkins: readonly Hex[];
+	/**
+	 * Whether the agents' turns carry the shell and file tools. A plugin whose tools reach the host
+	 * checks it before it offers them to agents; under "chat-only" the host refuses to start with a
+	 * plugin that declares `hostAccess`.
+	 */
+	readonly agentTools: AgentTools;
 }
 
 /** What the host gives every plugin. */
@@ -391,6 +425,12 @@ export interface RoundtablePlugin {
 	 * dropped plugin provides a service this one does not replace.
 	 */
 	replaces?: readonly ServiceKey<unknown>[];
+	/**
+	 * Marks a plugin whose tools reach the host's machine, such as one that runs shells or edits
+	 * its files for the agents. A host that configures `agentServer: { tools: "chat-only" }`
+	 * refuses to start with one registered, with a ConfigError that names the plugin.
+	 */
+	hostAccess?: true;
 	setup(context: PluginContext): Promise<Contribution> | Contribution;
 	/**
 	 * Runs once every plugin is set up and linked, before any service starts; a failure stops the

package/src/core/registry/contributions.ts

@@ -25,6 +25,7 @@ import {
 	type DirectChannelProvider,
 	directChannelsPort,
 } from "../presence/direct-channels.ts";
+import { refuseShellTools } from "../runtime/chat-only.ts";
 import {
 	compileSessionPlan,
 	type SessionTool,
@@ -451,8 +452,14 @@ export async function collectContributions(
 				registry.holdRules.push(tool.hold);
 			}
 		}
-		if (contribution.agentSelection)
+		if (contribution.agentSelection) {
+			if (context.env.agentTools === "chat-only")
+				refuseShellTools(
+					contribution.agentSelection().tools,
+					`plugin ${plugin.name}: agentSelection`,
+				);
 			registry.agentSelections.push(contribution.agentSelection);
+		}
 		if (events) registry.handlers.push({ plugin: plugin.name, events });
 		registry.routes.push(...http);
 		registry.holdRules.push(...holdRules);

package/src/core/runtime/chat-only.ts

@@ -0,0 +1,32 @@
+import { ConfigError } from "../domain/errors.ts";
+import { SHELL_TOOLS } from "../modules/host-shell/shell-policy.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+
+const CHAT_ONLY = 'agentServer: { tools: "chat-only" }';
+
+/** The shell and file tools among these names. */
+export function shellToolsIn(names: Iterable<string>): string[] {
+	const shell: readonly string[] = SHELL_TOOLS;
+	return [...new Set(names)].filter((name) => shell.includes(name));
+}
+
+/**
+ * Refuses names that carry the machine's shell and file tools: the one place a chat-only host
+ * checks, where a selection turns into active tools. `where` says whose selection it is.
+ */
+export function refuseShellTools(names: Iterable<string>, where: string): void {
+	const found = shellToolsIn(names);
+	if (found.length > 0)
+		throw new ConfigError(
+			`${where} names ${found.join(", ")}, which ${CHAT_ONLY} withholds from every turn. Take the tool out of the selection, or remove tools: "chat-only" from agentServer to give the agents the shell.`,
+		);
+}
+
+/** Refuses, at start, a plugin whose tools reach the host: an agent of a chat-only host must not. */
+export function refuseHostAccess(plugins: readonly RoundtablePlugin[]): void {
+	const reaching = plugins.find((plugin) => plugin.hostAccess === true);
+	if (reaching)
+		throw new ConfigError(
+			`plugin ${reaching.name} declares hostAccess: its tools reach the host's machine, and the configuration says ${CHAT_ONLY}. Remove the plugin, or remove tools: "chat-only" from agentServer.`,
+		);
+}

package/src/core/runtime/conversation-sessions.ts

@@ -102,7 +102,8 @@ export class ConversationSessions {
 				this.#factory.link().holds,
 				this.#options.owner,
 				await this.#options.confirmations.load(key),
-				agents
+				// A chat-only host's agents have no shell, so their gate judges no workspace.
+				agents && this.#options.agentTools !== "chat-only"
 					? {
 							workspace: agents.workDir,
 							...(agents.scratchDir ? { scratchDir: agents.scratchDir } : {}),

package/src/core/runtime/extensions/agent-prompt.ts

@@ -1,16 +1,31 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { Logger } from "../../log.ts";
+import { readPromptOrStop } from "./prompt-read.ts";
 
 /**
  * Puts the agent's current prompt first in the system prompt's appended part before each run,
- * keeping what earlier handlers appended, such as the owner memory section.
+ * keeping what earlier handlers appended, such as the owner memory section. A `prompt()` that
+ * throws is logged as an error and stops the run: an agent never runs without its prompt.
  */
-export function agentPromptExtension(prompt: () => string): ExtensionFactory {
+export function agentPromptExtension(
+	prompt: () => string,
+	logger: Logger,
+	/** The agent's name, named in the log. */
+	agent: string,
+): ExtensionFactory {
 	return (pi) => {
-		pi.on("before_agent_start", (event) => {
+		pi.on("before_agent_start", (event, ctx) => {
+			const text = readPromptOrStop(
+				prompt,
+				ctx,
+				logger,
+				`The prompt of the agent "${agent}"`,
+			);
+			if (text === undefined) return;
 			const appended = event.systemPromptOptions.appendSystemPrompt;
 			event.systemPromptOptions.appendSystemPrompt = appended
-				? `${prompt()}\n\n${appended}`
-				: prompt();
+				? `${text}\n\n${appended}`
+				: text;
 		});
 	};
 }

package/src/core/runtime/extensions/persona-prompt.ts

@@ -0,0 +1,39 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { Logger } from "../../log.ts";
+import { readPromptOrStop } from "./prompt-read.ts";
+
+/**
+ * Brings the persona in the system prompt up to date before each run. The session was built with
+ * `initial`, the persona's text at that moment; when `current()` reads differently now, such as a
+ * prompt document the owner edited in the app, this run carries the new text in the same place.
+ * A `current()` that throws is logged as an error and stops the run: it does not go on with the
+ * text the session was built with.
+ */
+export function personaPromptExtension(
+	initial: string,
+	current: () => string,
+	logger: Logger,
+	/** The conversation kind, named in the log. */
+	kind: string,
+): ExtensionFactory {
+	return (pi) => {
+		pi.on("before_agent_start", (event, ctx) => {
+			const now = readPromptOrStop(
+				current,
+				ctx,
+				logger,
+				`The persona of the "${kind}" conversations`,
+			);
+			if (now === undefined || now === initial) return;
+			const appended = event.systemPromptOptions.appendSystemPrompt;
+			if (!appended) {
+				event.systemPromptOptions.appendSystemPrompt = now;
+				return;
+			}
+			event.systemPromptOptions.appendSystemPrompt =
+				initial === ""
+					? `${now}\n\n${appended}`
+					: appended.split(initial).join(now);
+		});
+	};
+}

package/src/core/runtime/extensions/prompt-read.ts

@@ -0,0 +1,22 @@
+import type { Logger } from "../../log.ts";
+
+/**
+ * Reads a prompt for the run that is starting. Pi swallows what a `before_agent_start` handler
+ * throws, so a prompt that cannot be read would let the run go on quietly with the prompt the
+ * session was built with, or with none at all. The failure is logged as an error and the run is
+ * stopped instead; the result is then undefined.
+ */
+export function readPromptOrStop(
+	read: () => string,
+	run: { abort(): void },
+	logger: Logger,
+	what: string,
+): string | undefined {
+	try {
+		return read();
+	} catch (error) {
+		logger.error({ err: error }, `${what} cannot be read; the run is stopped`);
+		run.abort();
+		return undefined;
+	}
+}

package/src/core/runtime/runtime-plugin.ts

@@ -199,6 +199,7 @@ export function runtimePlugin(
 						},
 						...turnPolicy(options),
 						sessions: context.sessions,
+						agentTools: context.env.agentTools,
 						agentDir: options.agentDir,
 						modelRuntime: options.modelRuntime,
 						dataDir: options.dataDir,

package/src/core/runtime/runtime-types.ts

@@ -16,7 +16,7 @@ import type { Logger } from "../log.ts";
 import type { EffortPolicy, ThinkingLevel, ThinkingPicker } from "../models.ts";
 import type { Autonomy } from "../modes/autonomy.ts";
 import type { ConversationModes } from "../modes/conversation-modes.ts";
-import type { LinkedSessions } from "../plugin.ts";
+import type { AgentTools, LinkedSessions } from "../plugin.ts";
 import {
 	planOrder,
 	type SessionContext,
@@ -75,6 +75,8 @@ export interface PiAgentRuntimeOptions {
 	sessions: () => LinkedSessions;
 	/** The agent server's sessions: their shared workspace, model, and skills. */
 	agents?: AgentSessions;
+	/** "chat-only": no turn carries the shell and file tools, and agent sessions have no workspace; default "full". */
+	agentTools?: AgentTools;
 	/**
 	 * The prompts of a channel for an interactive turn's scope, made from its speaker and its
 	 * conversation's visibility; undefined for a channel that cannot show them. Without it every

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

@@ -3,14 +3,11 @@ import { join } from "node:path";
 import {
 	type AgentSession,
 	createAgentSession,
-	createBashToolDefinition,
 	DefaultResourceLoader,
 	type ModelRuntime,
 	type SessionManager,
-	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { channelSegment } from "../attachments/attachment-dir.ts";
-import type { ImageDrawer } from "../contract/providers.ts";
 import type { ClientPort } from "../domain/client.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import { ConfigError } from "../domain/errors.ts";
@@ -29,16 +26,13 @@ import {
 	ATTACH_FILE_TOOL,
 	attachFileExtension,
 } from "../shared/attach-file-tool.ts";
-import {
-	GENERATE_IMAGE_TOOL,
-	generateImageExtension,
-} from "../shared/generate-image-tool.ts";
+import { GENERATE_IMAGE_TOOL } from "../shared/generate-image-tool.ts";
 import { packageDir } from "../shared/package-dir.ts";
 import { readAttachmentExtension } from "../shared/read-attachment-tool.ts";
-import type { WorkspaceRoots } from "../shared/workspace-files.ts";
 import { type Speaker, THE_SPEAKER } from "../speakers.ts";
 import { currentToolNames } from "../tool-tiers.ts";
 import { toolTurn } from "../tool-turn.ts";
+import { refuseShellTools } from "./chat-only.ts";
 import {
 	CompactionTiers,
 	compactionEngine,
@@ -49,6 +43,7 @@ import {
 	type ConfirmationGate,
 	confirmationGateExtension,
 } from "./extensions/confirmation-gate.ts";
+import { personaPromptExtension } from "./extensions/persona-prompt.ts";
 import {
 	MemoryDraws,
 	privateCompaction,
@@ -63,7 +58,6 @@ import type { PromptSlot } from "./prompt-slot.ts";
 import type {
 	ChannelSession,
 	CompactionEnd,
-	CoreExtensions,
 	PiAgentRuntimeOptions,
 } from "./runtime-types.ts";
 import {
@@ -77,6 +71,9 @@ import {
 	sessionAddressee,
 	turnAddressee,
 } from "./session-conversation.ts";
+import { imageTools, scratchBash } from "./session-helpers.ts";
+
+export { imageTools, scratchBash };
 
 /** What a session factory asks of the runtime that owns the turns. */
 export interface SessionFactoryDeps {
@@ -138,11 +135,22 @@ export class SessionFactory {
 		);
 	}
 
+	/** Whether the host's agents carry no shell or file tools. */
+	get chatOnly(): boolean {
+		return this.#options.agentTools === "chat-only";
+	}
+
 	get plan(): SessionPlan {
 		return this.link().plan;
 	}
 
+	/**
+	 * The tools a selection turns into. A chat-only host refuses a selection that names a shell or
+	 * file tool, whatever built it (the agent team, `context.turns`, a plugin), so the turn fails
+	 * closed before any session runs it.
+	 */
 	toolsFor(selection: ToolSelection): string[] {
+		if (this.chatOnly) refuseShellTools(selection.tools, "a tool selection");
 		const groups = planOrder(this.plan).flatMap(
 			(tool) => tool.snapshot().groups ?? [],
 		);
@@ -359,7 +367,8 @@ export class SessionFactory {
 			},
 			conversation,
 			addressee,
-			...(agents
+			// A chat-only host's agents work in no workspace.
+			...(agents && !this.chatOnly
 				? {
 						workspace: {
 							workspace: cwd,
@@ -390,42 +399,57 @@ export class SessionFactory {
 			noThemes: true,
 			noContextFiles: true,
 			additionalExtensionPaths: this.link().extensionPaths,
-			extensionFactories: sessionExtensions(this.plan, context, {
-				readAttachment: readAttachmentExtension(attachmentDir),
-				...(context.workspace
-					? { attachFile: attachFileExtension(context.workspace) }
-					: {}),
-				...imageTools(
-					this.#options.images,
-					context.workspace ?? { workspace: cwd },
-				),
-				confirmationGate: confirmationGateExtension(gate, slot, (signal) =>
-					toolTurn(context, signal),
-				),
-				askUser: askUserExtension(slot, addressee, () =>
-					turnAddressee(
-						this.#deps.speaker(turnKey),
-						state,
-						this.#options.owner,
+			extensionFactories: [
+				...(persona === undefined
+					? []
+					: [
+							{
+								name: "persona-prompt",
+								factory: personaPromptExtension(
+									persona,
+									() => this.personaOf(kind),
+									logger,
+									kind,
+								),
+							},
+						]),
+				...sessionExtensions(this.plan, context, {
+					readAttachment: readAttachmentExtension(attachmentDir),
+					...(context.workspace
+						? { attachFile: attachFileExtension(context.workspace) }
+						: {}),
+					...imageTools(
+						this.#options.images,
+						context.workspace ?? { workspace: cwd },
 					),
-				),
-				selfCompactGuard: selfCompactGuardExtension(),
-				// Each request carries no one's memory but the running turn's reader's.
-				privateMemory: privateMemoryExtension(
-					conversation.visibility === "shared",
-					() =>
-						deps.withholdsMemory(turnKey)
-							? undefined
-							: memoryReader(conversation, deps.speaker(turnKey)),
-					state.draws,
-				),
-				surfaceFormatting: surfaceFormattingExtension(() =>
-					// A worker writes a report for the turn, not a reply on its surface.
-					worker ? undefined : deps.formatting(turnKey),
-				),
-				activeTools: activeToolsExtension(() => state.tools),
-			}),
-			// An agent's prompt is set before each run by the agent-prompt extension.
+					confirmationGate: confirmationGateExtension(gate, slot, (signal) =>
+						toolTurn(context, signal),
+					),
+					askUser: askUserExtension(slot, addressee, () =>
+						turnAddressee(
+							this.#deps.speaker(turnKey),
+							state,
+							this.#options.owner,
+						),
+					),
+					selfCompactGuard: selfCompactGuardExtension(),
+					// Each request carries no one's memory but the running turn's reader's.
+					privateMemory: privateMemoryExtension(
+						conversation.visibility === "shared",
+						() =>
+							deps.withholdsMemory(turnKey)
+								? undefined
+								: memoryReader(conversation, deps.speaker(turnKey)),
+						state.draws,
+					),
+					surfaceFormatting: surfaceFormattingExtension(() =>
+						// A worker writes a report for the turn, not a reply on its surface.
+						worker ? undefined : deps.formatting(turnKey),
+					),
+					activeTools: activeToolsExtension(() => state.tools),
+				}),
+			],
+			// An agent's prompt is set before each run by the agent-prompt extension, and another kind's persona is read again before each run.
 			appendSystemPrompt: persona === undefined ? [] : [persona],
 		});
 		await resourceLoader.reload();
@@ -434,7 +458,7 @@ export class SessionFactory {
 			cwd,
 			agentDir,
 			// Pi's bash under its own name, run with TMPDIR at the agents' scratch dir.
-			...(agents?.scratchDir
+			...(agents?.scratchDir && !this.chatOnly
 				? { customTools: [scratchBash(cwd, agents.scratchDir)] }
 				: {}),
 			thinkingLevel: thinking,
@@ -463,22 +487,3 @@ export class SessionFactory {
 		return Object.assign(state, { session });
 	}
 }
-
-/** `generate_image` for a session of a host with an image provider; nothing without one. */
-export function imageTools(
-	images: ImageDrawer | undefined,
-	roots: WorkspaceRoots,
-): Pick<CoreExtensions, "generateImage"> {
-	return images ? { generateImage: generateImageExtension(images, roots) } : {};
-}
-
-/** Pi's bash tool with TMPDIR set to `scratchDir`, so tools that read TMPDIR and GNU `mktemp` write there (BSD `mktemp` needs `-p "$TMPDIR"`). */
-export function scratchBash(cwd: string, scratchDir: string): ToolDefinition {
-	// SAFETY: Pi's bash definition is a ToolDefinition typed by its own parameter schema, which the session takes as any custom tool.
-	return createBashToolDefinition(cwd, {
-		spawnHook: (context) => ({
-			...context,
-			env: { ...context.env, TMPDIR: scratchDir },
-		}),
-	}) as unknown as ToolDefinition;
-}

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

@@ -0,0 +1,27 @@
+import {
+	createBashToolDefinition,
+	type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { ImageDrawer } from "../contract/providers.ts";
+import { generateImageExtension } from "../shared/generate-image-tool.ts";
+import type { WorkspaceRoots } from "../shared/workspace-files.ts";
+import type { CoreExtensions } from "./runtime-types.ts";
+
+/** `generate_image` for a session of a host with an image provider; nothing without one. */
+export function imageTools(
+	images: ImageDrawer | undefined,
+	roots: WorkspaceRoots,
+): Pick<CoreExtensions, "generateImage"> {
+	return images ? { generateImage: generateImageExtension(images, roots) } : {};
+}
+
+/** Pi's bash tool with TMPDIR set to `scratchDir`, so tools that read TMPDIR and GNU `mktemp` write there (BSD `mktemp` needs `-p "$TMPDIR"`). */
+export function scratchBash(cwd: string, scratchDir: string): ToolDefinition {
+	// SAFETY: Pi's bash definition is a ToolDefinition typed by its own parameter schema, which the session takes as any custom tool.
+	return createBashToolDefinition(cwd, {
+		spawnHook: (context) => ({
+			...context,
+			env: { ...context.env, TMPDIR: scratchDir },
+		}),
+	}) as unknown as ToolDefinition;
+}