pi-roundtable 0.26.3 → 0.27.1

package/src/core/agents/group-turns.ts

@@ -1,6 +1,7 @@
 import type { TurnAttachments } from "../domain/attachment.ts";
-import type { ChannelKey } from "../domain/conversation.ts";
+import type { ChannelKey, TurnResult } from "../domain/conversation.ts";
 import { AgentError } from "../domain/errors.ts";
+import type { RoundEnd, RoundProgress } from "../domain/round.ts";
 import { messages } from "../i18n/index.ts";
 import type { Speaker } from "../speakers.ts";
 import { groupTurnText } from "./agent-prompt.ts";
@@ -24,14 +25,45 @@ import {
 	type TurnHost,
 } from "./team-turn-types.ts";
 
+/** A running round, as Stop reaches it: the flag it ends on, and the sessions whose turns it is running. */
+interface RunningRound {
+	stopped: boolean;
+	sessions: Set<ChannelKey>;
+}
+
 /** A group channel's rounds: scoring, then the chosen members answer one at a time. */
 export class GroupTurns {
 	readonly #host: TurnHost;
+	/** The round each channel runs now; a channel runs one at a time, inside its queue. */
+	readonly #running = new Map<ChannelKey, RunningRound>();
 
 	constructor(host: TurnHost) {
 		this.#host = host;
 	}
 
+	/** Tells the channel's surface where the round stands; a surface that shows no rounds hears nothing, and a refusal only reaches the log. */
+	#tell(channel: ChannelKey, round: RoundProgress): void {
+		const { surfaces, logger } = this.#host.options;
+		// pi-lens-ignore: no-unknown-parameters — a rejection reason is unknown; it only reaches the logger
+		surfaces
+			?.groupRound?.(channel, round)
+			.catch((error: unknown) =>
+				logger.warn({ channel, err: error }, "round not shown"),
+			);
+	}
+
+	/**
+	 * Ends the channel's running round: the member speaking is stopped, and the members still waiting
+	 * do not speak. Returns the sessions whose turns the caller must stop, or undefined when no round runs
+	 * in the channel.
+	 */
+	stopRound(channel: ChannelKey): ChannelKey[] | undefined {
+		const round = this.#running.get(channel);
+		if (!round) return undefined;
+		round.stopped = true;
+		return [...round.sessions];
+	}
+
 	/** The active group whose Discord channel or room the key is. */
 	#groupOf(channel: ChannelKey): AgentGroup {
 		const { store, surfaces } = this.#host.options;
