pi-roundtable 0.1.0

package/src/core/runtime/text-tools.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { AgentError, ScheduleError } from "../domain/errors.ts";
+import {
+	optionalString,
+	requiredString,
+	stringList,
+	type TextToolDef,
+	textToolsExtension,
+} from "./text-tools.ts";
+
+interface Registered {
+	name: string;
+	label: string;
+	execute: (
+		id: string,
+		params: unknown,
+		signal: AbortSignal | undefined,
+	) => Promise<{
+		isError?: boolean;
+		content: { type: string; text: string }[];
+		details?: unknown;
+	}>;
+}
+
+async function registered(defs: TextToolDef[]): Promise<Registered[]> {
+	const tools: Registered[] = [];
+	await textToolsExtension(
+		defs,
+		AgentError,
+	)({
+		registerTool: (tool: Registered) => {
+			tools.push(tool);
+		},
+	} as unknown as ExtensionAPI);
+	return tools;
+}
+
+const def = (run: TextToolDef["run"]): TextToolDef => ({
+	name: "echo",
+	label: "Echo",
+	description: "Echo.",
+	parameters: Type.Object({}),
+	run,
+});
+
+describe("textToolsExtension", () => {
+	test("registers each tool and returns its text", async () => {
+		const [tool] = await registered([def((i) => `got ${String(i.word)}`)]);
+		expect(tool?.name).toBe("echo");
+		expect(tool?.label).toBe("Echo");
+		const result = await tool?.execute("1", { word: "hi" }, undefined);
+		expect(result).toEqual({
+			content: [{ type: "text", text: "got hi" }],
+			details: {},
+		});
+	});
+
+	test("passes the call's signal to the tool", async () => {
+		const signal = new AbortController().signal;
+		let seen: AbortSignal | undefined;
+		const [tool] = await registered([
+			def((_i, s) => {
+				seen = s;
+				return "ok";
+			}),
+		]);
+		await tool?.execute("1", {}, signal);
+		expect(seen).toBe(signal);
+	});
+
+	test("turns the refusal class into an error result", async () => {
+		const [tool] = await registered([
+			def(() => {
+				throw new AgentError("no such agent");
+			}),
+		]);
+		const result = await tool?.execute("1", {}, undefined);
+		expect(result?.isError).toBe(true);
+		expect(result?.content[0]?.text).toBe("no such agent");
+	});
+
+	test("lets any other error fail the call", async () => {
+		const [tool] = await registered([
+			def(() => {
+				throw new ScheduleError("wrong domain");
+			}),
+		]);
+		expect(tool?.execute("1", {}, undefined)).rejects.toThrow("wrong domain");
+	});
+});
+
+describe("tool input", () => {
+	test("reads strings and string lists", () => {
+		const input = { a: "x", n: 3, list: ["p", 4, "q"] };
+		expect(optionalString(input, "a")).toBe("x");
+		expect(optionalString(input, "n")).toBeUndefined();
+		expect(stringList(input, "list")).toEqual(["p", "q"]);
+		expect(stringList(input, "a")).toBeUndefined();
+	});
+
+	test("refuses a blank required string with AgentError", () => {
+		expect(requiredString({ a: " x " }, "a")).toBe(" x ");
+		expect(() => requiredString({ a: "  " }, "a")).toThrow(
+			new AgentError("a is required."),
+		);
+		expect(() => requiredString({}, "b")).toThrow(AgentError);
+	});
+});

package/src/core/runtime/text-tools.ts

