pi-roundtable 0.27.1 → 0.29.0

package/src/core/agents/agent-messages.ts

@@ -1,9 +1,9 @@
-import type { ChannelKey } from "../domain/conversation.ts";
+import type { ChannelKey, IntercomCard } from "../domain/conversation.ts";
 import { AgentError, IdentityError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
 import { HostStoppingError } from "../errors.ts";
-import { messages } from "../i18n/index.ts";
 import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
+import { intercomPlain } from "../presentation/intercom.ts";
 import { isQuiet } from "../presentation/reply-body.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
 import { addressee, type Speaker } from "../speakers.ts";
@@ -14,14 +14,13 @@ import {
 	agentReplyText,
 	chainLimitReason,
 	deliveredMessagePost,
-	returnedAnswerPost,
 } from "./agent-prompt.ts";
+import { answersTo } from "./agent-rules.ts";
 import type { Agent } from "./agent-store.ts";
 import { conversationLabel, messageTarget } from "./message-target.ts";
 import { discordIdOf, discordKey, scopeOf } from "./team-keys.ts";
 import {
 	type Chain,
-	type Exchange,
 	MAX_CHAIN_MESSAGES,
 	type TurnHost,
 } from "./team-turn-types.ts";
@@ -80,35 +79,25 @@ export class AgentMessages {
 			);
 		// A temp knight talks only to the conversation it was made from (and to the owners), so one
 		// person's helper session is not open to another person's turn.
-		if (target.parent !== undefined && chain.speaker.tier !== "owner") {
-			const own = sender.name === target.parent && target.origin === parent;
-			if (!own)
-				throw new AgentError(
-					`"${target.name}" is a temp knight of "${target.parent}" and answers only the conversation that made it; ask "${target.parent}" there.`,
-				);
-		}
+		if (!answersTo(target, caller.name, parent, chain.speaker))
+			throw new AgentError(
+				`"${target.name}" is a temp knight of "${target.parent}" and answers only the conversation that made it; ask "${target.parent}" there.`,
+			);
 		chain.messages += 1;
 		// A temp knight is working from the moment a message is handed to it until it has answered.
 		this.#host.helpers.begin(target.name);
-		// The thread opens in the sender's turn channel, on its surface when that hosts threads; a
-		// surface that hosts none leaves the answer returning to the sender's conversation.
-		const exchange = this.#openExchange(parent, sender, target, text);
+		// The request shows in the sender's turn channel as a small card under the sender's name.
+		this.#card(parent, sender, {
+			kind: "sent",
+			peer: this.#peer(target),
+			text,
+		});
 		void queue
 			.run(targetChannel, async () =>
-				this.#deliver(
-					sender,
-					target,
-					text,
-					chain,
-					await exchange,
-					targetChannel,
-					parent,
-				),
+				this.#exchange(sender, target, text, chain, targetChannel, parent),
 			)
 			.catch((error: unknown) => {
 				if (error instanceof HostStoppingError) {
-					// Refused before it started: the thread it opened has nothing more to hold.
-					void exchange.then((opened) => opened?.thread.close());
 					this.#keep({
 						kind: "message",
 						sender: sender.name,
@@ -139,69 +128,36 @@ export class AgentMessages {
 		return `Sent to "${target.displayName}" in its ${conversationLabel(targetChannel)}. It works there; its answer comes back to you as a new turn.`;
 	}
 
+	/** The other agent of a card, as it is named now. */
+	#peer(agent: Agent): IntercomCard["peer"] {
+		const current = this.#host.current(agent);
+		return { name: current.name, displayName: current.displayName };
+	}
+
 	/**
-	 * Opens the message's thread in the sender's turn channel, a Discord channel or a room, and
-	 * posts the request there under the sender's name; undefined where no thread opens. Never
-	 * rejects.
+	 * Posts a card of the exchange in the channel under `as`'s name: the card where the channel's
+	 * surface shows cards, and its heading and text where it shows none. Never rejects.
 	 */
-	async #openExchange(
-		parent: ChannelKey,
-		sender: Agent,
-		target: Agent,
-		text: string,
-	): Promise<Exchange | undefined> {
-		const thread = await this.#host.options.threads?.open(
-			parent,
-			`→ ${target.displayName}`,
-		);
-		if (!thread) return undefined;
-		await this.#host
-			.post(parent, this.#host.current(sender), {
-				chunks: splitReply(
-					deliveredMessagePost(this.#host.current(target), text),
-				),
-				threadId: thread.id,
+	#card(channel: ChannelKey, as: Agent, card: IntercomCard): Promise<void> {
+		return this.#host
+			.post(channel, this.#host.current(as), {
+				chunks: splitReply(intercomPlain(card)),
+				intercom: card,
 			})
 			.catch((error: unknown) =>
 				this.#host.options.logger.warn(
-					{ err: error },
-					"agent request not threaded",
+					{ channel, kind: card.kind, err: error },
+					"agent message card not posted",
 				),
 			);
-		return { parent, thread };
-	}
-
-	/** Runs the target's turn, then posts its answer and wakes the sender; closes the thread either way. */
-	async #deliver(
-		sender: Agent,
-		target: Agent,
-		text: string,
-		chain: Chain,
-		exchange: Exchange | undefined,
-		targetChannel: ChannelKey,
-		senderChannel: ChannelKey,
-	): Promise<void> {
-		try {
-			await this.#exchange(
-				sender,
-				target,
-				text,
-				chain,
-				exchange,
-				targetChannel,
-				senderChannel,
-			);
-		} finally {
-			await exchange?.thread.close();
-		}
 	}
 
