pi-roundtable 0.1.0

package/src/core/sessions.ts

@@ -0,0 +1,149 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { PluginError } from "./errors.ts";
+import type { Speaker } from "./speakers.ts";
+
+/** `<surface>:<channel id>`, for example `discord:1234`. A DM is one channel. */
+export type ChannelKey = `${string}:${string}`;
+
+/** Who an agent-server turn belongs to; see the agent team. */
+export interface AgentTurnScope {
+	/** The agent's name. */
+	name: string;
+	/** The conversation and its held actions: the agent's channel, or its seat in a group. */
+	session: ChannelKey;
+	/** The agent's own channel, where its schedules and delegated reports belong. */
+	home: ChannelKey;
+	/** The group, for a member's conversation in one. */
+	group?: string;
+}
+
+/** The tools a turn or a transient task may use: named tools, plus every tool of each named group. */
+export interface ToolSelection {
+	tools: readonly string[];
+	groups: readonly string[];
+}
+
+/** The tools of one turn, named so its held actions and log lines say which selection ran. */
+export interface TurnSelection extends ToolSelection {
+	id: string;
+}
+
+/** A task that runs now in a fresh, unsaved session and reports its final text. */
+export interface TransientTask {
+	selection: ToolSelection;
+	text: string;
+	/** Aborted after this long. */
+	timeoutMs: number;
+	signal?: AbortSignal;
+	/** Tools of the selection the task may not use. */
+	exclude: readonly string[];
+	/** Called after the session is disposed, whether the task succeeded or failed. */
+	onFinished?(toolCalls: readonly string[]): void;
+}
+
+/** What one Pi session is for, as a session tool's factory sees it. */
+export interface SessionContext {
+	kind: "owner" | "agent";
+	/** Where the session's schedules and delegated reports belong: the agent's own channel, or the owner's. */
+	homeChannel: ChannelKey;
+	/** Where the session's turns run: a group's channel for an agent's seat in it, else the home channel. */
+	turnChannel: ChannelKey;
+	/** The agent the session belongs to; absent for the owner's sessions. */
+	agent?: AgentTurnScope;
+	/** Wraps a compactor so the core's compaction tiers decide when it may answer. */
+	compaction: { wrap(compactor: ExtensionFactory): ExtensionFactory };
+	/** The person the session's running turn is for; undefined between turns. */
+	speaker(): Speaker | undefined;
+	/** Runs a task beside this session, under its confirmation gate. */
+	runTask(task: TransientTask): Promise<string>;
+}
+
+/**
+ * One contribution's state for a session being built. A new revision rebuilds each open
+ * session on its next turn, keeping its history.
+ */
+export interface SessionToolSnapshot {
+	revision: number;
+	/** The session's extension, or null when the contribution does not apply to it. */
+	factory(session: SessionContext): ExtensionFactory | null;
+	/** Tool groups a selection may name, in order. */
+	groups?: readonly { name: string; tools: readonly string[] }[];
+	/** Tools a new session waits for, because they register after it loads. */
+	awaitTools?: readonly string[];
+	/** Tools startup refuses to run without. */
+	requiredTools?: readonly string[];
+}
+
+/** A named Pi extension a plugin adds to every conversation session, at its phase's position. */
+export interface SessionTool {
+	/** The extension's name, unique across sessions. */
+	name: string;
+	phase: "tools" | "compaction" | "mcp";
+	/**
+	 * The compaction phase's marker: the `engine` its compactions record in their details, which is how
+	 * the core tells them from Pi's own.
+	 */
+	engine?: string;
+	/** Synchronous and side-effect free; read once per session build and before each turn. */
+	snapshot(): SessionToolSnapshot;
+}
+
+/** Extensions the core places itself; no contribution may take their names. */
+const CORE_EXTENSIONS = [
+	"read-attachment",
+	"confirmation-gate",
+	"ask-user",
+	"self-compact-guard",
+	"profile-tools",
+] as const;
+
+/** Session tools grouped by phase, each group in registration order. */
+export interface SessionPlan {
+	tools: readonly SessionTool[];
+	compaction?: SessionTool;
+	mcp: readonly SessionTool[];
+}
+
+/** Checks the contributions and orders them by phase; throws PluginError on a clash. */
+export function compileSessionPlan(
+	contributions: readonly SessionTool[],
+): SessionPlan {
+	const reserved = new Set<string>(CORE_EXTENSIONS);
+	const names = new Set<string>();
+	for (const { name } of contributions) {
+		if (reserved.has(name))
+			throw new PluginError(
+				`session tool ${name} takes a core extension name. Rename it.`,
+			);
+		if (names.has(name))
+			throw new PluginError(
+				`session tool ${name} is registered twice. Rename one of the two.`,
+			);
+		names.add(name);
+	}
+	const compactors = contributions.filter((c) => c.phase === "compaction");
+	if (compactors.length > 1)
+		throw new PluginError(
+			`only one compactor may run; got ${compactors.map((c) => c.name).join(", ")}. Keep one.`,
+		);
+	const unmarked = compactors.find((c) => !c.engine);
+	if (unmarked)
+		throw new PluginError(
+			`compactor ${unmarked.name} needs an engine: the value its compactions record as details.engine.`,
+		);
+	const plan: SessionPlan = {
+		tools: contributions.filter((c) => c.phase === "tools"),
+		mcp: contributions.filter((c) => c.phase === "mcp"),
+	};
+	if (compactors[0]) plan.compaction = compactors[0];
+	return plan;
+}
+
+/** A plan's contributions in the order their extensions load. */
+export function planOrder(plan: SessionPlan): readonly SessionTool[] {
+	return [
+		...plan.tools,
+		...(plan.compaction ? [plan.compaction] : []),
+		...plan.mcp,
+	];
+}