@@ -0,0 +1,66 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import { AgentError } from "../domain/errors.ts";
+import { toolError, toolText } from "../shared/tool-result.ts";
+
+export type ToolInput = Record<string, unknown>;
+
+/** A tool whose result is text for the model. */
+export interface TextToolDef<Name extends string = string> {
+	name: Name;
+	label: string;
+	description: string;
+	parameters: TSchema;
+	run(input: ToolInput, signal?: AbortSignal): Promise<string> | string;
+}
+
+type ErrorClass = abstract new (...args: never[]) => Error;
+
+/**
+ * Registers text tools. A thrown `refusal` becomes an error result the model reads; any other
+ * error fails the call.
+ */
+export function textToolsExtension(
+	defs: readonly TextToolDef[],
+	refusal: ErrorClass,
+): ExtensionFactory {
+	return (pi) => {
+		for (const def of defs) {
+			pi.registerTool({
+				name: def.name,
+				label: def.label,
+				description: def.description,
+				parameters: def.parameters,
+				execute: async (_toolCallId, params, signal) => {
+					try {
+						return toolText(await def.run(params as ToolInput, signal));
+					} catch (error) {
+						if (!(error instanceof refusal)) throw error;
+						return toolError(error.message);
+					}
+				},
+			});
+		}
+	};
+}
+
+/** A string argument, or undefined when absent. */
+export function optionalString(input: ToolInput, key: string) {
+	const value = input[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+/** A string argument that is not blank; throws AgentError otherwise. */
+export function requiredString(input: ToolInput, key: string): string {
+	const value = optionalString(input, key);
+	if (!value?.trim()) throw new AgentError(`${key} is required.`);
+	return value;
+}
+
+/** The strings of an array argument, or undefined when it is not an array. */
+export function stringList(input: ToolInput, key: string) {
+	const value = input[key];
+	return Array.isArray(value)
+		? value.filter((v): v is string => typeof v === "string")
+		: undefined;
+}

package/src/core/runtime/turn-answer.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import { lastReply, thinkingOf, turnAnswer } from "./turn-answer.ts";
+
+const assistant = (
+	text: string,
+	stopReason = "stop",
+	thinking?: { thinking: string; redacted?: boolean },
+) => ({
+	role: "assistant",
+	stopReason,
+	content: [
+		...(thinking ? [{ type: "thinking", ...thinking }] : []),
+		{ type: "text", text },
+	],
+});
+const user = { role: "user", content: "hi" };
+
+describe("turnAnswer", () => {
+	test("answers with the last message's text and its visible thinking", () => {
+		expect(
+			turnAnswer(
+				[
+					user,
+					assistant("tool call", "toolUse", { thinking: " plan " }),
+					assistant(" done ", "stop", { thinking: "secret", redacted: true }),
+				],
+				false,
+			),
+		).toEqual({ ok: true, text: "done", thinking: "plan" });
+	});
+
+	test("keeps every final answer of a steered run", () => {
+		expect(
+			turnAnswer(
+				[
+					assistant("first"),
+					user,
+					assistant("tool", "toolUse"),
+					assistant("second"),
+				],
+				true,
+			),
+		).toEqual({ ok: true, text: "first\n\nsecond" });
+	});
+
+	test("fails without a usable answer", () => {
+		const none = turnAnswer([user], false);
+		expect(none.ok || none.error.message).toBe(
+			"the run produced no assistant message",
+		);
+		const blank = turnAnswer([assistant("  ")], false);
+		expect(blank.ok || blank.error.message).toBe(
+			"the final assistant message has no text",
+		);
+	});
+});
+
+describe("session helpers", () => {
+	test("lastReply is the last answer's text, or undefined", () => {
+		expect(lastReply([assistant("a"), user, assistant(" b ")])).toBe("b");
+		expect(lastReply([user])).toBeUndefined();
+	});
+
+	test("thinkingOf skips redacted thinking", () => {
+		expect(
+			thinkingOf([
+				assistant("x", "stop", { thinking: "one" }),
+				assistant("y", "stop", { thinking: "two", redacted: true }),
+			]),
+		).toBe("one");
+	});
+});

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

@@ -0,0 +1,79 @@
+import type { TurnResult } from "../domain/conversation.ts";
+import { AgentRunError } from "../domain/errors.ts";
+import { lastAssistant, textOf } from "../shared/session-messages.ts";
+
+interface MessagePart {
+	type?: unknown;
+	text?: unknown;
+	thinking?: unknown;
+	redacted?: unknown;
+}
+
+type Message = { role: string };
+type Assistant = Message & {
+	role: "assistant";
+	content: unknown;
+	stopReason?: string;
+};
+
+const isAssistant = (message: Message): message is Assistant =>
+	message.role === "assistant";
+
+/** The session's last answer, which tells the judge what a short follow-up continues. */
+export function lastReply(messages: readonly Message[]): string | undefined {
+	const last = messages.findLast(isAssistant);
+	return last ? textOf(last.content).trim() || undefined : undefined;
+}
+
+/** The visible thinking of the messages a turn added, in order. */
+export function thinkingOf(messages: readonly Message[]): string {
+	return messages
+		.filter(isAssistant)
+		.flatMap((message) =>
+			Array.isArray(message.content)
+				? (message.content as (MessagePart | undefined)[])
+				: [],
+		)
+		.filter(
+			(
+				part,
+			): part is { type: "thinking"; thinking: string; redacted?: boolean } =>
+				part?.type === "thinking" &&
+				typeof part.thinking === "string" &&
+				part.redacted !== true,
+		)
+		.map((part) => part.thinking.trim())
+		.filter(Boolean)
+		.join("\n\n");
+}
+
+/**
+ * A finished turn's result from the messages it added. A steered run may have answered before
+ * the steer arrived, so every final answer of it is kept.
+ */
+export function turnAnswer(
+	messages: readonly Message[],
+	steered: boolean,
+): TurnResult {
+	const last = lastAssistant(messages);
+	if (!last.ok) return { ok: false, error: new AgentRunError(last.error) };
+	const text = (
+		steered
+			? messages
+					.filter(
+						(message): message is Assistant =>
+							isAssistant(message) && message.stopReason === "stop",
+					)
+					.map((message) => textOf(message.content).trim())
+					.filter(Boolean)
+					.join("\n\n")
+			: textOf(last.message.content)
+	).trim();
+	if (!text)
+		return {
+			ok: false,
+			error: new AgentRunError("the final assistant message has no text"),
+		};
+	const thinking = thinkingOf(messages);
+	return { ok: true, text, ...(thinking ? { thinking } : {}) };
+}

package/src/core/runtime/worker-task.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import { AgentRunError } from "../domain/errors.ts";
+import { lastAssistant, textOf } from "../shared/session-messages.ts";
+import { MAX_REPORT_CHARS, workerReport } from "./worker-task.ts";
+
+const user = { role: "user", content: "task" };
+const answer = (text: string, extra: Record<string, unknown> = {}) => ({
+	role: "assistant",
+	content: [
+		{ type: "thinking", thinking: "hm" },
+		{ type: "text", text },
+	],
+	stopReason: "stop",
+	...extra,
+});
+
+describe("textOf", () => {
+	test("joins text parts and passes a string through", () => {
+		expect(
+			textOf([
+				{ type: "text", text: "a" },
+				{ type: "image" },
+				{ type: "text", text: "b" },
+			]),
+		).toBe("a\nb");
+		expect(textOf("plain")).toBe("plain");
+		expect(textOf(undefined)).toBe("");
+	});
+});
+
+describe("lastAssistant", () => {
+	test("finds the last assistant message", () => {
+		const result = lastAssistant([user, answer("first"), answer("second")]);
+		expect(result.ok && textOf(result.message.content)).toBe("second");
+	});
+
+	test("says why there is no usable answer", () => {
+		expect(lastAssistant([user])).toEqual({
+			ok: false,
+			error: "the run produced no assistant message",
+		});
+		expect(
+			lastAssistant([answer("", { stopReason: "error", errorMessage: "503" })]),
+		).toEqual({ ok: false, error: "503" });
+		expect(lastAssistant([answer("", { stopReason: "error" })])).toEqual({
+			ok: false,
+			error: "the run stopped with error",
+		});
+		expect(lastAssistant([answer("", { stopReason: "aborted" })])).toEqual({
+			ok: false,
+			error: "the run stopped with aborted",
+		});
+		expect(
+			lastAssistant([answer("", { stopReason: "aborted" })], "timed out"),
+		).toEqual({ ok: false, error: "timed out" });
+	});
+});
+
+describe("workerReport", () => {
+	test("returns the trimmed answer", () => {
+		expect(workerReport([user, answer("  done  ")], "stopped")).toBe("done");
+	});
+
+	test("cuts a long report and says so", () => {
+		const report = workerReport(
+			[answer("x".repeat(MAX_REPORT_CHARS + 5))],
+			"stopped",
+		);
+		expect(report).toBe(
+			`${"x".repeat(MAX_REPORT_CHARS)}\n\n[report cut at ${MAX_REPORT_CHARS} characters]`,
+		);
+	});
+
+	test("throws AgentRunError without a usable answer", () => {
+		expect(() =>
+			workerReport([answer("", { stopReason: "aborted" })], "stopped"),
+		).toThrow(new AgentRunError("stopped"));
+		expect(() => workerReport([answer("   ")], "stopped")).toThrow(
+			new AgentRunError("the worker's answer is empty"),
+		);
+	});
+});

package/src/core/runtime/worker-task.ts

@@ -0,0 +1,65 @@
+import type {
+	AgentSession,
+	ModelRuntime,
+} from "@earendil-works/pi-coding-agent";
+import { AgentRunError, ConfigError } from "../domain/errors.ts";
+import { parseModelRef } from "../models.ts";
+import { lastAssistant, textOf } from "../shared/session-messages.ts";
+
+export const MAX_REPORT_CHARS = 20_000;
+
+/**
+ * A finished worker's report: its last answer, cut at MAX_REPORT_CHARS. Throws AgentRunError
+ * when it has none; `aborted` says why an aborted run stopped.
+ */
+export function workerReport(
+	messages: readonly { role: string }[],
+	aborted: string,
+): string {
+	const last = lastAssistant(messages, aborted);
+	if (!last.ok) throw new AgentRunError(last.error);
+	const report = textOf(last.message.content).trim();
+	if (!report) throw new AgentRunError("the worker's answer is empty");
+	return report.length > MAX_REPORT_CHARS
+		? `${report.slice(0, MAX_REPORT_CHARS)}\n\n[report cut at ${MAX_REPORT_CHARS} characters]`
+		: report;
+}
+
+/** The host's model for `<provider>/<id>`; throws ConfigError when it has none. */
+export function hostModel(runtime: ModelRuntime, model: string) {
+	const ref = parseModelRef(model);
+	const resolved = ref && runtime.getModel(ref.provider, ref.id);
+	if (!resolved)
+		throw new ConfigError(`model ${model} is not available on this host`);
+	return resolved;
+}
+
+/**
+ * Runs one task in a fresh session on the model and returns its report; the signal aborts it.
+ * The session is disposed of either way.
+ */
+export async function runWorkerTask(
+	session: AgentSession,
+	options: {
+		modelRuntime: ModelRuntime;
+		/** `<provider>/<id>`. */
+		model: string;
+		task: string;
+		signal: AbortSignal;
+		/** Why an aborted run stopped, as the report's error. */
+		aborted: string;
+	},
+): Promise<string> {
+	const { modelRuntime, model, task, signal, aborted } = options;
+	const onAbort = () => void session.abort();
+	signal.addEventListener("abort", onAbort);
+	try {
+		// Extension providers such as claude-bridge exist only once the session loaded them.
+		await session.setModel(hostModel(modelRuntime, model));
+		await session.prompt(task);
+		return workerReport(session.messages, aborted);
+	} finally {
+		signal.removeEventListener("abort", onAbort);
+		session.dispose();
+	}
+}

package/src/core/services.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { PluginError } from "./errors.ts";
+import { CoreRegistry, type CoreStores } from "./services.ts";
+
+const stores = {} as CoreStores;
+
+describe("CoreRegistry", () => {
+	test("gives a plugin what a built-in one provided", () => {
+		const core = new CoreRegistry();
+		core.provide("stores", stores);
+		expect(core.stores).toBe(stores);
+	});
+
+	test("reading a service before it is provided names the service and the fix", () => {
+		expect(() => new CoreRegistry().stores).toThrow(PluginError);
+		expect(() => new CoreRegistry().stores).toThrow(
+			"core service stores is not provided yet. Register the built-in plugin that provides it before the plugin that reads it.",
+		);
+	});
+
+	test("a service provided twice is refused", () => {
+		const core = new CoreRegistry();
+		core.provide("stores", stores);
+		expect(() => core.provide("stores", stores)).toThrow(
+			"core service stores is provided twice. Register only one plugin that provides it.",
+		);
+	});
+});

package/src/core/services.ts

@@ -0,0 +1,107 @@
+import type { AgentStore } from "./agents/agent-store.ts";
+import type { AgentTeam } from "./agents/agent-team.ts";
+import type { AvatarStudio } from "./agents/avatar-studio.ts";
+import type { DiscordSurface } from "./discord/discord-surface.ts";
+import type { DispatchThreads } from "./discord/dispatch-threads.ts";
+import type { OwnerCards } from "./discord/owner-cards.ts";
+import type { OwnerGuard } from "./discord/owner-command.ts";
+import { PluginError } from "./errors.ts";
+import type { ConfirmationJudge } from "./judging/confirmation-judge.ts";
+import type { BackgroundTurns } from "./modules/background/background-turns.ts";
+import type { Delegator } from "./modules/delegation/delegator.ts";
+import type { OwnerMemoryStore } from "./modules/memory/owner-memory-store.ts";
+import type { ScheduleStore } from "./modules/schedules/schedule-store.ts";
+import type { SkillRegistry } from "./modules/skills/skill-registry.ts";
+import type { SkillStore } from "./modules/skills/skill-store.ts";
+import type { PendingConfirmationStore } from "./runtime/pending-confirmation-store.ts";
+import type { PiAgentRuntime } from "./runtime/pi-agent-runtime.ts";
+
+/** The stores every process has, attached to the host's one pool. */
+export interface CoreStores {
+	/** The owner's memory. */
+	memory: OwnerMemoryStore;
+	schedules: ScheduleStore;
+	/** Held actions, kept across a restart. */
+	confirmations: PendingConfirmationStore;
+	/** The agent server's agents and groups. */
+	agents: AgentStore;
+	skills: SkillStore;
+}
+
+/** The Discord connection and what stands on it. */
+export interface CoreDiscord {
+	surface: DiscordSurface;
+	/** The owner's cards, which also answer the interactions of held actions. */
+	cards: OwnerCards;
+	guard: OwnerGuard;
+	studio: AvatarStudio;
+	/** The threads that carry background reports. */
+	threads: DispatchThreads;
+}
+
+/** What the agent server builds. */
+export interface CoreAgents {
+	team: AgentTeam;
+	runtime: PiAgentRuntime;
+	skills: SkillRegistry;
+	/** Decides whether the owner's reply approves a held action. */
+	confirmations: ConfirmationJudge;
+}
+
+/** What the built-in plugins build for the plugins registered after them. */
+export interface CoreServices {
+	stores: CoreStores;
+	discord: CoreDiscord;
+	/** Turns nobody wrote: a due schedule's, a delegated task's report, a logged error's. */
+	background: BackgroundTurns;
+	delegator: Delegator;
+	/** The agent server: its team, the runtime that runs every turn, and the skill registry. */
+	agents: CoreAgents;
+}
+
+/** Reads the core's services; reading one before its built-in plugin has set up throws a PluginError. */
+export type CoreAccess = {
+	readonly [K in keyof CoreServices]: CoreServices[K];
+};
+
+/** Holds what the built-in plugins provide, for the plugins set up after them. */
+export class CoreRegistry implements CoreAccess {
+	readonly #values = new Map<keyof CoreServices, unknown>();
+
+	/** Stores a service; a built-in plugin calls this once in its setup. */
+	provide<K extends keyof CoreServices>(key: K, value: CoreServices[K]): void {
+		if (this.#values.has(key))
+			throw new PluginError(
+				`core service ${key} is provided twice. Register only one plugin that provides it.`,
+			);
+		this.#values.set(key, value);
+	}
+
+	#need<K extends keyof CoreServices>(key: K): CoreServices[K] {
+		if (!this.#values.has(key))
+			throw new PluginError(
+				`core service ${key} is not provided yet. Register the built-in plugin that provides it before the plugin that reads it.`,
+			);
+		return this.#values.get(key) as CoreServices[K];
+	}
+
+	get stores(): CoreStores {
+		return this.#need("stores");
+	}
+
+	get discord(): CoreDiscord {
+		return this.#need("discord");
+	}
+
+	get background(): BackgroundTurns {
+		return this.#need("background");
+	}
+
+	get delegator(): Delegator {
+		return this.#need("delegator");
+	}
+
+	get agents(): CoreAgents {
+		return this.#need("agents");
+	}
+}

package/src/core/sessions.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import { PluginError } from "./errors.ts";
+import { compileSessionPlan, planOrder, type SessionTool } from "./sessions.ts";
+
+const tool = (name: string, phase: SessionTool["phase"]): SessionTool => ({
+	name,
+	phase,
+	...(phase === "compaction" ? { engine: `${name}-engine` } : {}),
+	snapshot: () => ({ revision: 0, factory: () => null }),
+});
+
+const names = (tools: readonly SessionTool[]) => tools.map((t) => t.name);
+
+describe("compileSessionPlan", () => {
+	test("orders tools, then the compactor, then MCP, keeping registration order in each", () => {
+		const plan = compileSessionPlan([
+			tool("mcp-a", "mcp"),
+			tool("memory", "tools"),
+			tool("summarizer", "compaction"),
+			tool("notify", "tools"),
+			tool("mcp-b", "mcp"),
+		]);
+		expect(names(planOrder(plan))).toEqual([
+			"memory",
+			"notify",
+			"summarizer",
+			"mcp-a",
+			"mcp-b",
+		]);
+	});
+
+	test("a plan without a compactor has none", () => {
+		const plan = compileSessionPlan([tool("memory", "tools")]);
+		expect(plan.compaction).toBeUndefined();
+		expect(names(planOrder(plan))).toEqual(["memory"]);
+	});
+
+	test("refuses a name registered twice", () => {
+		expect(() =>
+			compileSessionPlan([tool("memory", "tools"), tool("memory", "mcp")]),
+		).toThrow(
+			new PluginError(
+				"session tool memory is registered twice. Rename one of the two.",
+			),
+		);
+	});
+
+	test("refuses the names of the core's own extensions", () => {
+		for (const name of [
+			"read-attachment",
+			"confirmation-gate",
+			"ask-user",
+			"self-compact-guard",
+			"profile-tools",
+		]) {
+			expect(() => compileSessionPlan([tool(name, "tools")])).toThrow(
+				new PluginError(
+					`session tool ${name} takes a core extension name. Rename it.`,
+				),
+			);
+		}
+	});
+
+	test("refuses a compactor that names no engine", () => {
+		const { engine: _engine, ...unmarked } = tool("summarizer", "compaction");
+		expect(() => compileSessionPlan([unmarked])).toThrow(
+			new PluginError(
+				"compactor summarizer needs an engine: the value its compactions record as details.engine.",
+			),
+		);
+	});
+
+	test("refuses a second compactor", () => {
+		expect(() =>
+			compileSessionPlan([
+				tool("summarizer", "compaction"),
+				tool("pi", "compaction"),
+			]),
+		).toThrow(
+			new PluginError(
+				"only one compactor may run; got summarizer, pi. Keep one.",
+			),
+		);
+	});
+});