@@ -63,7 +95,7 @@ export class GroupTurns {
 			.map((name) => store.agent(name))
 			.filter((m): m is Agent => m?.status === "active");
 		const recent = await store.recentGroupMessages(log, RECENT_FOR_SCORING);
-		await store.appendGroupMessage(log, {
+		const openedBy = await store.appendGroupMessage(log, {
 			author: speaker.tier === "owner" ? "owner" : `human:${speaker.id}`,
 			authorName:
 				speaker.tier === "owner" ? this.#host.options.owner.name : speaker.name,
@@ -103,48 +135,107 @@ export class GroupTurns {
 		const chain: Chain = { messages: 0, speaker };
 		const queued = [...order];
 		const spoken = new Set<string>();
+		const control: RunningRound = { stopped: false, sessions: new Set() };
+		this.#running.set(channel, control);
+		// The stop button belongs to the round, which ends whole: it is shown until the round ends.
+		const hideStop = this.#host.options.showStop(channel);
+		const share = (
+			state: RoundProgress["state"],
+			current: string | undefined,
+			ended?: RoundEnd,
+		) => {
+			// The owner's messages waiting in the channel's queue, not counting this round's own task.
+			const waiting = Math.max(this.#host.options.queue.size(channel) - 1, 0);
+			this.#tell(channel, {
+				id: openedBy,
+				state,
+				...(current === undefined ? {} : { current }),
+				next: [...queued],
+				spoken: [...spoken],
+				replies,
+				limit: MAX_ROUND_REPLIES,
+				...(ended === undefined ? {} : { ended }),
+				...(waiting > 0 ? { queued: waiting } : {}),
+			});
+		};
 		let last: Agent | undefined;
 		let replies = 0;
-		while (queued.length > 0 && replies < MAX_ROUND_REPLIES) {
-			// A member may archive the group during the round.
-			if (store.group(group.name)?.status !== "active") return;
-			const name = queued.shift() as string;
-			const member = store.agent(name);
-			if (member?.status !== "active") continue;
-			const first = !spoken.has(name);
-			spoken.add(name);
-			const backlog = await store.backlog(log, name, BACKLOG_LIMIT);
-			// Delivered once the session has the text, so a message never comes twice.
-			if (backlog.lastId !== undefined)
-				await store.advanceCursor(log, name, backlog.lastId);
-			// Attachments and a confirmation belong to a member's first turn of the round only.
-			const extra: TurnExtra = { interactive: true, byMessage: true };
-			if (first) {
-				extra.attachments = attachments;
-				if (approvals.get(name)) extra.confirmed = true;
+		let end: RoundEnd = "done";
+		try {
+			share("running", undefined);
+			while (queued.length > 0 && replies < MAX_ROUND_REPLIES) {
+				if (control.stopped) {
+					end = "stopped";
+					break;
+				}
+				// A member may archive the group during the round.
+				if (store.group(group.name)?.status !== "active") {
+					queued.length = 0;
+					break;
+				}
+				const name = queued.shift() as string;
+				const member = store.agent(name);
+				if (member?.status !== "active") continue;
+				const first = !spoken.has(name);
+				const backlog = await store.backlog(log, name, BACKLOG_LIMIT);
+				// Delivered once the session has the text, so a message never comes twice.
+				if (backlog.lastId !== undefined)
+					await store.advanceCursor(log, name, backlog.lastId);
+				// Attachments and a confirmation belong to a member's first turn of the round only.
+				const extra: TurnExtra = { interactive: true, byMessage: true };
+				if (first) {
+					extra.attachments = attachments;
+					if (approvals.get(name)) extra.confirmed = true;
+				}
+				const scope = groupScope(member, group, channel);
+				control.sessions.add(scope.session);
+				share("running", name);
+				let result: TurnResult;
+				try {
+					result = await this.#host.turn(
+						member,
+						scope,
+						channel,
+						groupTurnText(group, member, backlog),
+						chain,
+						extra,
+					);
+				} finally {
+					control.sessions.delete(scope.session);
+				}
+				spoken.add(name);
+				replies += 1;
+				last = member;
+				if (control.stopped || (!result.ok && result.stopped)) {
+					end = "stopped";
+					break;
+				}
+				if (result.ok) {
+					await store.appendGroupMessage(log, {
+						author: name,
+						authorName: this.#host.current(member).displayName,
+						text: result.text,
+					});
+					for (const handoff of mentionedMembers(result.text, members))
+						if (handoff !== name && !queued.includes(handoff))
+							queued.push(handoff);
+				}
+				share("running", undefined);
 			}
-			const result = await this.#host.turn(
-				member,
-				groupScope(member, group, channel),
-				channel,
-				groupTurnText(group, member, backlog),
-				chain,
-				extra,
-			);
-			replies += 1;
-			last = member;
-			if (!result.ok) continue;
-			await store.appendGroupMessage(log, {
-				author: name,
-				authorName: this.#host.current(member).displayName,
-				text: result.text,
-			});
-			for (const handoff of mentionedMembers(result.text, members))
-				if (handoff !== name && !queued.includes(handoff)) queued.push(handoff);
+			if (end !== "stopped" && queued.length > 0) end = "limit";
+			if (queued.length > 0 && last)
+				await this.#host.post(channel, this.#host.current(last), {
+					chunks: [
+						end === "stopped"
+							? messages().roundStoppedNotice
+							: messages().roundLimitNotice,
+					],
+				});
+			if (end === "stopped") queued.length = 0;
+		} finally {
+			hideStop();
+			this.#running.delete(channel);
+			share("ended", undefined, end);
 		}
-		if (queued.length > 0 && last)
-			await this.#host.post(channel, this.#host.current(last), {
-				chunks: [messages().roundLimitNotice],
-			});
 	}
 }

