pi-roundtable 0.1.0

package/src/core/judging/model-judge.ts

@@ -0,0 +1,193 @@
+import type {
+	Api,
+	AssistantMessage,
+	Context,
+	Model,
+} from "@earendil-works/pi-ai";
+import type {
+	ChoiceAnswer,
+	ChoiceQuestion,
+	Judge,
+	ScoreQuestion,
+	YesNoQuestion,
+} from "../contract/providers.ts";
+import { JudgeError } from "../errors.ts";
+
+/** One completion: a system prompt and a user message in, the model's text out. */
+export type JudgeModel = (system: string, prompt: string) => Promise<string>;
+
+const SYSTEM = [
+	"You judge a situation for a chat assistant. Read the state and the question, then answer",
+	"with exactly one JSON object in the requested format: no prose, no code fence.",
+	"Every number is a probability from 0 to 1. For a yes-or-no question it is the probability",
+	"that the answer is yes, so a clear no is near 0 and a clear yes near 1.",
+].join(" ");
+
+type Json = Record<string, unknown>;
+
+// pi-lens-ignore: no-unknown-parameters — a type guard over parsed JSON
+const isRecord = (value: unknown): value is Json =>
+	typeof value === "object" && value !== null && !Array.isArray(value);
+
+// pi-lens-ignore: no-unknown-parameters — a type guard over parsed JSON
+const isProbability = (value: unknown): value is number =>
+	typeof value === "number" && value >= 0 && value <= 1;
+
+/** The one JSON object in the model's answer, tolerating a code fence or stray words around it. */
+function answerObject(text: string): Json {
+	const start = text.indexOf("{");
+	const end = text.lastIndexOf("}");
+	if (start < 0 || end < start)
+		throw new JudgeError(
+			`the judge did not answer with JSON: ${text.slice(0, 200)}`,
+		);
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text.slice(start, end + 1));
+	} catch {
+		throw new JudgeError(
+			`the judge answered malformed JSON: ${text.slice(0, 200)}`,
+		);
+	}
+	if (!isRecord(parsed))
+		throw new JudgeError("the judge's answer is not a JSON object");
+	return parsed;
+}
+
+function prompt(state: Json, question: string, format: string): string {
+	return [
+		"State:",
+		JSON.stringify(state, null, 2),
+		"",
+		question,
+		"",
+		`Answer with: ${format}`,
+	].join("\n");
+}
+
+/**
+ * The core's default judge: asks a model for each judgment instead of a hosted judging service.
+ * Answers are checked strictly, so a model that strays throws and the caller falls back.
+ */
+// pi-lens-ignore: large-class — one method per Judge question type, sharing one prompt and parser
+export class ModelJudge implements Judge {
+	readonly #complete: JudgeModel;
+
+	constructor(complete: JudgeModel) {
+		this.#complete = complete;
+	}
+
+	async #ask(state: Json, question: string, format: string): Promise<Json> {
+		return answerObject(
+			await this.#complete(SYSTEM, prompt(state, question, format)),
+		);
+	}
+
+	async askYesNo(
+		state: Json,
+		questions: Record<string, YesNoQuestion>,
+	): Promise<Record<string, number>> {
+		const names = Object.keys(questions);
+		const listed = names.map((name) => {
+			const { instructions, criteria } = questions[name] as YesNoQuestion;
+			const yes = criteria?.true ? ` Yes means: ${criteria.true}.` : "";
+			const no = criteria?.false ? ` No means: ${criteria.false}.` : "";
+			return `- ${name}: ${instructions}${yes}${no}`;
+		});
+		const answer = await this.#ask(
+			state,
+			`Answer each yes-or-no question:\n${listed.join("\n")}`,
+			`{${names.map((name) => `"${name}": <probability that the answer is yes>`).join(", ")}}`,
+		);
+		// pi-lens-ignore: no-known-value-widening — filled per question name below
+		const result: Record<string, number> = {};
+		for (const name of names) {
+			const value = answer[name];
+			if (!isProbability(value))
+				throw new JudgeError(`the judge gave no probability for ${name}`);
+			result[name] = value;
+		}
+		return result;
+	}
+
+	async askChoice(
+		state: Json,
+		name: string,
+		question: ChoiceQuestion,
+	): Promise<ChoiceAnswer> {
+		const options = Object.entries(question.criteria).map(
+			([option, criterion]) => `- ${option}: ${criterion}`,
+		);
+		const answer = await this.#ask(
+			state,
+			`${name}: ${question.instructions}\nOptions:\n${options.join("\n")}`,
+			'{"choice": "<one option name>", "confidence": <probability>}',
+		);
+		const { choice, confidence } = answer;
+		if (typeof choice !== "string" || !(choice in question.criteria))
+			throw new JudgeError(`the judge chose no listed option for ${name}`);
+		if (!isProbability(confidence))
+			throw new JudgeError(`the judge gave no confidence for ${name}`);
+		return { choice, confidence };
+	}
+
+	async askScore(
+		state: Json,
+		name: string,
+		question: ScoreQuestion,
+	): Promise<number[]> {
+		const levels = question.criteria.map(
+			(criterion, index) => `${index}. ${criterion}`,
+		);
+		const answer = await this.#ask(
+			state,
+			`${name}: ${question.instructions}\nLevels, in order:\n${levels.join("\n")}`,
+			`{"probabilities": [<one probability per level, ${levels.length} numbers, summing to 1>]}`,
+		);
+		const { probabilities } = answer;
+		if (
+			!Array.isArray(probabilities) ||
+			probabilities.length !== question.criteria.length ||
+			!probabilities.every(isProbability)
+		)
+			throw new JudgeError(
+				`the judge gave no probability per level for ${name}`,
+			);
+		const total = probabilities.reduce((sum, p) => sum + p, 0);
+		if (total <= 0)
+			throw new JudgeError(
+				`the judge's probabilities for ${name} are all zero`,
+			);
+		return probabilities.map((p) => p / total);
+	}
+}
+
+/** The text of a completed answer; an errored one throws. */
+function answerText(message: AssistantMessage): string {
+	if (message.stopReason === "error" || message.stopReason === "aborted")
+		throw new JudgeError(
+			`the judge's model failed: ${message.errorMessage ?? message.stopReason}`,
+		);
+	return message.content
+		.flatMap((part) => (part.type === "text" ? [part.text] : []))
+		.join("");
+}
+
+/** A Pi model as a judge's completion, through the runtime that holds its credentials. */
+export function piJudgeModel(
+	runtime: {
+		completeSimple(
+			model: Model<Api>,
+			context: Context,
+		): Promise<AssistantMessage>;
+	},
+	model: Model<Api>,
+): JudgeModel {
+	return async (system, text) =>
+		answerText(
+			await runtime.completeSimple(model, {
+				systemPrompt: system,
+				messages: [{ role: "user", content: text, timestamp: Date.now() }],
+			}),
+		);
+}