package/src/core/shared/attachment-reader.ts

@@ -0,0 +1,91 @@
+import { basename, join } from "node:path";
+import { extractText, getDocumentProxy } from "unpdf";
+
+/** Characters returned per read; the model can ask for a later offset. */
+export const READ_LIMIT = 60_000;
+
+const TEXT_EXTENSIONS = new Set([
+	".txt",
+	".md",
+	".markdown",
+	".csv",
+	".tsv",
+	".json",
+	".yaml",
+	".yml",
+	".xml",
+	".html",
+	".htm",
+	".log",
+	".ts",
+	".js",
+	".py",
+	".sh",
+	".toml",
+	".ini",
+	".srt",
+	".vtt",
+]);
+
+function extension(name: string): string {
+	const dot = name.lastIndexOf(".");
+	return dot < 0 ? "" : name.slice(dot).toLowerCase();
+}
+
+function isPdf(name: string, head: Uint8Array): boolean {
+	return (
+		extension(name) === ".pdf" ||
+		new TextDecoder().decode(head.subarray(0, 5)) === "%PDF-"
+	);
+}
+
+function looksLikeText(bytes: Uint8Array): boolean {
+	const sample = bytes.subarray(0, 4096);
+	if (sample.includes(0)) return false;
+	try {
+		new TextDecoder("utf-8", { fatal: true }).decode(sample);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export interface ReadResult {
+	text: string;
+	/** Characters in the whole extracted text. */
+	total: number;
+}
+
+/**
+ * Reads a stored attachment as text: plain text files directly, PDFs through unpdf.
+ * Other files are refused with a message naming what can take them.
+ * `file` must be a name inside `dir`; paths are rejected.
+ */
+export async function readAttachment(
+	dir: string,
+	file: string,
+	offset = 0,
+): Promise<ReadResult> {
+	if (basename(file) !== file || file.startsWith(".")) {
+		throw new Error(`"${file}" is not an attachment name`);
+	}
+	const handle = Bun.file(join(dir, file));
+	if (!(await handle.exists())) {
+		throw new Error(`no attachment named "${file}" in this channel`);
+	}
+	const bytes = new Uint8Array(await handle.arrayBuffer());
+	let text: string;
+	if (isPdf(file, bytes)) {
+		const pdf = await getDocumentProxy(bytes);
+		const result = await extractText(pdf, { mergePages: true });
+		text = `[PDF, ${result.totalPages} pages]\n${result.text}`;
+	} else if (TEXT_EXTENSIONS.has(extension(file)) || looksLikeText(bytes)) {
+		text = new TextDecoder().decode(bytes);
+	} else {
+		throw new Error(
+			`"${file}" is not a text or PDF file (${bytes.byteLength} bytes). Images are shown to you directly; audio or video can go to a tool that takes files.`,
+		);
+	}
+	const start = Math.max(0, Math.floor(offset));
+	return { text: text.slice(start, start + READ_LIMIT), total: text.length };
+}

package/src/core/shared/delegate-tool.ts

@@ -0,0 +1,15 @@
+import { Type } from "typebox";
+
+/** Hands web research to the cheaper worker model; the same for the owner agent and party roles. */
+export const DELEGATE_TOOL = "delegate_task" as const;
+
+export const DELEGATE_TOOL_SPEC = {
+	name: DELEGATE_TOOL,
+	label: "Delegate task",
+	description:
+		"Hand research that needs many searches or long reading to a cheaper worker model that has only web search and page reading. It runs in the background, and its report comes back to you in this channel as a new turn, where you answer with it. The worker sees nothing but the task, so write it self-contained: the question, what the answer is for, and what to report. Answer quick lookups yourself.",
+	parameters: Type.Object({
+		title: Type.String({ description: "A short name for the task." }),
+		task: Type.String({ description: "The self-contained task." }),
+	}),
+};

package/src/core/shared/mcp-adapter.ts

@@ -0,0 +1,58 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+
+export interface McpEndpoint {
+	name: string;
+	url: string;
+	/** Absent when a proxy in front of the endpoint adds the credential. */
+	bearerToken?: string;
+}
+
+interface McpServerEntry {
+	url: string;
+	auth?: "bearer";
+	bearerToken?: string;
+	directTools: boolean;
+	lifecycle: "eager";
+	toolPrefix: "none";
+}
+
+interface McpAdapterModule {
+	createMcpAdapter(options: {
+		config: { mcpServers: Record<string, McpServerEntry> };
+	}): ExtensionFactory;
+}
+
+// pi-mcp-adapter ships TypeScript sources that fail this project's strict type check, and
+// skipLibCheck does not cover .ts files. A non-literal specifier keeps tsc from following
+// the import; the interface above declares the part the host uses.
+const ADAPTER_MODULE: string = "pi-mcp-adapter";
+const { createMcpAdapter } = (await import(ADAPTER_MODULE)) as McpAdapterModule;
+
+/**
+ * pi-mcp-adapter connected to MCP endpoints such as an MCP gateway's virtual servers. Tools
+ * register directly under their server-side names (`toolPrefix: "none"`), so the names
+ * the host activates are the names the gateway lists, and they stay within Claude's
+ * 64-character limit after claude-bridge adds its own prefix.
+ */
+export function mcpAdapterExtension(
+	endpoints: readonly McpEndpoint[],
+): ExtensionFactory {
+	return createMcpAdapter({
+		config: {
+			mcpServers: Object.fromEntries(
+				endpoints.map((endpoint) => [
+					endpoint.name,
+					{
+						url: endpoint.url,
+						...(endpoint.bearerToken
+							? { auth: "bearer" as const, bearerToken: endpoint.bearerToken }
+							: {}),
+						directTools: true,
+						lifecycle: "eager" as const,
+						toolPrefix: "none" as const,
+					},
+				]),
+			),
+		},
+	});
+}

package/src/core/shared/package-dir.ts

@@ -0,0 +1,9 @@
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+/** The installed package's folder, as Pi's `additionalExtensionPaths` takes it. */
+export function packageDir(name: string): string {
+	return dirname(require.resolve(`${name}/package.json`));
+}

package/src/core/shared/profile-tools.ts

@@ -0,0 +1,16 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Pins each run's active tools to the current profile. Inline factories load after path
+ * extensions, so this handler runs last and undoes additions such as pi-web-access
+ * re-adding web_enable or claude-bridge's AskClaude.
+ */
+export function profileToolsExtension(
+	currentTools: () => readonly string[],
+): ExtensionFactory {
+	return (pi) => {
+		pi.on("before_agent_start", () => {
+			pi.setActiveTools([...currentTools()]);
+		});
+	};
+}

package/src/core/shared/read-attachment-tool.ts

@@ -0,0 +1,43 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { READ_LIMIT, readAttachment } from "./attachment-reader.ts";
+
+/** Registers `read_attachment` over one channel's attachment store. */
+export function readAttachmentExtension(dir: string): ExtensionFactory {
+	return (pi) => {
+		pi.registerTool({
+			name: "read_attachment",
+			label: "Read attachment",
+			description:
+				"Read a text or PDF file someone attached in this channel, by the file name listed under Attachments. Long files come in pieces; pass offset to continue.",
+			parameters: Type.Object({
+				file: Type.String({
+					description: "File name from the Attachments list.",
+				}),
+				offset: Type.Optional(
+					Type.Integer({
+						minimum: 0,
+						description: "Character offset to start from.",
+					}),
+				),
+			}),
+			execute: async (_toolCallId, params) => {
+				const { text, total } = await readAttachment(
+					dir,
+					params.file,
+					params.offset ?? 0,
+				);
+				const start = params.offset ?? 0;
+				const end = start + text.length;
+				const more =
+					end < total
+						? `\n\n[${end} of ${total} characters shown; call again with offset ${end} for more]`
+						: "";
+				return {
+					content: [{ type: "text", text: `${text}${more}` }],
+					details: { total, limit: READ_LIMIT },
+				};
+			},
+		});
+	};
+}

package/src/core/shared/schedule-tools.ts

@@ -0,0 +1,118 @@
+import { type TSchema, Type } from "typebox";
+import { messages } from "../i18n/index.ts";
+import { timeZone } from "../time.ts";
+
+/**
+ * Schedule tools, the same for the owner agent and party roles. Each acts on the schedules of
+ * the channel it runs in; the host decides the channel and speaker, never the model.
+ */
+export const SCHEDULE_TOOLS = [
+	"schedule_create",
+	"schedule_list",
+	"schedule_update",
+	"schedule_cancel",
+] as const;
+export type ScheduleToolName = (typeof SCHEDULE_TOOLS)[number];
+
+export function isScheduleTool(value: string): value is ScheduleToolName {
+	return (SCHEDULE_TOOLS as readonly string[]).includes(value);
+}
+
+const timing = () => ({
+	in_minutes: Type.Optional(
+		Type.Integer({
+			minimum: 1,
+			description:
+				"Run once this many minutes from now; use it for relative times such as in two hours.",
+		}),
+	),
+	at: Type.Optional(
+		Type.String({
+			description: `Run once at this ${messages().zoneTime(timeZone())}, "YYYY-MM-DD HH:MM". Give one of in_minutes, at, or time.`,
+		}),
+	),
+	time: Type.Optional(
+		Type.String({
+			description: `Repeat at this ${messages().zoneTime(timeZone())} of day, "HH:MM".`,
+		}),
+	),
+	every_days: Type.Optional(
+		Type.Integer({
+			minimum: 1,
+			maximum: 365,
+			description: "With time: run every this many days (default 1, daily).",
+		}),
+	),
+	start_date: Type.Optional(
+		Type.String({
+			description:
+				'With every_days: the first day, "YYYY-MM-DD" (default today); later runs count from it.',
+		}),
+	),
+	weekdays: Type.Optional(
+		Type.Array(
+			Type.Union(
+				["sun", "mon", "tue", "wed", "thu", "fri", "sat"].map((d) =>
+					Type.Literal(d),
+				),
+			),
+			{
+				description: "With time: run on these weekdays instead of every_days.",
+			},
+		),
+	),
+});
+
+export interface ScheduleToolSpec {
+	name: ScheduleToolName;
+	label: string;
+	description: string;
+	parameters: TSchema;
+}
+
+export function scheduleToolSpecs(): readonly ScheduleToolSpec[] {
+	return [
+		{
+			name: "schedule_create",
+			label: "Create schedule",
+			description: `Schedule a task for yourself in this channel: at the set ${messages().zoneTime(timeZone())} you are woken with the prompt and your answer is posted here. Use it for reminders, follow-ups, and recurring checks someone asks for. Write the prompt as a complete instruction to your future self, including who it is for and what to report; it runs without the current conversation in view.`,
+			parameters: Type.Object({
+				title: Type.String({ description: "A short name for the schedule." }),
+				prompt: Type.String({
+					description: "What to do when it runs, self-contained.",
+				}),
+				...timing(),
+			}),
+		},
+		{
+			name: "schedule_list",
+			label: "List schedules",
+			description: `List this channel's schedules with their next run, and the current ${messages().zoneTime(timeZone())}. Give id to read one schedule's full prompt.`,
+			parameters: Type.Object({
+				id: Type.Optional(Type.Integer({ description: "Schedule id." })),
+			}),
+		},
+		{
+			name: "schedule_update",
+			label: "Update schedule",
+			description:
+				"Change one of this channel's schedules: its title, its prompt, or its timing (timing fields replace the old timing). A run can use this to keep its own prompt current, such as adding what it already reported.",
+			parameters: Type.Object({
+				id: Type.Integer({ description: "Schedule id." }),
+				title: Type.Optional(Type.String()),
+				prompt: Type.Optional(
+					Type.String({ description: "The whole new prompt." }),
+				),
+				...timing(),
+			}),
+		},
+		{
+			name: "schedule_cancel",
+			label: "Cancel schedule",
+			description: "Delete one of this channel's schedules.",
+			parameters: Type.Object({
+				id: Type.Integer({ description: "Schedule id." }),
+			}),
+		},
+	];
+}

package/src/core/shared/session-messages.ts

@@ -0,0 +1,50 @@
+/** An assistant message of a Pi session, as far as its final answer needs it. */
+interface AssistantLike {
+	role: "assistant";
+	content: unknown;
+	stopReason?: string;
+	errorMessage?: string;
+}
+
+/** The text parts of a message's content, joined by newlines. */
+export function textOf(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter(
+			(part): part is { type: "text"; text: string } =>
+				part?.type === "text" && typeof part.text === "string",
+		)
+		.map((part) => part.text)
+		.join("\n");
+}
+
+/**
+ * A run's last assistant message, or why there is no usable one: none at all, a failed run, or
+ * an aborted one. `aborted` names an abort that carries no error message of its own.
+ */
+export function lastAssistant<M extends { role: string }>(
+	messages: readonly M[],
+	aborted?: string,
+): { ok: true; message: M & AssistantLike } | { ok: false; error: string } {
+	const last = messages.findLast(
+		(message): message is M & AssistantLike => message.role === "assistant",
+	);
+	if (!last)
+		return { ok: false, error: "the run produced no assistant message" };
+	if (
+		last.errorMessage ||
+		last.stopReason === "error" ||
+		last.stopReason === "aborted"
+	) {
+		return {
+			ok: false,
+			error:
+				last.errorMessage ??
+				(last.stopReason === "aborted" && aborted
+					? aborted
+					: `the run stopped with ${last.stopReason}`),
+		};
+	}
+	return { ok: true, message: last };
+}

package/src/core/shared/tool-result.ts

@@ -0,0 +1,9 @@
+/** The text a tool returns, in the shape Pi expects. */
+export function toolText(text: string) {
+	return { content: [{ type: "text" as const, text }], details: {} };
+}
+
+/** A refused call's reason, which the model reads as the tool's error result. */
+export function toolError(text: string) {
+	return { ...toolText(text), isError: true };
+}

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

@@ -0,0 +1,18 @@
+import { rmSync } from "node:fs";
+import type { Server } from "bun";
+
+/**
+ * Serves HTTP on a unix socket without Bun's 10-second idle timeout, which would cut long
+ * turns and quiet model streams. Bun 1.4.2 honors `idleTimeout` on unix sockets, but its
+ * types reject the option there, hence the cast. A stale socket file is removed first.
+ */
+export function serveUnix(
+	socketPath: string,
+	fetch: (request: Request) => Response | Promise<Response>,
+): Server<undefined> {
+	rmSync(socketPath, { force: true });
+	const options = { unix: socketPath, idleTimeout: 0, fetch };
+	return Bun.serve(
+		options as unknown as Parameters<typeof Bun.serve>[0],
+	) as Server<undefined>;
+}

package/src/core/size.test.ts

@@ -0,0 +1,9 @@
+import { expect, test } from "bun:test";
+import { resolve } from "node:path";
+import { oversizedFiles } from "./testing/file-size.ts";
+
+test("no file of the core is over the size limit", () => {
+	expect(
+		oversizedFiles(resolve(import.meta.dir, "../.."), ["src/core"]),
+	).toEqual([]);
+});

package/src/core/speakers.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import { ConfigError } from "./domain/errors.ts";
+import { parseTierMembers, speakerPolicy, tierAtLeast } from "./speakers.ts";
+
+const OWNER = "100000000000000001";
+const ADMIN = "100000000000000002";
+const MEMBER = "100000000000000003";
+const ROLE = "200000000000000001";
+const STRANGER = "100000000000000009";
+const author = (id: string, roleIds: string[] = []) => ({
+	id,
+	name: `u${id.slice(-1)}`,
+	roleIds,
+});
+
+describe("speakerPolicy", () => {
+	test("names only the owner by default, so nobody else is a speaker", () => {
+		const policy = speakerPolicy({ owners: [OWNER] });
+		expect(policy.resolve(author(OWNER))?.tier).toBe("owner");
+		expect(policy.resolve(author(STRANGER, [ROLE]))).toBeUndefined();
+	});
+
+	test("admins and members come from users or roles, and the highest tier wins", () => {
+		const policy = speakerPolicy({
+			owners: [OWNER],
+			admins: { users: [ADMIN], roles: [ROLE] },
+			members: { users: [MEMBER, ADMIN] },
+		});
+		expect(policy.resolve(author(ADMIN))?.tier).toBe("admin");
+		expect(policy.resolve(author(STRANGER, [ROLE]))?.tier).toBe("admin");
+		expect(policy.resolve(author(MEMBER))?.tier).toBe("member");
+		expect(policy.resolve(author(OWNER, [ROLE]))?.tier).toBe("owner");
+		expect(policy.resolve(author(STRANGER))).toBeUndefined();
+	});
+
+	test("@everyone makes every author a member", () => {
+		const policy = speakerPolicy({
+			owners: [OWNER],
+			members: { everyone: true },
+		});
+		expect(policy.resolve(author(STRANGER))).toEqual({
+			id: STRANGER,
+			name: "u9",
+			tier: "member",
+		});
+	});
+});
+
+test("tiers order owner above admin above member", () => {
+	expect(tierAtLeast("owner", "admin")).toBe(true);
+	expect(tierAtLeast("admin", "admin")).toBe(true);
+	expect(tierAtLeast("member", "admin")).toBe(false);
+});
+
+describe("parseTierMembers", () => {
+	test("reads users, roles, and @everyone", () => {
+		expect(
+			parseTierMembers(
+				`user:${ADMIN}, role:${ROLE}, ${MEMBER}, @everyone`,
+				"X",
+				true,
+			),
+		).toEqual({ users: [ADMIN, MEMBER], roles: [ROLE], everyone: true });
+	});
+
+	test("unset or empty means nobody", () => {
+		expect(parseTierMembers(undefined, "X", true)).toBeUndefined();
+		expect(parseTierMembers(" , ", "X", true)).toBeUndefined();
+	});
+
+	test("refuses a malformed entry, and @everyone where it is not allowed", () => {
+		expect(() => parseTierMembers("nope", "X", true)).toThrow(ConfigError);
+		expect(() => parseTierMembers("group:1", "X", true)).toThrow(ConfigError);
+		expect(() => parseTierMembers("@everyone", "X", false)).toThrow(
+			/@everyone/,
+		);
+	});
+});