package/src/core/agents/helper-create.ts

@@ -0,0 +1,180 @@
+import type { CharacterInput } from "../../characters/index.ts";
+import { helpersOf } from "../config/helpers.ts";
+import { AgentError } from "../domain/errors.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
+import type { Speaker } from "../speakers.ts";
+import { toolTiers } from "../tool-tiers.ts";
+import { isHelper } from "./agent-rules.ts";
+import type { Agent } from "./agent-store.ts";
+import { keysOf } from "./team-keys.ts";
+import type { TeamContext } from "./team-options.ts";
+
+/** The team's way of making an agent, which `createHelper` uses to make a temp knight. */
+export type MakeAgent = (
+	who: {
+		speaker: Speaker;
+		by: string;
+		creator: Agent;
+		parent: Agent;
+		/** The conversation the temp knight is made from; only it and the owners may message the temp knight. */
+		origin?: string;
+	},
+	fields: {
+		name: string;
+		displayName: string;
+		prompt: string;
+		character?: CharacterInput;
+		skills?: string[];
+	},
+	settings: { model?: string | undefined; thinking?: string | undefined },
+) => Promise<{ agent: Agent; text: string }>;
+
+/**
+ * The agent tool: a knight makes a temp knight for one task. It is a real agent with its own
+ * prompt, picture and place (a thread of the parent's channel on Discord, a room on the web),
+ * that runs the parent's model unless told otherwise. The task goes to it as a message from the
+ * caller, so the answer comes back to the caller's conversation as a new turn. At a cap the
+ * caller's oldest finished temp knight is archived to make room; with none finished, it refuses.
+ */
+export async function createHelper(
+	ctx: TeamContext,
+	make: MakeAgent,
+	caller: AgentTurnScope,
+	input: {
+		name?: string;
+		displayName: string;
+		prompt: string;
+		task: string;
+		character?: CharacterInput;
+		skills?: string[];
+		model?: string;
+		thinking?: string;
+	},
+): Promise<string> {
+	const { store, logger } = ctx.options;
+	const limits = helpersOf(ctx.options.helpers);
+	if (!limits)
+		throw new AgentError("Temp knights are switched off on this host.");
+	const speaker = ctx.turns.speakerOf(caller);
+	if (!speaker)
+		throw new AgentError(
+			"helper_create can only be used during an agent turn.",
+		);
+	const parent = store.activeAgent(caller.name);
+	if (isHelper(parent))
+		throw new AgentError(
+			`You are a temp knight of "${parent.parent}" and cannot make temp knights; ask it to.`,
+		);
+	const { task, name: given, model, thinking, ...rest } = input;
+	// A temp knight never gets more than its parent unless the speaker could grant it by hand.
+	const tiers = ctx.options.toolTiers ?? toolTiers();
+	if (!tiers.allows(speaker.tier, "agent_update") && (model || thinking))
+		throw new AgentError(
+			"A temp knight runs your model and thinking level; choosing others needs a higher tier.",
+		);
+	if (rest.skills?.length && !tiers.allows(speaker.tier, "agent_skills")) {
+		const own = new Set(ctx.options.skills?.carriedNames(parent.name) ?? []);
+		const extra = rest.skills.filter((skill) => !own.has(skill));
+		if (extra.length > 0)
+			throw new AgentError(
+				`A temp knight can carry only skills you carry; not allowed: ${extra.join(", ")}.`,
+			);
+	}
+	const name = given ?? nextName(ctx, parent.name);
+	// Everything that can be refused is checked before anything is made or archived.
+	store.checkNewName(name);
+	const said = await makeRoom(ctx, parent, limits);
+	const made = await make(
+		{
+			speaker,
+			by: caller.name,
+			creator: parent,
+			parent,
+			origin: ctx.turns.turnChannel(caller),
+		},
+		{ ...rest, name },
+		{ model, thinking },
+	);
+	const helper = made.agent;
+	try {
+		await inheritLongRunning(ctx, caller, speaker, helper);
+		ctx.turns.message(caller, helper.name, task);
+	} catch (error) {
+		// The long-running mode or the task could not be handed over (a chain at its cap): the temp
+		// knight is not left idle, and its thread is closed.
+		await ctx.archiveHelpers([helper.name]);
+		throw error;
+	}
+	logger.info(
+		{ agent: helper.name, parent: parent.name },
+		"temp knight created",
+	);
+	return `Created "${helper.displayName}" (${helper.name}); it is working on the task and will answer here.${said}`;
+}
+
+/** The next `<parent>-<n>` no agent or group holds, with the parent cut to leave room for the number. */
+function nextName(ctx: TeamContext, parent: string): string {
+	const { store } = ctx.options;
+	const base = parent.slice(0, 26);
+	for (let n = 1; n < 100_000; n += 1) {
+		const name = `${base}-${n}`;
+		if (!store.agent(name) && !store.group(name)) return name;
+	}
+	throw new AgentError(`No free name for a temp knight of "${parent}".`);
+}
+
+/**
+ * Holds the caps: when the parent or the host is full, archives the parent's oldest finished temp
+ * knight and says so; with none finished, refuses and says what to wait for.
+ */
+async function makeRoom(
+	ctx: TeamContext,
+	parent: Agent,
+	limits: { perParent: number; perHost: number },
+): Promise<string> {
+	const { store } = ctx.options;
+	const mine = store.helpersOf(parent.name, "active");
+	const onHost = store
+		.agents()
+		.filter((agent) => isHelper(agent) && agent.status === "active").length;
+	const full =
+		mine.length >= limits.perParent
+			? `${mine.length} temp knights of yours are still working`
+			: onHost >= limits.perHost
+				? `The host's ${onHost} temp knights are all in use`
+				: undefined;
+	if (!full) return "";
+	const oldest = mine
+		.filter((agent) => agent.finishedAt !== undefined)
+		.sort(
+			(a, b) =>
+				(a.finishedAt as Date).getTime() - (b.finishedAt as Date).getTime(),
+		)[0];
+	if (!oldest)
+		throw new AgentError(
+			`${full}, and none is finished; end one with helper_end or wait for one to finish.`,
+		);
+	await ctx.archiveHelpers([oldest.name]);
+	return ` To make room, "${oldest.displayName}" (${oldest.name}), your oldest finished temp knight, was archived.`;
+}
+
+/**
+ * Turns long-running on for the temp knight's conversations when the conversation that asked for
+ * it has it on, so it works as long as its parent may. This adds no permission: an owner turned
+ * it on there. Only a turn of an owner can carry that over, as for any change of modes.
+ */
+async function inheritLongRunning(
+	ctx: TeamContext,
+	caller: AgentTurnScope,
+	speaker: Speaker,
+	helper: Agent,
+): Promise<void> {
+	const { store, surfaces } = ctx.options;
+	const modes = ctx.options.modes?.();
+	if (!modes?.peek(ctx.turns.turnChannel(caller)).longRunning) return;
+	if (speaker.tier !== "owner" || speaker.principalId === SYSTEM_PRINCIPAL)
+		return;
+	for (const key of keysOf(store, helper.name, surfaces?.roomSurfaces() ?? []))
+		await modes.set(key, { longRunning: true }, speaker);
+}

