pi-roundtable 0.16.0 → 0.17.1

package/src/core/identity/identity-plugin.ts

@@ -1,3 +1,4 @@
+import { isCheckDatabase } from "../db/check-database.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
 import { IDENTITY, IDENTITY_LINKS } from "../services.ts";
 import type { AccessRules } from "./access-policy.ts";
@@ -45,12 +46,16 @@ export function identityPlugin(options: IdentityOptions): RoundtablePlugin {
 		provides: rules.selfLink ? [IDENTITY, IDENTITY_LINKS] : [IDENTITY],
 		setup: async ({ database, services, logger }) => {
 			if (summary) logger.info(backfillLine(summary));
+			const sql = database();
 			const identity = new PgIdentityService(
-				await PgPrincipalStore.attach(database()),
+				await PgPrincipalStore.attach(sql),
 				rules,
 				{ logger, identities },
 			);
-			await identity.syncConfig();
+			// `Roundtable.check()` has no database to write the configured principals to: it asks
+			// only what the configuration and the declared identities settle without one.
+			if (isCheckDatabase(sql)) identity.checkConfig();
+			else await identity.syncConfig();
 			services.provide(IDENTITY, identityView(identity));
 			if (rules.selfLink)
 				services.provide(

package/src/core/identity/identity-service.ts

@@ -15,10 +15,11 @@ import {
 	surfaceOf,
 } from "./actor-facts.ts";
 import { CachingPrincipalStore } from "./caching-principal-store.ts";
-import { configuredOwnerId } from "./config-owner.ts";
+import { configuredOwnerId, refuseOwnerDeclarations } from "./config-owner.ts";
 import type { Contact, ContactAssessor } from "./contact.ts";
 import {
 	type DeclaredIdentity,
+	refuseUnboundIdentities,
 	syncDeclaredIdentities,
 } from "./plugin-identities.ts";
 import { highest, lowest, publicOf, speakerOf } from "./principal-reads.ts";
@@ -141,6 +142,12 @@ export class PgIdentityService implements IdentityService, ContactAssessor {
 		this.#logger = options.logger;
 	}
 
+	/** The refusals `syncConfig` makes from the configuration and the declarations alone, for `Roundtable.check()`. */
+	checkConfig(): void {
+		refuseUnboundIdentities(this.#declared, this.#rules.owners.length > 0);
+		refuseOwnerDeclarations(this.#rules.owners, this.#declared);
+	}
+
 	/**
 	 * Makes the stored owners match the configuration: each configured owner's principal made or
 	 * renamed, their identities linked, and the owner role granted, all as the configuration's;

package/src/core/identity/plugin-identities.ts

@@ -57,6 +57,21 @@ export function declaredIdentities(
 	return declared;
 }
 
+/**
+ * The refusal `syncDeclaredIdentities` makes that needs no stored principal: an identity that names
+ * no principal when the configuration lists no primary owner to bind it to.
+ */
+export function refuseUnboundIdentities(
+	identities: readonly DeclaredIdentity[],
+	hasPrimaryOwner: boolean,
+): void {
+	for (const { plugin, identity, principal } of identities)
+		if (principal === undefined && !hasPrimaryOwner)
+			throw new ConfigError(
+				`plugin ${plugin}: ${identity} names no principal, and access.owners lists no primary owner to bind it to. Give the plugin the principal it stands for.`,
+			);
+}
+
 /**
  * Links each identity a plugin declares to its principal, `primaryOwner` by default, as the
  * plugin's: one the plugins bound to another principal at an earlier boot moves, one the
@@ -76,10 +91,10 @@ export async function syncDeclaredIdentities(
 		const ref = parseIdentity(identity);
 		if (!ref) throw new ConfigError(`plugin ${plugin}: ${identity}`);
 		const id = principal ?? primaryOwner;
-		if (id === undefined)
-			throw new ConfigError(
-				`plugin ${plugin}: ${identity} names no principal, and access.owners lists no primary owner to bind it to. Give the plugin the principal it stands for.`,
-			);
+		if (id === undefined) {
+			refuseUnboundIdentities([{ plugin, identity, principal }], false);
+			continue;
+		}
 		if (id === SYSTEM_PRINCIPAL || !(await store.get(id)))
 			throw new ConfigError(
 				`plugin ${plugin}: ${identity} is bound to principal ${id}, and there is no principal ${id}. roundtable principal list shows the principals, and roundtable principal create makes one.`,

package/src/core/modules/skills/skill-store.ts

@@ -1,4 +1,5 @@
 import type { SQL } from "bun";
+import { isCheckDatabase } from "../../db/check-database.ts";
 import { scopeToGuild } from "../../db/guild-scope.ts";
 import type { Migration } from "../../db/migrations.ts";
 import { AgentError } from "../../domain/errors.ts";
@@ -128,7 +129,8 @@ export class SkillStore {
 	/** The store over the host's migrated pool; the skills agents carry are those of one guild. */
 	static async attach(sql: SQL, guildId: string): Promise<SkillStore> {
 		const store = new SkillStore(sql, guildId);
-		await store.#reload();
+		// `Roundtable.check()` has no database to read the rows from: the store starts empty.
+		if (!isCheckDatabase(sql)) await store.#reload();
 		return store;
 	}
 

package/src/core/runtime/extensions/surface-formatting.ts

@@ -0,0 +1,22 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Appends the formatting guidance of the surface the running turn replies on to the system
+ * prompt's appended part before each run, after the persona and what earlier handlers appended.
+ * Nothing is added when `guidance` returns undefined or only blank text: a turn whose channel has
+ * no surface, a surface without guidance, or no turn running.
+ */
+export function surfaceFormattingExtension(
+	guidance: () => string | undefined,
+): ExtensionFactory {
+	return (pi) => {
+		pi.on("before_agent_start", (event) => {
+			const text = guidance();
+			if (text === undefined || text.trim() === "") return;
+			const appended = event.systemPromptOptions.appendSystemPrompt;
+			event.systemPromptOptions.appendSystemPrompt = appended
+				? `${appended}\n\n${text}`
+				: text;
+		});
+	};
+}

package/src/core/runtime/pi-agent-runtime.ts

@@ -33,9 +33,9 @@ import { loadsMemory } from "./extensions/private-memory.ts";
 import { missingToolsError } from "./extensions/self-compact-guard.ts";
 import { interimPoster } from "./interim-text.ts";
 import { preflightTools } from "./preflight-tools.ts";
-import { PromptSlot, workTimeout } from "./prompt-slot.ts";
+import { PromptSlot } from "./prompt-slot.ts";
 import { carriesMemory, recordMemoryTurn } from "./reader-history.ts";
-import type { RunningTurn } from "./running-turn.ts";
+import { type RunningTurn, runningTurn } from "./running-turn.ts";
 import type { PiAgentRuntimeOptions, TurnMessage } from "./runtime-types.ts";
 import { archiveSessions } from "./session-archive.ts";
 import {
@@ -48,6 +48,7 @@ import { promptImages, SteerableRun } from "./steerable-run.ts";
 import { thinkingLevel } from "./thinking-level.ts";
 import { runningCalls } from "./tool-call-scope.ts";
 import { transcriptOf, turnAnswer, unspokenTurn } from "./turn-answer.ts";
+import { runtimeTurnBudget, type TurnBudget } from "./turn-budget.ts";
 import { progressReporter } from "./turn-progress.ts";
 import { wrapUpTurn } from "./turn-wrapup.ts";
 import { workerReport } from "./worker-task.ts";
@@ -75,6 +76,8 @@ export class PiAgentRuntime implements AgentRuntime {
 	readonly #turns = new Map<ChannelKey, RunningTurn>();
 	/** Each conversation's turn in progress, which the owner may steer or stop. */
 	readonly #running = new Map<ChannelKey, SteerableRun>();
+	/** Each running turn's time limit, which a steered message renews. */
+	readonly #budgets = new Map<ChannelKey, TurnBudget>();
 	readonly #memoryTurns = new Map<ChannelKey, () => void>();
 
 	/** Builds the runtime without starting a session; the preflight proves it can run. */
@@ -86,6 +89,10 @@ export class PiAgentRuntime implements AgentRuntime {
 			speaker: (channel) => this.#turns.get(channel)?.speaker,
 			origin: (channel) => this.#turns.get(channel)?.origin,
 			client: (channel) => this.#turns.get(channel)?.client,
+			formatting: (channel) => {
+				const reply = this.#turns.get(channel)?.channel;
+				return reply === undefined ? undefined : options.formatting?.(reply);
+			},
 			withholdsMemory: (channel) => this.#turns.get(channel)?.withheld === true,
 			runTask: (scope, task) => this.#runTask(scope, task),
 		});
@@ -110,7 +117,7 @@ export class PiAgentRuntime implements AgentRuntime {
 
 	// pi-lens-ignore: high-complexity, high-fan-out, mixed-async-styles — one turn's lifecycle end to end; batch 4 splits it with the channel router
 	async runTurn(request: TurnRequest): Promise<TurnResult> {
-		const { logger, turnTimeoutMs = 10 * 60_000 } = this.#options;
+		const { logger } = this.#options;
 		if (!request.speaker) return unspokenTurn();
 		// A turn that is only asked for now, such as a group's next member, starts nothing.
 		if (this.#options.stopping?.())
@@ -195,13 +202,7 @@ export class PiAgentRuntime implements AgentRuntime {
 				loadsMemory(registered),
 		);
 		this.#memoryTurns.set(key, markPrivateMemory);
-		this.#turns.set(key, {
-			tier,
-			speaker: request.speaker,
-			...(request.origin === undefined ? {} : { origin: request.origin }),
-			...(request.client === undefined ? {} : { client: request.client }),
-			withheld,
-		});
+		this.#turns.set(key, runningTurn(request, tier, withheld));
 		const missing = wanted.filter((name) => !registered.has(name));
 		if (missing.length > 0) {
 			logger.warn(
@@ -274,17 +275,14 @@ export class PiAgentRuntime implements AgentRuntime {
 				this.#sessions.drop(key, channelSession);
 			},
 		});
-		// Time spent waiting on the owner's cards does not count towards the timeout.
-		const cancelTimeout = workTimeout(turnTimeoutMs, slot, () => {
-			logger.warn(
-				{ channel: request.channel, turnTimeoutMs },
-				"turn timed out; aborting",
-			);
-			guard.abort();
-		});
+		// Time spent waiting on the owner's cards does not count towards the timeout or the cap.
+		const budget = runtimeTurnBudget(this.#options, slot, request.channel, () =>
+			guard.abort(),
+		);
+		this.#budgets.set(key, budget);
 		const running = new SteerableRun(
 			session,
-			() => request.steerable === true && !gate.pending(),
+			() => request.steerable === true && !gate.pending() && !budget.capped(),
 			() => guard.abort(),
 		);
 		this.#running.set(key, running);
@@ -315,9 +313,10 @@ export class PiAgentRuntime implements AgentRuntime {
 			};
 		} finally {
 			this.#running.delete(key);
+			this.#budgets.delete(key);
 			this.#turns.delete(key);
 			this.#memoryTurns.delete(key);
-			cancelTimeout();
+			budget.cancel();
 			guard.release();
 			slot.unbind();
 			unsubscribe();
@@ -360,8 +359,10 @@ export class PiAgentRuntime implements AgentRuntime {
 				withAttachmentsBlock(text, attachments),
 				promptImages(attachments),
 			);
-			if (steered)
+			if (steered) {
 				this.#options.logger.info({ channel }, "message steered into the turn");
+				this.#budgets.get(channel)?.renew();
+			}
 			return steered;
 		} catch (error) {
 			this.#options.logger.warn({ channel, err: error }, "steer refused");

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

@@ -1,8 +1,11 @@
 import type { ClientPort } from "../domain/client.ts";
+import type { TurnRequest } from "../domain/ports.ts";
 import type { Speaker, Tier } from "../speakers.ts";
 
 /** What the runtime keeps about a conversation's running turn, for its tools to read. */
 export interface RunningTurn {
+	/** The channel the turn replies in, as `TurnRequest.channel` says; its surface formats the reply. */
+	channel: TurnRequest["channel"];
 	tier: Tier;
 	speaker: Speaker;
 	/** Where the turn's request came from, as `TurnRequest.origin` says. */
@@ -12,3 +15,19 @@ export interface RunningTurn {
 	/** Whether the turn loads no memory. */
 	withheld: boolean;
 }
+
+/** The record of a turn that starts: what its tools read while it runs. */
+export function runningTurn(
+	request: TurnRequest,
+	tier: Tier,
+	withheld: boolean,
+): RunningTurn {
+	return {
+		channel: request.channel,
+		tier,
+		speaker: request.speaker,
+		...(request.origin === undefined ? {} : { origin: request.origin }),
+		...(request.client === undefined ? {} : { client: request.client }),
+		withheld,
+	};
+}

package/src/core/runtime/runtime-plugin.ts

@@ -129,6 +129,8 @@ export function runtimePlugin(
 			const prompts = (channel: ChannelKey, scope?: PromptScope | Speaker) =>
 				context.surfaces.prompts(channel, scope);
 			const agents = () => options.agents?.current();
+			const formatting = (channel: ChannelKey) =>
+				context.surfaces.of(channel)?.formatting;
 			const running: AgentRuntime = providers.filled.has("runtime")
 				? providers.runtime(
 						runtimeDeps({
@@ -138,6 +140,7 @@ export function runtimePlugin(
 							sessions: context.sessions,
 							toolTiers: context.toolTiers,
 							prompts,
+							formatting,
 							agents,
 							confirmations: heldActions,
 							judge: providers.judge,
@@ -182,6 +185,7 @@ export function runtimePlugin(
 							return agents();
 						},
 						prompts,
+						formatting,
 						logger,
 						...(options.interimText
 							? { interimText: options.interimText }

package/src/core/runtime/runtime-types.ts

@@ -79,10 +79,27 @@ export interface PiAgentRuntimeOptions {
 	 * held action waits for a message that approves it.
 	 */
 	prompts?: (channel: ChannelKey, scope?: PromptScope) => Prompts | undefined;
+	/**
+	 * The formatting guidance of the chat surface that serves a channel, such as
+	 * `ChatSurface.formatting`; undefined for a channel with no surface or no guidance. Read before
+	 * each run for the channel the turn replies in, and appended to the system prompt after the
+	 * persona.
+	 */
+	formatting?: (channel: ChannelKey) => string | undefined;
 	/** The lowest tier that may use each tool; the default names the core's tools and leaves the rest to the owner. */
 	toolTiers?: ToolTiers;
-	/** A run that takes longer, not counting time spent waiting on the owner's cards, is aborted and reported as failed. */
+	/**
+	 * A run that works longer, not counting time spent waiting on the owner's cards, is aborted and
+	 * reported as failed; default 10 minutes. Each message steered into the turn gives it this
+	 * budget again from that moment, up to `turnMaxMs`.
+	 */
 	turnTimeoutMs?: number;
+	/**
+	 * The most one turn may work in all, however often it is steered, not counting time spent
+	 * waiting on the owner's cards; default three times `turnTimeoutMs`. Once it is reached the turn
+	 * takes no more steering (the message waits for the next turn) and is aborted as on its timeout.
+	 */
+	turnMaxMs?: number;
 	/**
 	 * How long a turn that was aborted, by its timeout or a stop, gets to end before its session is
 	 * disposed of and the turn is reported failed; default 15 seconds. A model that ignores the
@@ -124,13 +141,16 @@ export interface CoreExtensions {
 	askUser: ExtensionFactory;
 	selfCompactGuard: ExtensionFactory;
 	privateMemory: ExtensionFactory;
+	/** The formatting guidance of the surface the turn replies on, appended after the persona. */
+	surfaceFormatting: ExtensionFactory;
 	activeTools: ExtensionFactory;
 }
 
 /**
  * A session's extensions in load order: the tools phase, the core's attachment, gate, ask-user,
  * and compact guard, the compactor, the MCP phase, the memory projection, so each request is
- * projected after every other extension changed it, and active-tools last, so its
+ * projected after every other extension changed it, the surface's formatting guidance, so it follows
+ * the persona and everything appended before it, and active-tools last, so its
  * before_agent_start handler runs after every other extension's.
  */
 export function sessionExtensions(
@@ -160,6 +180,7 @@ export function sessionExtensions(
 		...contributed(plan.compaction ? [plan.compaction] : []),
 		...contributed(plan.mcp),
 		{ name: "private-memory", factory: core.privateMemory },
+		{ name: "surface-formatting", factory: core.surfaceFormatting },
 		{ name: "active-tools", factory: core.activeTools },
 	];
 }

package/src/core/runtime/session-factory.ts

@@ -58,6 +58,7 @@ import {
 	COMPACT_TOOL,
 	selfCompactGuardExtension,
 } from "./extensions/self-compact-guard.ts";
+import { surfaceFormattingExtension } from "./extensions/surface-formatting.ts";
 import type { PromptSlot } from "./prompt-slot.ts";
 import type {
 	ChannelSession,
@@ -85,6 +86,8 @@ export interface SessionFactoryDeps {
 	origin(channel: ChannelKey): string | undefined;
 	/** What the client that started the conversation's running turn can do for its tools. */
 	client(channel: ChannelKey): ClientPort | undefined;
+	/** The formatting guidance of the surface the conversation's running turn replies on. */
+	formatting(channel: ChannelKey): string | undefined;
 	/** Whether the conversation's running turn loads no memory, as the agent server's option keeps a speaker out of it. */
 	withholdsMemory(channel: ChannelKey): boolean;
 	/**
@@ -416,6 +419,10 @@ export class SessionFactory {
 							: memoryReader(conversation, deps.speaker(turnKey)),
 					state.draws,
 				),
+				surfaceFormatting: surfaceFormattingExtension(() =>
+					// A worker writes a report for the turn, not a reply on its surface.
+					worker ? undefined : deps.formatting(turnKey),
+				),
 				activeTools: activeToolsExtension(() => state.tools),
 			}),
 			// An agent's prompt is set before each run by the agent-prompt extension.

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

@@ -0,0 +1,112 @@
+import type { ChannelKey } from "../sessions.ts";
+import type { PromptSlot } from "./prompt-slot.ts";
+import type { PiAgentRuntimeOptions } from "./runtime-types.ts";
+
+/** Which limit ended a turn: its budget since the start or the last steer, or its cap. */
+export type TurnLimit = "turn" | "turnMax";
+
+/** A turn's time limit, which a steered message renews up to a cap on the whole turn. */
+export interface TurnBudget {
+	/**
+	 * Gives the turn its full budget again from now, up to the cap; the work time left, in ms,
+	 * or undefined when the cap is reached and the turn takes no more steering.
+	 */
+	renew(): number | undefined;
+	/** Whether the turn has worked up to its cap. */
+	capped(): boolean;
+	cancel(): void;
+}
+
+/** The clock a turn budget reads; the real one by default, a fake one in tests. */
+export interface BudgetClock {
+	now(): number;
+	schedule(run: () => void, ms: number): () => void;
+}
+
+const REAL_CLOCK: BudgetClock = {
+	now: () => Date.now(),
+	schedule: (run, ms) => {
+		const timer = setTimeout(run, ms);
+		return () => clearTimeout(timer);
+	},
+};
+
+/**
+ * Calls `expire` once the turn has worked `ms` since it started or since its last renewal, or
+ * `maxMs` in all, whichever comes first; time the slot spent waiting on the owner's cards counts
+ * towards neither. `expire` is told which limit fired.
+ */
+export function turnBudget(
+	ms: number,
+	maxMs: number,
+	slot: Pick<PromptSlot, "waitedMs">,
+	expire: (limit: TurnLimit) => void,
+	clock: BudgetClock = REAL_CLOCK,
+): TurnBudget {
+	const started = clock.now();
+	const worked = () => {
+		const now = clock.now();
+		return now - started - slot.waitedMs(now);
+	};
+	let deadline = Math.min(ms, maxMs);
+	let cancelTimer: (() => void) | undefined;
+	let expired = false;
+	const arm = (delay: number) => {
+		cancelTimer = clock.schedule(() => {
+			const left = deadline - worked();
+			if (left > 0) return arm(left);
+			expired = true;
+			expire(deadline >= maxMs ? "turnMax" : "turn");
+		}, delay);
+	};
+	arm(deadline);
+	return {
+		renew() {
+			const now = worked();
+			if (expired || now >= maxMs) return undefined;
+			deadline = Math.min(now + ms, maxMs);
+			cancelTimer?.();
+			arm(deadline - now);
+			return deadline - now;
+		},
+		capped: () => expired || worked() >= maxMs,
+		cancel: () => cancelTimer?.(),
+	};
+}
+
+/**
+ * The time limit of one turn of the built-in runtime, from its options: `turnTimeoutMs` (default
+ * 10 minutes) renewed by each steer up to `turnMaxMs` (default three times that). It logs each
+ * renewal and, when a limit fires, which one before it calls `abort`.
+ */
+export function runtimeTurnBudget(
+	options: Pick<
+		PiAgentRuntimeOptions,
+		"turnTimeoutMs" | "turnMaxMs" | "logger"
+	>,
+	slot: Pick<PromptSlot, "waitedMs">,
+	channel: ChannelKey,
+	abort: () => void,
+): TurnBudget {
+	const { logger, turnTimeoutMs = 10 * 60_000 } = options;
+	const turnMaxMs = options.turnMaxMs ?? 3 * turnTimeoutMs;
+	const budget = turnBudget(turnTimeoutMs, turnMaxMs, slot, (limit) => {
+		logger.warn(
+			{ channel, limit, turnTimeoutMs, turnMaxMs },
+			"turn timed out; aborting",
+		);
+		abort();
+	});
+	return {
+		...budget,
+		renew() {
+			const deadlineMs = budget.renew();
+			if (deadlineMs !== undefined)
+				logger.info(
+					{ channel, deadlineMs },
+					"steer renewed the turn's time budget",
+				);
+			return deadlineMs;
+		},
+	};
+}

package/src/core/testing/database.ts

@@ -9,9 +9,27 @@ const url = process.env.ROUNDTABLE_TEST_DATABASE_URL;
 /** The guild the stores of the tests serve. */
 export const TEST_GUILD = "900000000000000001";
 
-export const testDatabaseUrl = url ?? "";
+/** The test database's URL, or "" when the run has none; `usePostgresForTests` sets it for the rest of the run. */
+export let testDatabaseUrl = url ?? "";
 
-export const describeDb = url ? describe : describe.skip;
+/** `describe` when the run has a test database, `describe.skip` otherwise; `usePostgresForTests` switches it on. */
+export let describeDb = url ? describe : describe.skip;
+
+/** Makes `url` the run's test database, for the tests and suites that read the two exports above afterwards. */
+export function adoptTestDatabase(url: string): void {
+	process.env.ROUNDTABLE_TEST_DATABASE_URL = url;
+	testDatabaseUrl = url;
+	describeDb = describe;
+}
+
+/** The test database's URL; throws, naming how to provide one, when the run has none. */
+export function requireDatabase(): string {
+	if (!testDatabaseUrl)
+		throw new Error(
+			"this test needs PostgreSQL: set ROUNDTABLE_TEST_DATABASE_URL to a throwaway database, or start one for the run with usePostgresForTests() in a test preload (it needs initdb and postgres on PATH or in PG_BIN)",
+		);
+	return testDatabaseUrl;
+}
 
 /** A test pool with the migrations run, as the host runs them before any store attaches; the caller closes it. */
 export async function migratedPool(...migrations: Migration[]): Promise<SQL> {