pi-roundtable 0.24.2 → 0.25.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/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/session-factory.ts

@@ -49,6 +49,7 @@ import {
 	type ConfirmationGate,
 	confirmationGateExtension,
 } from "./extensions/confirmation-gate.ts";
+import { personaPromptExtension } from "./extensions/persona-prompt.ts";
 import {
 	MemoryDraws,
 	privateCompaction,
@@ -390,42 +391,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();

package/src/core/services.ts

@@ -25,6 +25,10 @@ import type {
 	MemoryKind,
 	PromptMemory,
 } from "./modules/memory/owner-memory-store.ts";
+import type {
+	PromptDocuments,
+	PromptVersion,
+} from "./modules/prompts/prompt-documents.ts";
 import type {
 	PrecheckFinding,
 	PrecheckRegistry,
@@ -34,11 +38,9 @@ import type {
 	Schedule,
 	ScheduleChange,
 } from "./modules/schedules/schedule-store.ts";
-import type {
-	SkillCatalogEntry,
-	SkillSet,
-} from "./modules/skills/skill-rules.ts";
+import type { SkillRegistry } from "./modules/skills/skill-contract.ts";
 import type { AgentTurnScope, ChannelKey } from "./sessions.ts";
+import type { Speaker } from "./speakers.ts";
 import type { DispatchThreads } from "./threads/dispatch-threads.ts";
 
 // The services the built-in plugins provide, and the ports they keep to. Each port is an
@@ -145,6 +147,16 @@ export const SKILLS: ServiceKey<SkillRegistry> = serviceKey<SkillRegistry>(
 	},
 );
 
+/**
+ * The prompt texts the owner edits in the app, each with a file version, an override and a
+ * history. Provided by the built-in `prompts` plugin, which registers `shared` and `guest` (the
+ * prompts of the agent server) and which every plugin set up after it may register more with; a
+ * plugin reads a document's `text()` when it builds a prompt, so an override applies from the next
+ * turn. Read it with `get`: the plugin is always on.
+ */
+export const PROMPTS: ServiceKey<PromptDocuments> =
+	serviceKey<PromptDocuments>("roundtable.prompts");
+
 /** What the agent server builds, for the plugins set up after it. */
 export interface AgentServer {
 	team: AgentTeam;
@@ -209,6 +221,29 @@ export interface AgentDirectory {
 	groupByChannel(channelId: string): AgentGroup | undefined;
 }
 
+/** What an owner gives to create an agent: the fields of `agent_create`, with the settings `update` takes. */
+export interface NewAgent {
+	/** Permanent: lowercase letters, digits and dashes, 1 to 32. */
+	name: string;
+	displayName: string;
+	prompt: string;
+	/** Fields of its look; any left out come from the look its role suggests. */
+	character?: CharacterInput;
+	/** Its opening task; without it the agent only exists. */
+	task?: string;
+	/**
+	 * The surface whose room the opening task runs in, so the person who asked sees it start
+	 * there. Without it, or for a surface that hosts no rooms, the task runs where `agent_create`
+	 * runs it: the agent's Discord channel, else its first room.
+	 */
+	openIn?: string;
+	category?: string;
+	/** Skills it carries; refused when the skills addon is off. */
+	skills?: string[];
+	model?: string;
+	thinking?: string;
+}
+
 /** What an agent's settings may change, as `update` takes it. */
 export interface AgentChange {
 	displayName?: string;
@@ -259,8 +294,54 @@ export interface AgentTeam {
 	postAs(caller: AgentTurnScope, text: string): Promise<void>;
 	/** The assistant's own notice, posted in the coordinator's channel under its name. */
 	announce(text: string): Promise<void>;
-	/** Changes an agent's display name, prompt, model, or thinking level; a model must be one the host runs. */
-	update(name: string, change: AgentChange): Promise<string>;
+	/**
+	 * Changes an agent's display name, prompt, model, or thinking level; a model must be one the
+	 * host runs. `by` names who asks; a changed prompt is kept in the agent's prompt history under it.
+	 */
+	update(name: string, change: AgentChange, by?: string): Promise<string>;
+	/** The changes of an agent's prompt, newest first: who made each, when, and the text it replaced. */
+	promptHistory(name: string, limit?: number): Promise<PromptVersion[]>;
+	/**
+	 * Creates an agent for an owner, outside any agent turn: the checks, picture, channel and
+	 * opening task of `agent_create`, with `speaker` as the one who asked. `model` and `thinking`
+	 * take what `update` takes and are checked before anything is made; `task` is optional, and
+	 * without it the agent waits in its room. Throws AgentError for a bad or taken name, an
+	 * unusable model or an unknown skill.
+	 */
+	createAgent(speaker: Speaker, input: NewAgent): Promise<Agent>;
+	/**
+	 * Archives an agent or group like the `archive` tool: it stops answering, its schedules are
+	 * cancelled, an agent leaves its groups, and its history is kept. `caller` is the agent that
+	 * asks, which cannot archive itself; an owner's request has none. The coordinator cannot be
+	 * archived.
+	 */
+	archive(caller: AgentTurnScope | undefined, name: string): Promise<string>;
+	/**
+	 * Returns an archived agent or group to the active ones. An agent rejoins no group; a group
+	 * needs all its members active. Throws AgentError for an unknown or active name.
+	 */
+	restore(name: string): Promise<string>;
+	/**
+	 * Deletes an archived agent or group for good and frees its name. Throws AgentError for an
+	 * unknown name, for an active one (archive it first), and for an agent the host's seeds name,
+	 * which the next start would seed again. `cleanup` is a surface's own part of the delete (what
+	 * it kept under the name): it runs once the checks have passed and before anything is deleted,
+	 * and one that throws leaves the agent or group in place, so the delete can be tried again.
+	 */
+	remove(name: string, cleanup?: () => Promise<void>): Promise<string>;
+	/** Creates a group of 2 to 6 agents; the host is the first member unless given. */
+	createGroup(input: {
+		name: string;
+		displayName: string;
+		members: string[];
+		host?: string;
+		category?: string;
+	}): Promise<string>;
+	/** Changes a group's display name, members (all of them) or host. */
+	updateGroup(
+		name: string,
+		change: { displayName?: string; members?: string[]; host?: string },
+	): Promise<string>;
 	/**
 	 * Changes an agent's look: `input` is resolved over its current character (a new class keeps
 	 * its colors unless the input gives a palette or colors), rendered, and stored with the new
@@ -406,30 +487,4 @@ export interface SpeakerMemory {
 	remove(text: string): Promise<string[]>;
 }
 
-/** The skills agents carry: built in, linked from repositories, or written by an agent. */
-export interface SkillRegistry {
-	/** The built-in skills plus the named registered ones, resolved to their files. */
-	resolve(names: readonly string[]): SkillSet;
-	/** What an agent carries, built-in skills included. */
-	carried(agent: string): SkillSet;
-	/** The registered skills an agent carries, as the dashboard lists them. */
-	carriedNames(agent: string): string[];
-	/** An agent's skills as `agent_get` shows them. */
-	describeCarried(agent: string): string;
-	/** Every skill, built-in ones first. */
-	catalog(): SkillCatalogEntry[];
-	/** Every skill, or those of a group or matching a query, as the `skill_list` tool shows them. */
-	list(filter?: { group?: string; query?: string }): string;
-	/** The skills linked from a managed repository. */
-	linkedFrom(repo: string): string[];
-	/** Throws AgentError when a name is not registered; built-in names are carried already. */
-	checkRegistered(names: readonly string[]): void;
-	/** Links the skill at a repository path, or every child folder with a SKILL.md. */
-	link(repo: string, path: string): Promise<string>;
-	/** Adds and removes an agent's registered skills together, or changes nothing; returns what it carries after. */
-	attach(
-		agent: string,
-		add: readonly string[],
-		remove: readonly string[],
-	): Promise<string[]>;
-}
+export type { SkillRegistry } from "./modules/skills/skill-contract.ts";

package/src/index.ts

@@ -264,6 +264,14 @@ export type {
 	PromptMemory,
 } from "./core/modules/memory/owner-memory-store.ts";
 export { MEMORY_KINDS } from "./core/modules/memory/owner-memory-store.ts";
+export type {
+	PromptDocumentSpec,
+	PromptDocuments,
+	PromptDocumentView,
+	PromptHandle,
+	PromptVersion,
+} from "./core/modules/prompts/prompt-documents.ts";
+export { PromptConflictError } from "./core/modules/prompts/prompt-documents.ts";
 export type { PrecheckTool } from "./core/modules/schedules/precheck-tools.ts";
 export type {
 	Precheck,
@@ -291,9 +299,12 @@ export type {
 export type {
 	ResolvedSkill,
 	SkillCatalogEntry,
+	SkillDocument,
 	SkillSet,
 	SkillSource,
+	SkillVersion,
 } from "./core/modules/skills/skill-rules.ts";
+export { SkillConflictError } from "./core/modules/skills/skill-rules.ts";
 export type {
 	Contribution,
 	EventHandlers,
@@ -339,6 +350,7 @@ export type {
 	DelegationRequest,
 	Delegator,
 	MemoryStore,
+	NewAgent,
 	ScheduleStore,
 	SkillRegistry,
 	SpeakerMemory,
@@ -355,6 +367,7 @@ export {
 	MEMORY,
 	MODES,
 	PRECHECKS,
+	PROMPTS,
 	RUNTIME,
 	SCHEDULES,
 	SKILLS,