package/src/core/agents/helper-ops.ts

@@ -0,0 +1,33 @@
+import type { Agent } from "./agent-rules.ts";
+
+/** A knight cleared its own temp knights with `helper_end`. */
+export interface HelpersEnded {
+	/** The knight that ended them. */
+	parent: string;
+	/** The temp knights archived, by name. */
+	names: string[];
+}
+
+/** What the agent team offers for temp knights: the helpers a knight made for a task. */
+export interface HelperTeam {
+	/** The active temp knights a knight made, in the order they were made. */
+	helpersOf(parent: string): Agent[];
+	/**
+	 * The active temp knights that are finished (nothing runs, queued or waits for the owner), of
+	 * the named parents or, with none named, of every knight.
+	 */
+	finishedHelpers(parents?: readonly string[]): Agent[];
+	/**
+	 * Archives temp knights like `archive`, each keeping its history, and closes their Discord
+	 * threads; a name that is no active temp knight is passed over. `by` is who asks, for the log.
+	 * Says which were archived.
+	 */
+	archiveHelpers(names: readonly string[], by: string): Promise<string[]>;
+	/**
+	 * Restores archived temp knights, the undo of `archiveHelpers`: only a name that is still an
+	 * archived temp knight of an active parent is restored. Says which were.
+	 */
+	restoreHelpers(names: readonly string[]): Promise<string[]>;
+	/** Called when a knight clears its own temp knights with `helper_end`; not for an owner's or the host's clearing. */
+	onHelpersEnded(listener: (event: HelpersEnded) => void): void;
+}