+	/** Runs the target's turn, then shows its answer in the sender's channel and wakes the sender. */
 	async #exchange(
 		sender: Agent,
 		target: Agent,
 		text: string,
 		chain: Chain,
-		exchange: Exchange | undefined,
 		targetChannel: ChannelKey,
 		senderChannel: ChannelKey,
 	): Promise<void> {
@@ -223,9 +179,6 @@ export class AgentMessages {
 			chain,
 			{ unattended: true },
 		);
-		const thread = exchange?.thread;
-		if (thread && !result.ok)
-			await thread.close(messages().agentNoReply(result.error.message));
 		// A target with nothing to answer sends nothing back and wakes nobody.
 		if (isQuiet(result)) {
 			logger.info(
@@ -236,29 +189,22 @@ export class AgentMessages {
 		}
 		const current = this.#host.options.store.agent(sender.name);
 		if (current?.status !== "active") return;
-		// With a thread the answer goes there, leaving the sender's channel its own reply.
-		if (result.ok)
-			await this.#host
-				.post(senderChannel, this.#host.current(target), {
-					chunks: splitReply(returnedAnswerPost(result.text)),
-					...(thread ? { threadId: thread.id } : {}),
-				})
-				.catch((error: unknown) =>
-					logger.error({ err: error }, "agent answer not posted back"),
-				);
-		await thread?.close();
+		// The answer, or why none came, shows in the sender's channel as a small card.
+		await this.#card(senderChannel, target, {
+			kind: result.ok ? "answered" : "failed",
+			peer: this.#peer(target),
+			text: result.ok ? result.text : result.error.message,
+		});
 		const followUp = result.ok
 			? agentReplyText(
 					addressee(chain.speaker, this.#host.options.owner),
 					this.#host.current(target),
 					result.text,
-					thread?.mention,
 				)
 			: agentFailureText(
 					addressee(chain.speaker, this.#host.options.owner),
 					this.#host.current(target),
 					result.error.message,
-					thread?.mention,
 				);
 		// The answer is a report back to the sender, so its turn may ask the owner on cards.
 		void queue
@@ -407,7 +353,7 @@ export class AgentMessages {
 			await this.#followUp(sender, entry.channel, entry.text, chain);
 			return;
 		}
-		// Its thread was closed when the host refused it, so the answer returns to the sender's conversation.
+		// Its request card was posted when it was sent; the answer's card follows as it would have.
 		this.#host.helpers.begin(target.name);
 		try {
 			await this.#exchange(
@@ -415,7 +361,6 @@ export class AgentMessages {
 				target,
 				entry.text,
 				chain,
-				undefined,
 				entry.channel,
 				origin,
 			);

package/src/core/agents/agent-ports.ts

@@ -1,4 +1,5 @@
 import type { AgentRuntime, ContextUse } from "../contract/runtime.ts";
+import type { IntercomCard } from "../domain/conversation.ts";
 import type { InterimPosts } from "../domain/interim.ts";
 import type { ThinkingSetting } from "../models.ts";
 
@@ -24,6 +25,8 @@ export interface AgentPost {
 	files?: { name: string; data: Uint8Array }[];
 	/** A thread of the channel to post in instead, such as a dispatch's. */
 	threadId?: string;
+	/** A message between agents, shown as a small card in place of `chunks` where the channel can. */
+	intercom?: IntercomCard;
 }
 
 /**

package/src/core/agents/agent-prompt.ts

@@ -134,16 +134,8 @@ export function agentReplyText(
 	who: OwnerIdentity,
 	from: Agent,
 	text: string,
-	thread?: string,
 ): string {
-	return `(The agent "${from.displayName}" (\`${from.name}\`) answered your message. Continue with it and tell ${who.name} what matters; your reply is posted in your channel.${threadNote(thread)})\n\n${text}`;
-}
-
-/** Where the exchange was posted, when it had a thread. */
-function threadNote(thread: string | undefined): string {
-	return thread
-		? ` The exchange is in the thread ${thread}, now archived; link it when useful.`
-		: "";
+	return `(The agent "${from.displayName}" (\`${from.name}\`) answered your message. Continue with it and tell ${who.name} what matters; your reply is posted in your channel.)\n\n${text}`;
 }
 
 /** What the sender receives when the target could not answer. */
@@ -151,9 +143,8 @@ export function agentFailureText(
 	who: OwnerIdentity,
 	from: Agent,
 	reason: string,
-	thread?: string,
 ): string {
-	return `(The agent "${from.displayName}" (\`${from.name}\`) could not answer your message: ${reason}. Tell ${who.name} briefly, or try again later.${threadNote(thread)})`;
+	return `(The agent "${from.displayName}" (\`${from.name}\`) could not answer your message: ${reason}. Tell ${who.name} briefly, or try again later.)`;
 }
 
 /** A new agent's first turn. */
@@ -192,11 +183,6 @@ export function deliveredMessagePost(to: Agent, text: string): string {
 	return messages().messageDelivered(to.displayName, text);
 }
 
-/** How the target's answer appears in the sender's channel. */
-export function returnedAnswerPost(text: string): string {
-	return messages().answerReturned(text);
-}
-
 /** Why a chain of agent messages stops without the owner in between. */
 export function chainLimitReason(who: OwnerIdentity): string {
 	const o = ownerWords(who);

package/src/core/agents/agent-rules.ts

@@ -42,6 +42,33 @@ export interface Agent {
 export const isHelper = (agent: Pick<Agent, "parent"> | undefined): boolean =>
 	agent?.parent !== undefined;
 
+/**
+ * Whether `sender`, writing from `from` in a run `speaker` started, may message `target`: a temp
+ * knight answers only its knight in the conversation that made it, and the owners.
+ */
+export const answersTo = (
+	target: Pick<Agent, "parent" | "origin">,
+	sender: string,
+	from: string,
+	speaker: { tier: string },
+): boolean =>
+	target.parent === undefined ||
+	speaker.tier === "owner" ||
+	(sender === target.parent && target.origin === from);
+
+/**
+ * The surface a temp knight was made on, such as "discord" or the web app's, read off its origin;
+ * undefined for a permanent knight and for a temp knight made before the origin was kept. A temp
+ * knight lives on that surface; its place on another is made only when someone uses it there.
+ */
+export const helperSurface = (
+	agent: Pick<Agent, "parent" | "origin"> | undefined,
+): string | undefined => {
+	const origin = agent?.parent === undefined ? undefined : agent.origin;
+	const colon = origin?.indexOf(":") ?? -1;
+	return origin && colon > 0 ? origin.slice(0, colon) : undefined;
+};
+
 export interface AgentGroup {
 	name: string;
 	displayName: string;

package/src/core/agents/agent-team.ts

@@ -19,6 +19,7 @@ import {
 import type { HelperTeam } from "./helper-ops.ts";
 import { type Routes, routesOf } from "./routes.ts";
 import { TeamEditing } from "./team-editing.ts";
+import type { TeamHelpers } from "./team-helpers.ts";
 import {
 	channelOwner,
 	coordinatorOf,
@@ -321,6 +322,10 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		return this.#turns.message(...args);
 	}
 
+	reach(...args: Parameters<TeamHelpers["reach"]>): Promise<void> {
+		return this.#lifecycle.helpers.reach(...args);
+	}
+
 	async read(
 		channel: string,
 		around: string | undefined,

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

@@ -123,7 +123,7 @@ export interface AgentOps {
 	avatar(name: string, look: CharacterInput): Promise<string>;
 	/** Queues the message and returns at once. */
 	/**
-	 * Hands a request to another agent, in the conversation it used most recently, or in the
+	 * Hands a request to another agent, in its conversation on the sender's surface, or in the
 	 * `conversation` named: "discord", "web" (or a room surface's name), or one of its conversation keys.
 	 */
 	message(
@@ -132,6 +132,15 @@ export interface AgentOps {
 		text: string,
 		conversation?: string,
 	): string;
+	/**
+	 * Readies the place a message is about to reach: a temp knight made in the web app gets its
+	 * Discord thread when the caller may message it and names "discord". Never rejects.
+	 */
+	reach?(
+		caller: AgentTurnScope,
+		to: string,
+		conversation?: string,
+	): Promise<void>;
 	createGroup(input: {
 		name: string;
 		displayName: string;
@@ -425,24 +434,23 @@ function toolDefs(
 			name: MESSAGE_AGENT_TOOL,
 			label: "Message agent",
 			description:
-				'Send a self-contained request to another agent. It returns at once; the agent works in its own conversation and its answer comes back to you as a new turn, in the conversation you are writing from. An agent has one conversation on each surface (Discord, the web app); by default the request lands in the one it used most recently, so work it started in the web app is answered there. Give conversation to choose another: "discord", "web", or one of the conversation keys agent_get lists for it. The exchange shows in its conversation, and a thread in yours.',
+				'Send a self-contained request to another agent. It returns at once; the agent works in its own conversation and its answer comes back to you as a new turn, in the conversation you are writing from. An agent has one conversation on each surface (Discord, the web app); by default the request lands in its conversation on the surface you are writing from (its room from a web room, its Discord channel from Discord), so nothing crosses surfaces unless you name it. Give conversation to choose another: "discord", "web", or one of the conversation keys agent_get lists for it. The request shows in its conversation, and the request and the answer show as small cards in yours.',
 			parameters: Type.Object({
 				to: NAME,
 				text: Type.String({ minLength: 1, maxLength: 4000 }),
 				conversation: Type.Optional(
 					Type.String({
 						description:
-							'Which of the agent\'s conversations to deliver into: "discord", "web" (or the name of another surface that hosts rooms), or a key from agent_get. Leave it out to reach the one it used most recently.',
+							'Which of the agent\'s conversations to deliver into: "discord", "web" (or the name of another surface that hosts rooms), or a key from agent_get. Leave it out to reach its conversation on the surface you are writing from.',
 					}),
 				),
 			}),
-			run: (i) =>
-				ops.message(
-					scope,
-					requiredString(i, "to"),
-					requiredString(i, "text"),
-					optionalString(i, "conversation"),
-				),
+			run: async (i) => {
+				const to = requiredString(i, "to");
+				const conversation = optionalString(i, "conversation");
+				await ops.reach?.(scope, to, conversation);
+				return ops.message(scope, to, requiredString(i, "text"), conversation);
+			},
 		});
 	return defs;
 }

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

@@ -2,12 +2,11 @@ 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 { followOrigin } from "./helper-modes.ts";
 import type { TeamContext } from "./team-options.ts";
 
 /** The team's way of making an agent, which `createHelper` uses to make a temp knight. */
@@ -98,10 +97,10 @@ export async function createHelper(
 	);
 	const helper = made.agent;
 	try {
-		await inheritLongRunning(ctx, caller, speaker, helper);
+		await followOrigin(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
+		// The modes 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;
@@ -158,23 +157,3 @@ async function makeRoom(
 	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-modes.ts

@@ -0,0 +1,64 @@
+import type { AgentTurnScope } from "../domain/ports.ts";
+import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
+import type { ModeOrigins } from "../modes/mode-inheritance.ts";
+import type { AgentDirectory } from "../services.ts";
+import type { Speaker } from "../speakers.ts";
+import { isHelper } from "./agent-rules.ts";
+import type { Agent } from "./agent-store.ts";
+import { agentOfChannel, groupOfChannel, keysOf } from "./team-keys.ts";
+import type { TeamContext } from "./team-options.ts";
+
+/**
+ * Makes the temp knight's conversations follow the modes of the conversation that asked for it,
+ * live, so turning yolo or long-running on or off there applies to it at once. This adds no
+ * permission: an owner turns the modes on there. Only a turn of an owner can carry them over, as
+ * for any change of modes; any other turn's temp knight starts with its own, both off, whatever
+ * an earlier agent of the same name followed.
+ */
+export async function followOrigin(
+	ctx: TeamContext,
+	caller: AgentTurnScope,
+	speaker: Speaker,
+	helper: Agent,
+): Promise<void> {
+	const { store, surfaces } = ctx.options;
+	const modes = ctx.options.modes?.();
+	if (!modes) return;
+	const keys = keysOf(store, helper.name, surfaces?.roomSurfaces() ?? []);
+	if (speaker.tier !== "owner" || speaker.principalId === SYSTEM_PRINCIPAL) {
+		for (const key of keys) await modes.forget(key);
+		return;
+	}
+	await modes.follow(keys, ctx.turns.turnChannel(caller), speaker);
+}
+
+/**
+ * What the agent server says of a conversation that follows another's modes: it still does while
+ * it is a temp knight's conversation made from that origin, named after the temp knight's parent;
+ * the origin is gone once the agent or group whose conversation it is (else the parent) is
+ * archived or deleted.
+ */
+export function modeOrigins(
+	store: Pick<
+		AgentDirectory,
+		"agent" | "agentByChannel" | "group" | "groupByChannel"
+	>,
+	hosts: { roomSurfaces(): readonly string[] },
+): ModeOrigins {
+	return {
+		originOf: (channel, origin) => {
+			const helper = agentOfChannel(store, hosts, channel);
+			if (!helper || !isHelper(helper) || helper.origin !== origin)
+				return undefined;
+			const parent = store.agent(helper.parent as string);
+			const owner =
+				agentOfChannel(store, hosts, origin) ??
+				groupOfChannel(store, hosts, origin) ??
+				parent;
+			return {
+				name: parent?.displayName ?? (helper.parent as string),
+				alive: owner?.status === "active",
+			};
+		},
+	};
+}

package/src/core/agents/message-target.ts

@@ -3,19 +3,22 @@ import { AgentError } from "../domain/errors.ts";
 import type { AgentDirectory } from "../services.ts";
 import type { Agent } from "./agent-store.ts";
 import { Routes } from "./routes.ts";
-import { agentRoomKey, discordKey, keysOf } from "./team-keys.ts";
+import { agentRoomKey, keysOf } from "./team-keys.ts";
 
 /** What the choice of a message's conversation reads. */
 export interface MessageTargetContext {
 	store: Pick<AgentDirectory, "agent" | "group">;
 	/** The surfaces that host agent rooms. */
 	roomSurfaces: readonly string[];
-	/** The conversation the target last ran a turn in, if it ran one since the host started. */
+	/**
+	 * The conversation the target last ran a turn in, if it ran one since the host started; read
+	 * only under the `"latest"` routing rule, and only on the sender's surface.
+	 */
 	latest: ChannelKey | undefined;
-	/** The conversation the sender writes from. */
+	/** The conversation the sender writes from: the origin whose surface the message stays on. */
 	from: ChannelKey;
 	/** The host's routing table; without it the defaults every host had before `routing`. */
-	routes?: Pick<Routes, "of">;
+	routes?: Pick<Routes, "of" | "placeOn">;
 }
 
 /** The word for the web app's conversation, accepted when exactly one surface hosts rooms. */
@@ -24,9 +27,8 @@ const WEB = "web";
 /**
  * The conversation of `target` that a message is delivered into. With `ask` (a surface name such
  * as "discord", "web", or the surface of a room, or one of the target's conversation keys) that
- * one; otherwise the conversation the routing table picks (`Routes.of`): by default the one the
- * target used most recently, which a message from a room never follows out to Discord, and, when
- * it has run none yet, the sender's own surface, so a message between rooms stays among the rooms.
+ * one; otherwise the conversation the routing table picks (`Routes.of`): by default the target's
+ * place on the sender's own surface, so a message never crosses surfaces unless named.
  */
 export function messageTarget(
 	ctx: MessageTargetContext,
@@ -35,25 +37,25 @@ export function messageTarget(
 ): ChannelKey {
 	const keys = keysOf(ctx.store, target.name, ctx.roomSurfaces);
 	const has = keys.length > 0 ? keys.join(", ") : "none";
-	if (ask === undefined || ask.trim() === "") {
-		const routes =
-			ctx.routes ??
-			new Routes({
-				store: ctx.store,
-				roomSurfaces: () => ctx.roomSurfaces,
-				latest: () => ctx.latest,
-			});
+	const routes =
+		ctx.routes ??
+		new Routes({
+			store: ctx.store,
+			roomSurfaces: () => ctx.roomSurfaces,
+			latest: () => ctx.latest,
+		});
+	if (ask === undefined || ask.trim() === "")
 		return routes.of(target.name, "agentMessage", ctx.from);
-	}
 	const wanted = ask.trim();
 	const exact = keys.find((key) => key === wanted);
 	if (exact !== undefined) return exact;
 	if (wanted === "discord") {
-		if (!target.channelId)
+		const place = routes.placeOn(target.name, "discord");
+		if (!place)
 			throw new AgentError(
 				`${target.name} has no Discord channel; its conversations: ${has}.`,
 			);
-		return discordKey(target.channelId);
+		return place;
 	}
 	const surface = ctx.roomSurfaces.includes(wanted)
 		? wanted