package/src/core/log.ts

@@ -0,0 +1,45 @@
+import pino, { type Logger } from "pino";
+
+export type { Logger };
+
+/** One log line as pino writes it: `level`, `time`, `msg`, `err`, and the logged fields. */
+export type LogEntry = Record<string, unknown>;
+
+/**
+ * JSON lines on stdout, each tagged with `app`, which journald keeps on the host. `onError`,
+ * when given, also receives every `error` and `fatal` entry; it must not throw.
+ */
+export function createLogger(
+	app: string,
+	onError?: (entry: LogEntry) => void,
+): Logger {
+	const options = {
+		base: { app },
+		level: process.env.LOG_LEVEL ?? "info",
+	};
+	if (!onError) return pino(options);
+	return pino(
+		options,
+		pino.multistream([
+			// The logger's own level filters; this stream takes whatever passes it.
+			{ level: "trace", stream: pino.destination(1) },
+			{
+				level: "error",
+				stream: {
+					write(line: string) {
+						try {
+							onError(JSON.parse(line) as LogEntry);
+						} catch {
+							// A broken sink never breaks logging.
+						}
+					},
+				},
+			},
+		]),
+	);
+}
+
+/** A logger that drops everything, for tests. */
+export function silentLogger(): Logger {
+	return pino({ level: "silent" });
+}

package/src/core/models.ts

