pi-roundtable 0.22.4 → 0.23.0

package/src/core/config/limits.ts

@@ -0,0 +1,93 @@
+import { ConfigError } from "../domain/errors.ts";
+import { type Autonomy, DEFAULT_LONG_RUNNING_MS } from "../modes/autonomy.ts";
+import { integer, list, optional, shape, text } from "./schema.ts";
+
+/** The configuration's `turnLimits` and `autonomy`: how long a turn works, and what runs without a person. */
+export interface LimitsConfig {
+	/**
+	 * How long one turn may work before it asks the owner on a card whether to go on, or is
+	 * stopped when it cannot show a card. Time spent waiting on the owner's cards does not count.
+	 */
+	turnLimits?: {
+		/** The budget of a turn, renewed by each message steered into it; 60 to 86400, default 600 (10 min). */
+		timeoutSeconds?: number;
+		/** The most one turn works in all, however often it is steered; at least `timeoutSeconds`, default three times it. */
+		maxSeconds?: number;
+		/** How long the card that asks whether to go on waits for an answer, in wall time; 30 to 3600, default 300. */
+		cardSeconds?: number;
+	};
+	/** What a conversation may do without a person, once its owner switches the mode on. */
+	autonomy?: {
+		/** Yolo mode: the server approves held calls instead of asking, within these limits. */
+		yolo?: {
+			/**
+			 * Hold classes yolo approves although it cards them by default, such as `shell.rm`, and the
+			 * names of rules that report no classes, such as `tool:repo_push`, whose calls it then approves.
+			 */
+			allow?: readonly string[];
+			/** Hold classes or rule names yolo never approves, such as `shell.push` or `tool:repo_push`. */
+			card?: readonly string[];
+		};
+		/** Long-running mode: a turn that reaches its time limit goes on by itself, up to this. */
+		longRunning?: {
+			/** The most one turn works in all before it asks or stops; 600 to 604800, default 14400 (4 h). */
+			maxSeconds?: number;
+		};
+	};
+}
+
+/** The two keys' shapes, spread into the configuration's. */
+export const limitsShape = {
+	turnLimits: optional(
+		shape({
+			timeoutSeconds: optional(integer(60, 86_400)),
+			maxSeconds: optional(integer(60, 604_800)),
+			cardSeconds: optional(integer(30, 3_600)),
+		}),
+	),
+	autonomy: optional(
+		shape({
+			yolo: optional(
+				shape({ allow: optional(list(text)), card: optional(list(text)) }),
+			),
+			longRunning: optional(
+				shape({ maxSeconds: optional(integer(600, 604_800)) }),
+			),
+		}),
+	),
+};
+
+/** The limits with their defaults, in ms; `maxMs` is never below `timeoutMs`. */
+export interface ResolvedLimits {
+	turnLimits: { timeoutMs: number; maxMs: number; cardMs: number };
+	autonomy: Autonomy;
+}
+
+/** The configuration's limits with every default filled, refusing a cap below the timeout. */
+export function limitsOf(config: LimitsConfig): ResolvedLimits {
+	const { turnLimits, autonomy } = config;
+	const timeoutSeconds = turnLimits?.timeoutSeconds ?? 600;
+	const maxSeconds = turnLimits?.maxSeconds ?? 3 * timeoutSeconds;
+	if (maxSeconds < timeoutSeconds)
+		throw new ConfigError(
+			`config turnLimits.maxSeconds: expected at least turnLimits.timeoutSeconds (${timeoutSeconds}), got ${maxSeconds}. Raise maxSeconds, or lower timeoutSeconds.`,
+		);
+	const longRunning = autonomy?.longRunning?.maxSeconds;
+	return {
+		turnLimits: {
+			timeoutMs: timeoutSeconds * 1_000,
+			maxMs: maxSeconds * 1_000,
+			cardMs: (turnLimits?.cardSeconds ?? 300) * 1_000,
+		},
+		autonomy: {
+			yolo: {
+				allow: autonomy?.yolo?.allow ?? [],
+				card: autonomy?.yolo?.card ?? [],
+			},
+			longRunningMaxMs:
+				longRunning === undefined
+					? DEFAULT_LONG_RUNNING_MS
+					: longRunning * 1_000,
+		},
+	};
+}

