pi-roundtable 0.7.19 → 0.8.0

package/src/core/runtime/turn-progress.ts

@@ -0,0 +1,116 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { TurnProgress } from "../domain/progress.ts";
+
+/** How long text is joined before it is sent, so a fast stream costs a few events a second. */
+export const PROGRESS_INTERVAL_MS = 250;
+/** The longest preview of a tool's arguments, ellipsis included. */
+export const PROGRESS_PREVIEW_CHARS = 80;
+
+/** One turn's progress as the runtime reports it; every method returns at once and never throws. */
+export interface ProgressReporter {
+	text(delta: string): void;
+	toolStart(id: string, tool: string, args: unknown): void;
+	toolEnd(id: string, tool: string, isError: boolean): void;
+	/** Reports a session's event: its text deltas and its tools' starts and ends, never the thinking. */
+	observe(event: AgentSessionEvent): void;
+	/** Sends the text not sent yet; nothing is sent after it. */
+	close(): void;
+}
+
+export interface ProgressReporterOptions {
+	intervalMs?: number;
+	/** Runs `run` after `ms`; returns a cancel. Replaceable in tests. */
+	setTimer?: (run: () => void, ms: number) => () => void;
+}
+
+const realTimer = (run: () => void, ms: number) => {
+	const timer = setTimeout(run, ms);
+	timer.unref?.();
+	return () => clearTimeout(timer);
+};
+
+/** One line of a tool's arguments, cut to the preview length; undefined for none. */
+export function toolPreview(args: unknown): string | undefined {
+	let text: string | undefined;
+	try {
+		text = args === undefined ? undefined : JSON.stringify(args);
+	} catch {
+		return undefined;
+	}
+	if (!text || text === "{}" || text === "[]") return undefined;
+	const line = text.replace(/\s+/g, " ");
+	return line.length > PROGRESS_PREVIEW_CHARS
+		? `${line.slice(0, PROGRESS_PREVIEW_CHARS - 1)}…`
+		: line;
+}
+
+/**
+ * Turns a session's text deltas and tool events into `TurnProgress`. Text is joined and sent at
+ * most once per interval, and always before a tool event, so the order the turn wrote in holds.
+ * A sink that throws loses that event only.
+ */
+export function progressReporter(
+	sink: (event: TurnProgress) => void,
+	options: ProgressReporterOptions = {},
+): ProgressReporter {
+	const intervalMs = options.intervalMs ?? PROGRESS_INTERVAL_MS;
+	const setTimer = options.setTimer ?? realTimer;
+	let buffered = "";
+	let cancel: (() => void) | undefined;
+	let closed = false;
+	const send = (event: TurnProgress) => {
+		try {
+			sink(event);
+		} catch {
+			// The surface's failure is its own; the turn goes on without that event.
+		}
+	};
+	const flush = () => {
+		cancel?.();
+		cancel = undefined;
+		if (buffered === "") return;
+		const delta = buffered;
+		buffered = "";
+		send({ type: "text", delta });
+	};
+	const reporter: ProgressReporter = {
+		observe(event) {
+			if (
+				event.type === "message_update" &&
+				event.assistantMessageEvent.type === "text_delta"
+			)
+				reporter.text(event.assistantMessageEvent.delta);
+			else if (event.type === "tool_execution_start")
+				reporter.toolStart(event.toolCallId, event.toolName, event.args);
+			else if (event.type === "tool_execution_end")
+				reporter.toolEnd(event.toolCallId, event.toolName, event.isError);
+		},
+		text(delta) {
+			if (closed || delta === "") return;
+			buffered += delta;
+			cancel ??= setTimer(flush, intervalMs);
+		},
+		toolStart(id, tool, args) {
+			if (closed) return;
+			flush();
+			const preview = toolPreview(args);
+			send({
+				type: "tool_start",
+				id,
+				tool,
+				...(preview === undefined ? {} : { preview }),
+			});
+		},
+		toolEnd(id, tool, isError) {
+			if (closed) return;
+			flush();
+			send({ type: "tool_end", id, tool, ok: !isError });
+		},
+		close() {
+			if (closed) return;
+			flush();
+			closed = true;
+		},
+	};
+	return reporter;
+}

package/src/core/services.ts

@@ -4,6 +4,7 @@ import type { TeamStatus } from "./agents/team-status.ts";
 import type { ScheduledOutcome } from "./contract/channels.ts";
 import type { AgentRuntime } from "./contract/runtime.ts";
 import { type ServiceKey, serviceKey } from "./contract/services.ts";
+import type { ConversationRegistry } from "./conversations/conversation-registry.ts";
 import type { PendingConfirmation } from "./domain/conversation.ts";
 import type { HttpRoute } from "./http/listeners.ts";
 import type { ThinkingSetting } from "./models.ts";
@@ -35,6 +36,19 @@ import type { AgentTurnScope, ChannelKey } from "./sessions.ts";
 // interface, so an object with the same methods satisfies it without being one of the built-in
 // classes; a plugin replaces a built-in by providing its own under the same key.
 