@@ -0,0 +1,52 @@
+import { messages } from "./i18n/index.ts";
+/** Models and thinking levels as Pi names them, and the settings built on them. */
+
+export type ThinkingLevel =
+	| "off"
+	| "minimal"
+	| "low"
+	| "medium"
+	| "high"
+	| "xhigh";
+
+export const THINKING_LEVELS: readonly ThinkingLevel[] = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+];
+
+/** An agent's or the assistant's thinking setting: a fixed level, or the judge's choice each turn. */
+export const AUTO_THINKING = "auto";
+export type ThinkingSetting = ThinkingLevel | typeof AUTO_THINKING;
+
+/** A thinking setting as the owner reads it in Discord. */
+export function thinkingLabel(setting: ThinkingSetting): string {
+	return setting === AUTO_THINKING ? messages().thinkingAuto : setting;
+}
+
+/** A model as Pi's model runtime looks it up; written `<provider>/<id>`. */
+export interface ModelRef {
+	provider: string;
+	id: string;
+}
+
+/** `<provider>/<id>` as a ModelRef, or undefined when either part is missing. */
+export function parseModelRef(text: string): ModelRef | undefined {
+	const slash = text.indexOf("/");
+	if (slash <= 0 || slash === text.length - 1) return undefined;
+	return { provider: text.slice(0, slash), id: text.slice(slash + 1) };
+}
+
+export const formatModelRef = (model: ModelRef): string =>
+	`${model.provider}/${model.id}`;
+
+/** Picks one turn's thinking level from its message and the previous turn's reply and level. */
+export interface ThinkingPicker {
+	judge(
+		message: string,
+		previous?: { reply?: string; level?: ThinkingLevel },
+	): Promise<ThinkingLevel>;
+}

package/src/core/modules/background/background-turns.ts

@@ -0,0 +1,78 @@
+import type {
+	ConversationPort,
+	ScheduledOutcome,
+} from "../../contract/channels.ts";
+import type { ChannelKey } from "../../domain/conversation.ts";
+import type { Logger } from "../../log.ts";
+import { zonedStamp } from "../../time.ts";
+import {
+	type DelegationJob,
+	type DelegationOutcome,
+	delegatedTurnText,
+} from "../delegation/delegator.ts";
+import type { Schedule } from "../schedules/schedule-store.ts";
+import { scheduledTurnText } from "../schedules/schedule-tools.ts";
+
+export interface BackgroundTurnsOptions {
+	conversations: Pick<ConversationPort, "background">;
+	/** Who a turn the process itself starts, such as a logged error's report, is written by. */
+	system: { id: string; name: string };
+	logger: Logger;
+}
+
+/**
+ * Turns nobody wrote, each answered in its channel by the claim that owns it: a due schedule's,
+ * a delegated task's report, and the process's own logged error.
+ */
+export class BackgroundTurns {
+	readonly #options: BackgroundTurnsOptions;
+
+	constructor(options: BackgroundTurnsOptions) {
+		this.#options = options;
+	}
+
+	/** A due schedule's turn, run as its creator's. */
+	runScheduled(schedule: Schedule, firedAt: Date): Promise<ScheduledOutcome> {
+		return this.#options.conversations.background({
+			channel: schedule.channel,
+			mode: schedule.mode,
+			author: { id: schedule.createdById, name: schedule.createdByName },
+			tier: schedule.createdTier,
+			turnId: `schedule-${schedule.id}-${firedAt.getTime()}`,
+			text: scheduledTurnText(schedule, firedAt),
+		});
+	}
+
+	/** A delegated task's report, answered in its channel under the same rules as a schedule. */
+	async runDelegated(
+		job: DelegationJob,
+		result: DelegationOutcome,
+	): Promise<void> {
+		const outcome = await this.#options.conversations.background({
+			channel: job.channel,
+			mode: job.mode,
+			author: job.author,
+			...(job.author.tier ? { tier: job.author.tier } : {}),
+			turnId: `delegate-${job.id}-${job.startedAt.getTime()}`,
+			text: delegatedTurnText(job, result, zonedStamp(job.startedAt)),
+			report: true,
+		});
+		if (outcome.status !== "ran")
+			this.#options.logger.warn(
+				{ job: job.id, channel: job.channel, outcome },
+				"delegated report not answered",
+			);
+	}
+
+	/** The process's own logged error, reported to an agent in its channel as a report turn. */
+	runErrorReport(channel: ChannelKey, text: string): Promise<ScheduledOutcome> {
+		return this.#options.conversations.background({
+			channel,
+			mode: "owner",
+			author: this.#options.system,
+			turnId: `error-${Date.now()}`,
+			text,
+			report: true,
+		});
+	}
+}