package/src/core/config/ops.ts

@@ -0,0 +1,34 @@
+import { ConfigError } from "../domain/errors.ts";
+import type { ChannelKey } from "../sessions.ts";
+
+/** Where the errors go: one agent, or one conversation. */
+export type ResolvedOps = { agent: string } | { conversation: ChannelKey };
+
+/** Where the errors go: one of an agent or a conversation; an agent only where the agents live. */
+export function opsOf(
+	ops: { agent?: string; conversation?: string } | undefined,
+	withDiscord: boolean,
+): ResolvedOps | undefined {
+	if (!ops) return undefined;
+	const { agent, conversation } = ops;
+	if (agent !== undefined && conversation !== undefined)
+		throw new ConfigError(
+			"config ops: name an agent or a conversation, not both. Keep the one the reports go to.",
+		);
+	if (agent !== undefined) {
+		if (!withDiscord)
+			throw new ConfigError(
+				'config ops.agent: the agents live in Discord, which is not configured. Report to a conversation a plugin\'s chat surface serves instead, with ops: { conversation: "<surface>:<id>" }; the web chat takes no error reports.',
+			);
+		return { agent };
+	}
+	if (conversation === undefined)
+		throw new ConfigError(
+			'config ops: name an agent or a conversation, such as ops: { agent: "infra" } or ops: { conversation: "<surface>:<id>" }.',
+		);
+	if (!/^[^:]+:.+$/.test(conversation))
+		throw new ConfigError(
+			`config ops.conversation: expected a conversation key <surface>:<id>, got ${JSON.stringify(conversation)}. Write the surface's prefix, a colon, and the conversation's id.`,
+		);
+	return { conversation: conversation as ChannelKey };
+}

package/src/core/config/schema.ts

@@ -1,3 +1,8 @@
+import {
+	CharacterError,
+	type CharacterInput,
+	resolveCharacter,
+} from "../../characters/index.ts";
 import { ConfigError } from "../domain/errors.ts";
 import { nearest } from "../registry/contributions.ts";
 
@@ -129,6 +134,27 @@ export const guarded = <T>(
 	},
 });
 