+/**
+ * The runtime every conversation turn runs on: the agent server's, and each turn run through
+ * `context.turns`. The `runtime` provider slot's when a plugin fills it, Pi's otherwise. Provided
+ * by the `runtime` plugin, which every host registers, with or without the agent server.
+ */
+export const RUNTIME: ServiceKey<AgentRuntime> =
+	serviceKey<AgentRuntime>("roundtable.runtime");
+/**
+ * The conversations run through `context.turns`: who each belongs to, its kind and visibility,
+ * and when it was last active, recorded at its first turn. Provided by the `conversations` plugin.
+ */
+export const CONVERSATIONS: ServiceKey<ConversationRegistry> =
+	serviceKey<ConversationRegistry>("roundtable.conversations");
 /** The agent server: its team, its directory, the runtime that runs every agent turn. Provided by the agent-server plugin. */
 export const AGENTS: ServiceKey<AgentServer> =
 	serviceKey<AgentServer>("roundtable.agents");
@@ -84,7 +98,7 @@ export interface AgentServer {
 	team: AgentTeam;
 	/** Read-only lookups of agents and groups; edits go through the team. */
 	directory: AgentDirectory;
-	/** The runtime every agent-server turn runs on: the `runtime` provider's, or Pi's when no plugin fills the slot. */
+	/** The runtime every agent-server turn runs on: the same one `RUNTIME` provides. */
 	runtime: AgentRuntime;
 	/** Decides whether the owner's reply approves the actions the assistant held for them. */
 	approvals: {

package/src/core/shared/unix-server.ts

@@ -1,5 +1,5 @@
 import { rmSync } from "node:fs";
-import type { Server } from "bun";
+import type { Server, WebSocketHandler } from "bun";
 
 /**
  * Serves HTTP on a unix socket without Bun's 10-second idle timeout, which would cut long
@@ -9,18 +9,48 @@ import type { Server } from "bun";
  */
 export function serveUnix(
 	socketPath: string,
-	fetch: (request: Request) => Response | Promise<Response>,
-	options: { error?: (error: Error) => Response | Promise<Response> } = {},
-): Server<undefined> {
+	fetch: (
+		request: Request,
+		server: Server<undefined>,
+	) => Response | Promise<Response>,
+	options?: { error?: (error: Error) => Response | Promise<Response> },
+): Server<undefined>;
+/**
+ * Serves HTTP and WebSockets on a unix socket: `websocket` serves the sockets `fetch` upgrades
+ * with `server.upgrade`, and `fetch` answers nothing for a request it upgraded.
+ */
+export function serveUnix<WebSocketData>(
+	socketPath: string,
+	fetch: (
+		request: Request,
+		server: Server<WebSocketData>,
+	) => Response | undefined | Promise<Response | undefined>,
+	options: {
+		error?: (error: Error) => Response | Promise<Response>;
+		websocket: WebSocketHandler<WebSocketData>;
+	},
+): Server<WebSocketData>;
+export function serveUnix<WebSocketData>(
+	socketPath: string,
+	fetch: (
+		request: Request,
+		server: Server<WebSocketData>,
+	) => Response | undefined | Promise<Response | undefined>,
+	options: {
+		error?: (error: Error) => Response | Promise<Response>;
+		websocket?: WebSocketHandler<WebSocketData>;
+	} = {},
+): Server<WebSocketData> {
 	rmSync(socketPath, { force: true });
 	const serveOptions = {
 		unix: socketPath,
 		idleTimeout: 0,
 		fetch,
 		...(options.error ? { error: options.error } : {}),
+		...(options.websocket ? { websocket: options.websocket } : {}),
 	};
 	// SAFETY: these are Bun's unix-socket options; only `idleTimeout` is missing from its types.
 	return Bun.serve(
 		serveOptions as unknown as Parameters<typeof Bun.serve>[0],
-	) as Server<undefined>;
+	) as unknown as Server<WebSocketData>;
 }

package/src/core/testing/modules.ts

@@ -3,7 +3,7 @@ import type { SQL } from "bun";
 import { OWNER_TARGET } from "../agents/agent-claim.ts";
 import { DISCORD, type DiscordServices } from "../builtin/discord.ts";
 import { discordAdminPlugin } from "../builtin/discord-admin.ts";
-import { modulesPlugin } from "../builtin/modules.ts";
+import { type ModulesOptions, modulesPlugin } from "../builtin/modules.ts";
 import { skillsPlugin } from "../builtin/skills.ts";
 import { memoryPlugin } from "../builtin/stores.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
@@ -28,14 +28,28 @@ export interface ModuleRecord {
 	reportChannels: ChannelKey[];
 	/** How often a conversation without a chat channel fell back to the owner's messages. */
 	ownerChannelAsked: number;
+	/** What was posted on the surface, by channel. */
+	posted: { channel: ChannelKey; text: string }[];
 }
 
 export const OWNER_CHANNEL: ChannelKey = "discord:owner-dm";
 
 /** The modules plugin set up over stand-in stores and surface; returns its contribution and the record. */
 export async function setUpModules(
-	options: { agentChannelOf?: (name: string) => ChannelKey } = {},
+	options: {
+		agentChannelOf?: (name: string) => ChannelKey;
+		/** Whether Discord is there; default true. A host without it has no owner's messages. */
+		discord?: boolean;
+		/** Whether a plugin contributes the owner's background target, as the agent server does; default true. */
+		ownerTarget?: boolean;
+		/** Whether a claim owns a channel; by default the Discord channels are owned and no other. */
+		owns?: (channel: ChannelKey) => boolean;
+		/** Whether the claim owning a channel takes background turns; by default every owned channel's does. */
+		takesBackground?: (channel: ChannelKey) => boolean;
+		errorReporter?: ModulesOptions["errorReporter"];
+	} = {},
 ): Promise<{
+	plugin: RoundtablePlugin;
 	contribution: Contribution;
 	record: ModuleRecord;
 	services: ServiceRegistry;
@@ -44,6 +58,7 @@ export async function setUpModules(
 		threadOrigins: [],
 		reportChannels: [],
 		ownerChannelAsked: 0,
+		posted: [],
 	};
 	const plugin = modulesPlugin({
 		owner: {
@@ -61,40 +76,48 @@ export async function setUpModules(
 			thinking: "low",
 			worker: { run: async () => "found it" },
 		},
+		...(options.errorReporter ? { errorReporter: options.errorReporter } : {}),
 	});
 	const services = new ServiceRegistry([plugin]);
 	// SAFETY: the tools under test read no store; each stub is asked for nothing else.
 	services.preset(MEMORY, {} as MemoryStore);
 	services.preset(SCHEDULES, {} as ScheduleStore);
-	// SAFETY: the schedule tools ask the agent team for a channel and nothing else.
 	if (options.agentChannelOf)
+		// SAFETY: the schedule tools ask the agent team for a channel and nothing else.
 		services.preset(AGENTS, {
 			team: { channelOf: options.agentChannelOf },
 		} as unknown as AgentServer);
-	// SAFETY: the tools under test use the connection's owner channel and the threads' open only.
-	services.preset(DISCORD, {
-		connection: {
-			ownerChannel: async () => {
-				record.ownerChannelAsked += 1;
-				return OWNER_CHANNEL;
+	if (options.discord !== false)
+		// SAFETY: the tools under test use the connection's owner channel and the threads' open only.
+		services.preset(DISCORD, {
+			connection: {
+				ownerChannel: async () => {
+					record.ownerChannelAsked += 1;
+					return OWNER_CHANNEL;
+				},
+				ownerOperations: () => ({}),
 			},
-			ownerOperations: () => ({}),
-		},
-		threads: {
-			open: async (origin: ChannelKey | undefined) => {
-				record.threadOrigins.push(origin);
-				return undefined;
+			threads: {
+				open: async (origin: ChannelKey | undefined) => {
+					record.threadOrigins.push(origin);
+					return undefined;
+				},
 			},
-		},
-		guard: {},
-		commands: { add: () => undefined },
-	} as unknown as DiscordServices);
-	// SAFETY: setup reads only the logger, the conversations' background and targets, the surfaces, and the services.
+			guard: {},
+			commands: { add: () => undefined },
+		} as unknown as DiscordServices);
+	const owns =
+		options.owns ?? ((channel: ChannelKey) => channel.startsWith("discord:"));
+	// SAFETY: setup and the preflight read only the logger, the conversations' background, targets and owners, the surfaces, and the services.
 	const context = {
 		logger: silentLogger(),
 		conversations: {
 			target: (name: string) =>
-				name === OWNER_TARGET.name ? OWNER_TARGET : undefined,
+				options.ownerTarget !== false && name === OWNER_TARGET.name
+					? OWNER_TARGET
+					: undefined,
+			owns,
+			takesBackground: options.takesBackground ?? owns,
 			background: async (turn: { channel: ChannelKey }) => {
 				record.reportChannels.push(turn.channel);
 				return { status: "ran" };
@@ -105,14 +128,15 @@ export async function setUpModules(
 			{
 				surface: "discord",
 				start: async () => undefined,
-				sendReply: async () => undefined,
+				sendReply: async (channel, reply) =>
+					void record.posted.push({ channel, text: reply.chunks.join("") }),
 			},
 		]),
 	} as unknown as Omit<PluginContext, "services">;
 	const contribution = await services.setUp(plugin, () =>
 		plugin.setup(pluginContext(plugin, context, services.forPlugin(plugin))),
 	);
-	return { contribution, record, services };
+	return { plugin, contribution, record, services };
 }
 
 /** What each addon plugin contributes, set up over stand-ins as far as setup reads them. */