package/src/core/agents/helper-test-kit.ts

@@ -0,0 +1,72 @@
+import { NO_ATTACHMENTS } from "../domain/attachment.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import type { Speaker } from "../speakers.ts";
+import { OWNER_SPEAKER } from "../testing/owner.ts";
+import { agentChannel, fx, settle } from "./agent-team-fixture.ts";
+
+export { settle };
+
+export const SCOUT = {
+	displayName: "Scout One",
+	prompt: "You look one thing up.",
+	task: "Look up the first paper.",
+};
+
+/** The scope of an agent's turn in its own Discord channel. */
+export const scopeOf = (name: string): AgentTurnScope => ({
+	name,
+	session: agentChannel(name),
+	home: agentChannel(name),
+});
+
+/** The owner's message to an agent, answered in its own place through the channel's queue. */
+export const writeTo = (name: string, text: string) =>
+	fx.queue.run(agentChannel(name), () =>
+		fx.team.answerOwner(
+			agentChannel(name),
+			OWNER_SPEAKER,
+			text,
+			text,
+			NO_ATTACHMENTS,
+		),
+	);
+
+/**
+ * Runs `action` during the next turn of the agent `name` in its own place, as the model calls a
+ * tool, after the work already running has settled, and waits for what the action started.
+ */
+export async function inTurn<T>(
+	name: string,
+	action: (caller: AgentTurnScope) => Promise<T>,
+	speaker: Speaker = OWNER_SPEAKER,
+	via: string = name,
+): Promise<T> {
+	await settle();
+	let outcome: { value: T } | { error: unknown } | undefined;
+	fx.runtime.during = async (request) => {
+		if (request.agent?.name !== name) return;
+		fx.runtime.during = undefined;
+		outcome = await action(scopeOf(name)).then(
+			(value) => ({ value }),
+			(error: unknown) => ({ error }),
+		);
+	};
+	// Through the channel's queue, as the host runs it, so what the turn starts waits for its end.
+	await fx.queue.run(agentChannel(via), () =>
+		fx.team.answerOwner(agentChannel(via), speaker, "go", "go", NO_ATTACHMENTS),
+	);
+	fx.runtime.during = undefined;
+	await settle();
+	if (!outcome) throw new Error(`no turn of ${name} ran the action`);
+	if ("error" in outcome) throw outcome.error;
+	return outcome.value;
+}
+
+/** Runs `action` inside the coordinator's turn. */
+export const asCoordinator = <T>(
+	action: (caller: AgentTurnScope) => Promise<T>,
+) => inTurn("coordinator", action);
+
+/** The text of every turn the runtime ran, by the agent that ran it. */
+export const turnsOf = (name: string) =>
+	fx.runtime.turns.filter((turn) => turn.agent?.name === name);

package/src/core/agents/helper-tools.ts