+/** The fields of an agent's look, checked as `resolveCharacter` does; a bad field is named in the error. */
+export const characterInput: Field<CharacterInput> = {
+	describe: "an object of character fields, such as { class: 'knight' }",
+	check: (value, path) => {
+		try {
+			// Over a base so that a look without `class` is checked too.
+			resolveCharacter(
+				value as CharacterInput,
+				resolveCharacter({ class: "wizard" }),
+			);
+		} catch (error) {
+			if (error instanceof CharacterError)
+				throw new ConfigError(
+					`config ${path}.${error.field}: ${error.message}. Fix the character in roundtable.config.ts.`,
+				);
+			throw error;
+		}
+		return value as CharacterInput;
+	},
+};
+
 /** `false`, or whatever `item` accepts: a feature that is switched off, or configured. */
 export const orOff = <T>(item: Field<T>): Field<T | false> => ({
 	describe: `false, or ${item.describe}`,

package/src/core/contract/channels.ts

@@ -12,6 +12,26 @@ export interface AttachmentRef {
 	size: number;
 }
 
+/**
+ * A file on the host's disk that a surface hands the core in place of its bytes, such as an upload
+ * the surface stored. The core copies it into the conversation's attachment store as a stream and
+ * leaves the original where it is.
+ */
+export interface AttachmentFile {
+	/** Absolute path of a regular file the surface owns; a relative path, a symlink or another kind of file is refused with `EINVAL`. */
+	path: string;
+}
+
+/**
+ * What a surface hands the core for an attachment it made: the bytes, or, for a file too large to
+ * hold in memory, a file on disk or a stream the core stores as it comes. A file or stream is
+ * held to the surface's `maxAttachmentBytes`, and never buffered whole.
+ */
+export type AttachmentContent =
+	| Uint8Array
+	| AttachmentFile
+	| ReadableStream<Uint8Array>;
+
 /** The facts a surface reports about one incoming message; it never decides who may talk. */
 export interface InboundMessage {
 	channel: ChannelKey;

package/src/core/contract/surface.ts

@@ -1,11 +1,15 @@
-import type { OutboundReply } from "../domain/conversation.ts";
-import type { InterimPosts } from "../domain/interim.ts";
+import type { OutboundReply, PostAuthor } from "../domain/conversation.ts";
+import type { InterimMessage, InterimPosts } from "../domain/interim.ts";
 import type { TurnProgress } from "../domain/progress.ts";
 import { PluginError } from "../errors.ts";
 import type { PromptScope, Prompts } from "../interactions/prompts.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
-import type { InboundMessage } from "./channels.ts";
+import type {
+	AttachmentContent,
+	AttachmentRef,
+	InboundMessage,
+} from "./channels.ts";
 
 /**
  * Splits a channel key, `<surface>:<id>`, at its first colon: the surface names the chat network
@@ -33,6 +37,36 @@ export function channelKey(surface: string, id: string): ChannelKey {
 	return `${surface}:${id}`;
 }
 
+/**
+ * The threads a surface hosts for background dispatches (coding tasks, delegated tasks, messages
+ * between agents): a place beside a channel where one dispatch posts its progress and report. A
+ * thread's id is the surface's own and unique among its threads; the thread as a conversation
+ * channel is `channelKey(surface, id)`.
+ */
+export interface SurfaceThreads {
+	/**
+	 * Posts the start line in `parent` and opens a thread from it. `line` gives the start line's
+	 * text: called with no argument for the first post, and with the thread's `mention` once the
+	 * thread exists, so a surface that can edit its post shows the link. Resolves to undefined when
+	 * `parent` cannot host a thread, such as a direct message or a thread; rejects when the surface
+	 * refuses. `mention` is how the thread is named in text, such as `<#id>` on Discord.
+	 */
+	open(
+		parent: ChannelKey,
+		name: string,
+		line: (mention?: string) => string,
+	): Promise<{ id: string; mention: string } | undefined>;
+	/** Posts text in the thread. */
+	post(thread: string, text: string): Promise<void>;
+	/**
+	 * Posts one message of at most 2000 characters and resolves to it, so it can be edited in
+	 * place; without it a thread has no `interim` posts.
+	 */
+	send?(thread: string, text: string): Promise<InterimMessage>;
+	/** Archives the thread, and locks it when the surface allows. */
+	close(thread: string): Promise<void>;
+}
+
 /**
  * One chat network the host talks through. The host ships Discord's; a plugin may contribute
  * another with `surfaces`. A surface serves the channels whose key starts with its `surface`
@@ -43,6 +77,19 @@ export interface ChatSurface {
 	readonly surface: string;
 	/** Explicit opt-in to delivering OutboundReply.files; absent or false refuses turn attachments. */
 	readonly supportsFiles?: boolean;
+	/**
+	 * Serves a room for each agent and group of the agent team, `<surface>:agent.<name>` and
+	 * `<surface>:group.<name>`: separate conversations from the agents' Discord channels, with
+	 * their own session, held actions and group log, run by the same team. The team replies in a
+	 * room through `sendReply` with `OutboundReply.author`. Absent or false = no rooms.
+	 */
+	readonly agentRooms?: boolean;
+	/**
+	 * Hosts dispatch threads: a background dispatch started in one of this surface's channels
+	 * opens its thread here, and the thread is the conversation `<surface>:<id>`. Absent = the
+	 * dispatch posts in the channel as before.
+	 */
+	readonly threads?: SurfaceThreads;
 	/**
 	 * Short English guidance on how a reply renders here, such as "no Markdown tables", which the
 	 * runtime appends to the system prompt of every turn that replies on this surface, after the
@@ -88,9 +135,30 @@ export interface ChatSurface {
 	prompts?(channel: ChannelKey, scope?: PromptScope): Prompts | undefined;
 	/**
 	 * Where a running turn posts the text it writes before its final answer: ordinary messages it
-	 * may edit in place. Absent, or undefined, = only the final reply is posted.
+	 * may edit in place. `as` names who speaks when an agent of the team does, as `author` does in
+	 * `sendReply`. Absent, or undefined, = only the final reply is posted.
+	 */
+	interim?(channel: ChannelKey, as?: PostAuthor): InterimPosts | undefined;
+	/**
+	 * The content of an attachment this surface made, such as a file the owner uploaded to a room:
+	 * its bytes, or, for a file too large to hold in memory, `{ path }` of a file on the host or a
+	 * stream, which the core stores without buffering the whole. A ref of a message on this
+	 * surface is read here and never fetched over the network; a rejection fails that file. Absent
+	 * = the refs of its messages are downloaded from their URLs.
+	 */
+	readAttachment?(
+		channel: ChannelKey,
+		ref: AttachmentRef,
+	): Promise<AttachmentContent>;
+	/**
+	 * The most bytes of one attachment a turn takes from this surface, for a ref, a file, a stream
+	 * or a download alike; default 25 MiB (`MAX_ATTACHMENT_BYTES`), which Discord keeps. A larger
+	 * file is refused as `larger than <n> MB`; a smaller value than the default is allowed.
+	 * An image over 25 MiB is still not shown to the model, and a text or PDF file over 25 MiB is
+	 * not read by `read_attachment`: both stay in the conversation's store, named in the turn's
+	 * `## Attachments` block, for tools that take files.
 	 */
-	interim?(channel: ChannelKey): InterimPosts | undefined;
+	readonly maxAttachmentBytes?: number;
 	/**
 	 * Shows what a running turn writes and which tools it runs, as it goes, such as a live preview
 	 * in a web chat. Called between the turn's start and its reply; a rejection is logged and the
@@ -123,8 +191,10 @@ export interface SurfacePort {
 		channel: ChannelKey,
 		scope?: PromptScope | Speaker,
 	): Prompts | undefined;
-	/** The channel's interim posts; undefined when its surface has none. */
-	interim(channel: ChannelKey): InterimPosts | undefined;
+	/** The surfaces that serve agent rooms (`agentRooms: true`); read after link. */
+	roomSurfaces(): readonly string[];
+	/** The channel's interim posts, under `as` when given; undefined when its surface has none. */
+	interim(channel: ChannelKey, as?: PostAuthor): InterimPosts | undefined;
 	/**
 	 * Shows a running turn's progress; a no-op when no surface serves the channel or its surface
 	 * shows none. The host's port always has it; it is optional so a port written before 0.8 still

package/src/core/define-roundtable.ts

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { userInfo } from "node:os";
 import { join } from "node:path";
 import { ModelRegistry, ModelRuntime } from "@earendil-works/pi-coding-agent";
-import { agentServerPlugin } from "./builtin/agent-server.ts";
+import { agentServerPlugin, LOCAL_TEAM_ID } from "./builtin/agent-server.ts";
 import { discordPlugin } from "./builtin/discord.ts";
 import { discordAdminPlugin } from "./builtin/discord-admin.ts";
 import { modulesPlugin, schedulerPlugin } from "./builtin/modules.ts";
@@ -13,6 +13,7 @@ import {
 	precheckPlugin,
 	scheduleStorePlugin,
 } from "./builtin/stores.ts";
+import { threadsPlugin } from "./builtin/threads.ts";
 import { workerSessionsPlugin } from "./builtin/worker-sessions.ts";
 import { warnDeprecations } from "./config/access.ts";
 import {
@@ -29,6 +30,7 @@ import { identityPlugin } from "./identity/identity-plugin.ts";
 import { type JudgeModel, piJudgeModel } from "./judging/model-judge.ts";
 import { createLogger, type LogEntry, type Logger } from "./log.ts";
 import { formatModelRef, type ModelRef } from "./models.ts";
+import { modesPlugin } from "./modes/modes-plugin.ts";
 import { ErrorReporter } from "./ops/error-reporter.ts";
 import type { RoundtablePlugin } from "./plugin.ts";
 import {
@@ -132,34 +134,17 @@ export function discordOwnerOf(
 	};
 }
 
-/** The Discord bot and the agent server that lives there, each in its place in the plugin list. */
+/** The Discord bot and its administration, each in its place in the plugin list. */
 interface DiscordAssembly {
 	discord: RoundtablePlugin;
 	admin: RoundtablePlugin[];
-	skills: RoundtablePlugin[];
-	agentServer: RoundtablePlugin;
-	/** Absent when no agent is configured: a plugin that adds nothing is refused by the registry. */
-	seeds?: RoundtablePlugin;
 }
 
 function discordAssembly(
 	config: ResolvedConfig,
 	discord: NonNullable<ResolvedConfig["discord"]>,
-	shared: {
-		modelRuntime: ModelRuntime;
-		agentSessions: AgentSessionsSlot;
-		errorReporter: ErrorReporter | undefined;
-	},
 ): DiscordAssembly {
-	const { name } = config;
 	const owner = discordOwnerOf(config);
-	const sharedPrompt = config.prompts.shared
-		? readPrompt(config.prompts.shared, "prompts.shared")
-		: readPrompt(join(ASSETS, "prompts", "shared.md"), "prompts.shared");
-	const guest = config.prompts.guest
-		? readPrompt(config.prompts.guest, "prompts.guest")
-		: readPrompt(join(ASSETS, "prompts", "shared-guest.md"), "prompts.guest");
-	const { errorReporter } = shared;
 	return {
 		discord: discordPlugin({
 			token: discord.token,
@@ -181,10 +166,43 @@ function discordAssembly(
 			cardCopies: discord.cardCopies,
 		}),
 		admin: discord.admin ? [discordAdminPlugin({ owner })] : [],
+	};
+}
+
+/**
+ * The agent server and what only it uses, each in its place in the plugin list: the skills addon
+ * and the seed agents. Its team lives in the Discord guild when there is one, and otherwise in
+ * the rooms of the surfaces that host them.
+ */
+interface AgentAssembly {
+	skills: RoundtablePlugin[];
+	agentServer: RoundtablePlugin;
+	/** Absent when no agent is configured: a plugin that adds nothing is refused by the registry. */
+	seeds?: RoundtablePlugin;
+}
+
+function agentAssembly(
+	config: ResolvedConfig,
+	shared: {
+		modelRuntime: ModelRuntime;
+		agentSessions: AgentSessionsSlot;
+		errorReporter: ErrorReporter | undefined;
+	},
+): AgentAssembly {
+	const { name, discord } = config;
+	const owner = discordOwnerOf(config);
+	const sharedPrompt = config.prompts.shared
+		? readPrompt(config.prompts.shared, "prompts.shared")
+		: readPrompt(join(ASSETS, "prompts", "shared.md"), "prompts.shared");
+	const guest = config.prompts.guest
+		? readPrompt(config.prompts.guest, "prompts.guest")
+		: readPrompt(join(ASSETS, "prompts", "shared-guest.md"), "prompts.guest");
+	const { errorReporter } = shared;
+	return {
 		skills: config.skills
 			? [
 					skillsPlugin({
-						guildId: discord.guild,
+						guildId: discord?.guild ?? LOCAL_TEAM_ID,
 						reposDir: config.skills.reposDir ?? join(config.dataDir, "repos"),
 						writtenDir: join(config.dataDir, "skills"),
 						builtinDir: config.skills.builtinDir ?? join(ASSETS, "skills"),
@@ -193,8 +211,11 @@ function discordAssembly(
 				]
 			: [],
 		agentServer: agentServerPlugin({
-			guildId: discord.guild,
-			entryChannelId: discord.entryChannel,
+			...(discord
+				? { guildId: discord.guild, entryChannelId: discord.entryChannel }
+				: config.coordinator
+					? { coordinator: config.coordinator }
+					: {}),
 			owner,
 			assistant: name,
 			modelRuntime: shared.modelRuntime,
@@ -206,15 +227,15 @@ function discordAssembly(
 			scratchDir: config.scratchDir,
 			shellUser: userInfo().username,
 			prompts: { shared: sharedPrompt, guest },
-			...(discord.agentMemory ? { memory: discord.agentMemory } : {}),
-			...(discord.agentSpeakers ? { speakers: discord.agentSpeakers } : {}),
-			...(discord.attachmentDownload
+			...(discord?.agentMemory ? { memory: discord.agentMemory } : {}),
+			...(discord?.agentSpeakers ? { speakers: discord.agentSpeakers } : {}),
+			...(discord?.attachmentDownload
 				? { attachmentDownload: discord.attachmentDownload }
 				: {}),
-			avatarListener: "public",
-			// resolveConfig refuses Discord without a public address.
-			avatarUrl: config.http?.publicUrl ?? "",
-			avatarReference: config.avatar ?? join(ASSETS, "neutral.png"),
+			// The pictures are public on the listener only where a public address reaches it.
+			...(config.http ? { avatarListener: "public" } : {}),
+			...(config.http?.publicUrl ? { avatarUrl: config.http.publicUrl } : {}),
+			avatarReference: join(ASSETS, "neutral.png"),
 			avatarNeutral: join(ASSETS, "neutral.png"),
 			// An ops agent's reports are the agent server's to deliver.
 			...(errorReporter && "agent" in errorReporter.destination
@@ -229,9 +250,10 @@ function discordAssembly(
  * The host's options and the plugin list of a configured bot: the built-in plugins in their
  * fixed order (each service one provides is read by the ones after it), then the operator's, then the scheduler, so a due schedule fires only once
  * everything it reaches runs. The memory, Discord administration, and skills addons are left out
- * when the configuration switches them off. Without `discord` the Discord plugins, the skills,
- * the agent server and its seeds are left out, and the runtime still runs every turn of
- * `context.turns`. Configuration mistakes stop here, naming the key and the fix.
+ * when the configuration switches them off. Without `discord` the Discord plugins are left out,
+ * and the skills, the agent server and its seeds stay only when `agents` are configured: their
+ * team then lives in the rooms of the surfaces that host them, and the runtime still runs every
+ * turn of `context.turns`. Configuration mistakes stop here, naming the key and the fix.
  */
 export async function defineRoundtable(
 	input: RoundtableConfig,
@@ -271,13 +293,12 @@ export async function defineRoundtable(
 	warnDeprecations(logger, config.deprecations);
 	// The agent server hands the runtime its per-agent settings once it sets up.
 	const agentSessions = agentSessionsSlot();
-	const assembly = discord
-		? discordAssembly(config, discord, {
-				modelRuntime,
-				agentSessions,
-				errorReporter,
-			})
-		: undefined;
+	const assembly = discord ? discordAssembly(config, discord) : undefined;
+	// The agent server runs with Discord, and without it whenever agents are configured.
+	const agentTeam =
+		discord || config.agents.length > 0
+			? agentAssembly(config, { modelRuntime, agentSessions, errorReporter })
+			: undefined;
 	return {
 		options: {
 			logger,
@@ -309,6 +330,8 @@ export async function defineRoundtable(
 			...(config.memory ? [memoryPlugin({ owner })] : []),
 			scheduleStorePlugin(),
 			precheckPlugin(),
+			// Before Discord, whose services hand out its instance, and the modules and agent server that use it.
+			threadsPlugin({ dataDir: config.dataDir }),
 			...(assembly ? [assembly.discord] : []),
 			modulesPlugin({
 				owner,
@@ -330,8 +353,9 @@ export async function defineRoundtable(
 				delegation: config.delegation,
 			}),
 			...(assembly?.admin ?? []),
-			...(assembly?.skills ?? []),
+			...(agentTeam?.skills ?? []),
 			conversationsPlugin(),
+			modesPlugin(),
 			runtimePlugin({
 				owner,
 				modelRuntime,
@@ -344,11 +368,15 @@ export async function defineRoundtable(
 				agents: agentSessions,
 				interimText: config.interimText,
 				interimPrimaryChars: config.interimPrimaryChars,
+				turnTimeoutMs: config.turnLimits.timeoutMs,
+				turnMaxMs: config.turnLimits.maxMs,
+				turnTimeoutCardMs: config.turnLimits.cardMs,
+				autonomy: config.autonomy,
 				memory: config.memory,
 				...(crowd ? { crowd } : {}),
 			}),
-			...(assembly
-				? [assembly.agentServer, ...(assembly.seeds ? [assembly.seeds] : [])]
+			...(agentTeam
+				? [agentTeam.agentServer, ...(agentTeam.seeds ? [agentTeam.seeds] : [])]
 				: []),
 			...config.plugins,
 			schedulerPlugin(),