package/src/core/modules/delegation/delegate.ts

@@ -0,0 +1,54 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { ChannelKey } from "../../domain/conversation.ts";
+import { DelegationError } from "../../domain/errors.ts";
+import type { OwnerIdentity } from "../../identity.ts";
+import { textToolsExtension } from "../../runtime/text-tools.ts";
+import { DELEGATE_TOOL_SPEC } from "../../shared/delegate-tool.ts";
+import type { Speaker } from "../../speakers.ts";
+import type { Delegator } from "./delegator.ts";
+
+export interface OwnerDelegation {
+	delegator: Pick<Delegator, "start">;
+	owner: { id: string; name: string };
+	/** The chat channel a conversation's reports go to, as for schedules. */
+	channelFor: (channel: ChannelKey) => Promise<ChannelKey>;
+}
+
+/**
+ * Registers delegate_task for one owner conversation. `origin` is the channel its turns run
+ * in, where each job's thread opens: a group's, for an agent's seat in one.
+ */
+export function delegateExtension(
+	delegation: OwnerDelegation,
+	channel: ChannelKey,
+	identity: OwnerIdentity,
+	origin: ChannelKey = channel,
+	/** The person the running turn is for; the report comes back at their tier. */
+	speaker: () => Speaker | undefined = () => undefined,
+): ExtensionFactory {
+	return textToolsExtension(
+		[
+			{
+				...DELEGATE_TOOL_SPEC,
+				run: async (input) => {
+					const { title, task } = input as { title: string; task: string };
+					const target = await delegation.channelFor(channel);
+					const job = delegation.delegator.start({
+						channel: target,
+						origin,
+						mode: "owner",
+						author: speaker() ?? delegation.owner,
+						title,
+						task,
+					});
+					const where =
+						target === channel
+							? "here"
+							: `in ${identity.name}'s Discord direct messages`;
+					return `Delegated as task #${job.id}; the report comes back ${where} as a new turn.`;
+				},
+			},
+		],
+		DelegationError,
+	);
+}