@@ -0,0 +1,104 @@
+import { Type } from "typebox";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import { THINKING_LEVELS } from "../models.ts";
+import {
+	optionalString,
+	requiredString,
+	stringList,
+	type TextToolDef,
+} from "../runtime/text-tools.ts";
+import { CLASS, COLOR, DISPLAY, lookOf, PROMPT } from "./agent-tool-schema.ts";
+import type { AgentOps } from "./agent-tools.ts";
+
+/** The tools that make and end a knight's temp knights. */
+export function helperToolDefs(
+	ops: AgentOps,
+	scope: AgentTurnScope,
+	skillsOn: boolean,
+): TextToolDef<"helper_create" | "helper_end">[] {
+	return [
+		{
+			name: "helper_create",
+			label: "Create temp knight",
+			description: `Make a temp knight (a helper knight) for one self-contained task that can run on its own, such as one of several things to look up or compare. It is a real agent with its own picture and place, listed under you; it starts at once and its answer comes back to you here as a new turn, like message_agent's. Make one per task, then end your turn; when the answers are in, merge them and clear the ones that are done with helper_end. It runs your model unless you give one, cannot make knights, temp knights or groups, and has no schedules. You may have a few at once, and when you are at the limit your oldest finished one is archived to make room.`,
+			parameters: Type.Object({
+				display_name: DISPLAY,
+				prompt: PROMPT,
+				task: Type.String({
+					minLength: 1,
+					maxLength: 4000,
+					description:
+						"The task, self-contained: what to do, what to read, and what to answer with.",
+				}),
+				name: Type.Optional(
+					Type.String({
+						pattern: "^[a-z0-9-]{1,32}$",
+						description:
+							"Permanent name: lowercase letters, digits, and dashes. Left out, it is <your name>-<number>.",
+					}),
+				),
+				class: Type.Optional(CLASS),
+				color: Type.Optional(COLOR),
+				model: Type.Optional(
+					Type.String({
+						description:
+							"The model to run on, as <provider>/<model>; left out, yours. An unusable one is refused with the usable list.",
+					}),
+				),
+				thinking: Type.Optional(
+					Type.Union(
+						[...THINKING_LEVELS, "default"].map((level) => Type.Literal(level)),
+						{ description: "Its thinking level; left out, yours." },
+					),
+				),
+				...(skillsOn
+					? {
+							skills: Type.Optional(
+								Type.Array(Type.String(), {
+									description:
+										"Skills it carries, from skill_list; pick those the task needs.",
+								}),
+							),
+						}
+					: {}),
+			}),
+			run: (i) => {
+				const name = optionalString(i, "name");
+				const model = optionalString(i, "model");
+				const thinking = optionalString(i, "thinking");
+				const skills = stringList(i, "skills");
+				const look = lookOf(i);
+				return ops.helperCreate(scope, {
+					displayName: requiredString(i, "display_name"),
+					prompt: requiredString(i, "prompt"),
+					task: requiredString(i, "task"),
+					...(name ? { name } : {}),
+					...(Object.keys(look).length > 0 ? { character: look } : {}),
+					...(model ? { model } : {}),
+					...(thinking ? { thinking } : {}),
+					...(skills && skills.length > 0 ? { skills } : {}),
+				});
+			},
+		},
+		{
+			name: "helper_end",
+			label: "End temp knights",
+			description:
+				'Archive your own temp knights when you are done with them: the names you list, or "finished" for every one that has finished. Their history stays readable under the archive, and the owner can restore them. You cannot end anyone else\'s.',
+			parameters: Type.Object({
+				names: Type.Union(
+					[
+						Type.Array(Type.String(), { minItems: 1, maxItems: 50 }),
+						Type.Literal("finished"),
+					],
+					{ description: 'Their names, or "finished" for every finished one.' },
+				),
+			}),
+			run: (i) =>
+				ops.helperEnd(
+					scope,
+					i.names === "finished" ? "finished" : (stringList(i, "names") ?? []),
+				),
+		},
+	];
+}