package/src/core/modules/delegation/delegator.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, test } from "bun:test";
+import type { ChannelKey } from "../../domain/conversation.ts";
+import { messages } from "../../i18n/index.ts";
+import { silentLogger } from "../../log.ts";
+import { fakeThreads } from "../../testing/thread-host.ts";
+import {
+	type DelegationJob,
+	type DelegationOutcome,
+	Delegator,
+	delegatedTurnText,
+} from "./delegator.ts";
+
+const OWNER = { id: "1", name: "Riley" };
+
+function setup(
+	run: (task: string, signal: AbortSignal) => Promise<string>,
+	timeoutMs?: number,
+) {
+	const reports: [DelegationJob, DelegationOutcome][] = [];
+	const { host, threads } = fakeThreads();
+	/** Threads already archived when each report was delivered. */
+	const archived: string[][] = [];
+	const delegator = new Delegator({
+		worker: { run },
+		deliver: async (job, outcome) => {
+			archived.push([...host.closed]);
+			reports.push([job, outcome]);
+		},
+		threads,
+		logger: silentLogger(),
+		...(timeoutMs ? { timeoutMs } : {}),
+	});
+	return { delegator, reports, host, archived };
+}
+
+const request = (channel: ChannelKey = "discord:1") => ({
+	channel,
+	mode: "party" as const,
+	author: OWNER,
+	title: "t",
+	task: "find it",
+});
+
+describe("Delegator", () => {
+	test("a report comes back with its job, after start has returned", async () => {
+		const { delegator, reports } = setup(async (task) => `report for ${task}`);
+		const job = delegator.start(request());
+		expect(reports).toEqual([]);
+		await delegator.idle();
+		expect(reports).toEqual([
+			[job, { ok: true, report: "report for find it" }],
+		]);
+	});
+
+	test("a channel holds only so many running jobs; other channels are not affected", async () => {
+		let release = () => {};
+		const gate = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		const { delegator } = setup(async () => {
+			await gate;
+			return "done";
+		});
+		delegator.start(request());
+		delegator.start(request());
+		expect(() => delegator.start(request())).toThrow("already has 2");
+		expect(delegator.start(request("discord:2")).id).toBe(3);
+		release();
+		await delegator.idle();
+		expect(delegator.start(request()).id).toBe(4);
+		await delegator.idle();
+	});
+
+	test("a failing or slow worker reports the failure", async () => {
+		const { delegator, reports } = setup(
+			(_task, signal) =>
+				new Promise((_resolve, reject) =>
+					signal.addEventListener("abort", () =>
+						reject(new Error("timed out")),
+					),
+				),
+			10,
+		);
+		delegator.start(request());
+		await delegator.idle();
+		expect(reports[0]?.[1]).toEqual({ ok: false, error: "timed out" });
+	});
+
+	test("an owner job runs in a thread of its origin, archived with the report before the turn", async () => {
+		const { delegator, reports, host, archived } = setup(async () => "R");
+		delegator.start({
+			...request("discord:dm"),
+			mode: "owner",
+			origin: "discord:10",
+			title: "check the Bun version",
+		});
+		await delegator.idle();
+		expect(host.opened).toEqual([
+			{ parentId: "10", name: "check the Bun version", id: "900" },
+		]);
+		expect(host.lines.get("10")).toBe(
+			messages().threadStarted("check the Bun version", "<#900>"),
+		);
+		expect(host.textsIn("900")).toEqual([
+			messages().delegationTask("find it"),
+			messages().delegationDone("R"),
+		]);
+		expect(archived).toEqual([["900"]]);
+		const [job, outcome] = reports[0] ?? [];
+		expect(job?.channel).toBe("discord:dm");
+		expect(
+			delegatedTurnText(
+				job as DelegationJob,
+				outcome as DelegationOutcome,
+				"x",
+			),
+		).toContain("in the thread <#900>");
+	});
+
+	test("a failed or timed-out job's thread gets the failure and is archived", async () => {
+		const { delegator, host } = setup(
+			(_task, signal) =>
+				new Promise((_resolve, reject) =>
+					signal.addEventListener("abort", () =>
+						reject(new Error("timed out")),
+					),
+				),
+			10,
+		);
+		delegator.start({ ...request(), origin: "discord:10" });
+		await delegator.idle();
+		expect(host.textsIn("900").at(-1)).toBe(
+			messages().delegationFailed("timed out"),
+		);
+		expect(host.closed).toEqual(["900"]);
+	});
+
+	test("a party job, or one whose thread cannot open, reports only in its channel", async () => {
+		const { delegator, reports, host } = setup(async () => "R");
+		delegator.start(request());
+		host.failOpen = true;
+		delegator.start({ ...request("discord:2"), origin: "discord:2" });
+		await delegator.idle();
+		expect(host.posts).toEqual([]);
+		expect(reports.map(([job]) => job.thread)).toEqual([undefined, undefined]);
+		expect(reports.map(([, outcome]) => outcome.ok)).toEqual([true, true]);
+	});
+
+	test("an empty task is refused", () => {
+		const { delegator } = setup(async () => "x");
+		expect(() => delegator.start({ ...request(), task: " " })).toThrow(
+			"required",
+		);
+	});
+
+	test("the report turn carries the task and the report", () => {
+		const job: DelegationJob = { ...request(), id: 5, startedAt: new Date(0) };
+		const text = delegatedTurnText(
+			job,
+			{ ok: true, report: "R" },
+			"2026-09-27 01:00",
+		);
+		expect(text).toContain("## Delegated task #5: t");
+		expect(text).toContain("### Task\nfind it");
+		expect(text).toContain("### Report\nR");
+		expect(delegatedTurnText(job, { ok: false, error: "boom" }, "x")).toContain(
+			"failed: boom",
+		);
+	});
+});