pi-roundtable 0.7.19 → 0.8.0

package/src/core/ops/error-reporter.ts

@@ -19,20 +19,28 @@ const OWN_KEYS = new Set(["level", "time", "pid", "hostname", "msg", "err"]);
 const HEAD_KEYS = ["app", "plugin", "module"];
 const APP_FRAME = /((?:src|shared|worker)\/[^\s():]+\.ts):(\d+)/;
 
-/** Where the reports go, known once the Discord surface and the agent team are up. */
+/** Who investigates the errors: an agent, in its channel, or the claim of one conversation. */
+export type ErrorReportDestination =
+	| { agent: string }
+	| { conversation: ChannelKey };
+
+/** How the reports are delivered, known once the surfaces, and for an agent the team, are up. */
 export interface ErrorReportDelivery {
-	/** The agent's channel while it is active; undefined for an archived or unknown agent. */
-	channelOf(agent: string): ChannelKey | undefined;
-	/** The visible message in the agent's channel. */
+	/**
+	 * The agent's channel while it is active; undefined for an archived or unknown agent. Asked
+	 * only for an agent's reports.
+	 */
+	channelOf?(agent: string): ChannelKey | undefined;
+	/** The visible message in the channel. */
 	post(channel: ChannelKey, text: string): Promise<void>;
-	/** The agent's report turn; resolves when it has run. */
+	/** The report turn; resolves when it has run. */
 	turn(channel: ChannelKey, text: string): Promise<ScheduledOutcome>;
 	logger: Logger;
 }
 
 export interface ErrorReporterOptions {
-	/** The agent that investigates the errors, reported in its channel. */
-	opsAgent: string;
+	/** Who investigates the errors. */
+	destination: ErrorReportDestination;
 	/** The name the reports give the process, such as "Roundtable". */
 	app: string;
 	ignored?: readonly RegExp[];
@@ -43,14 +51,14 @@ export interface ErrorReporterOptions {
 }
 
 /**
- * The process's own `error` and `fatal` log entries, each reported to the ops agent as a visible
- * message and a report turn in its channel. The same error goes at most once an hour, and at
+ * The process's own `error` and `fatal` log entries, each reported to the ops agent or the ops
+ * conversation as a visible message and a report turn in its channel. The same error goes at most once an hour, and at
  * most five reports an hour overall; the rest are counted and summed up in one report when the
  * hour allows. Errors from the reporting itself are only logged; errors logged elsewhere while
  * an error-report turn runs are counted and summed up once it ends.
  */
 export class ErrorReporter {
-	readonly #opsAgent: string;
+	readonly destination: ErrorReportDestination;
 	readonly #app: string;
 	readonly #ignored: readonly RegExp[];
 	readonly #now: () => number;
@@ -68,7 +76,7 @@ export class ErrorReporter {
 	#summaryDue = false;
 
 	constructor(options: ErrorReporterOptions) {
-		this.#opsAgent = options.opsAgent;
+		this.destination = options.destination;
 		this.#app = options.app;
 		this.#ignored = options.ignored ?? IGNORED_ERRORS;
 		this.#now = options.now ?? Date.now;
@@ -177,7 +185,11 @@ export class ErrorReporter {
 		const delivery = this.#delivery;
 		if (!delivery) return Promise.resolve();
 		return this.#reporting.run(true, async () => {
-			const channel = delivery.channelOf(this.#opsAgent);
+			const { destination } = this;
+			const channel =
+				"conversation" in destination
+					? destination.conversation
+					: delivery.channelOf?.(destination.agent);
 			if (!channel) return;
 			try {
 				await delivery.post(channel, text);

package/src/core/plugin.ts

@@ -11,6 +11,7 @@ import type { ServiceKey, Services } from "./contract/services.ts";
 import type { ChatSurface, SurfacePort } from "./contract/surface.ts";
 import type { Migration } from "./db/migrations.ts";
 import type { ToolContribution } from "./define.ts";
+import type { TurnProgress } from "./domain/progress.ts";
 import { PluginError } from "./errors.ts";
 import type { HoldCheck, HoldRule } from "./holds.ts";
 import type { HttpRoute } from "./http/listeners.ts";
@@ -75,6 +76,11 @@ export interface TurnEndEvent extends TurnEvent {
 	result: "ok" | "failed" | "stopped";
 }
 
+/** What a running turn wrote or ran, as a handler hears of it, between its start and its end. */
+export interface TurnProgressEvent extends TurnEvent {
+	progress: TurnProgress;
+}
+
 /** What a plugin may react to; a handler that throws is logged and never stops the others. */
 export interface EventHandlers {
 	/**
@@ -87,6 +93,12 @@ export interface EventHandlers {
 	turnStarted?(turn: TurnEvent): Promise<void> | void;
 	/** A turn that began ended, however it ended. */
 	turnEnded?(turn: TurnEndEvent): Promise<void> | void;
+	/**
+	 * A turn run through `context.turns` wrote text or ran a tool, as it goes: text joined over a
+	 * short interval, and each tool's name with a short preview of its arguments. Turns on a runtime
+	 * without live progress report none.
+	 */
+	turnProgress?(event: TurnProgressEvent): Promise<void> | void;
 	/** The team changed: an agent or group was created, edited, arranged, archived, or started over. */
 	changed?(): Promise<void> | void;
 	/** The shutdown drain ended, before any service stops; `left` is the work it gave up on. */
@@ -97,6 +109,8 @@ export interface EventHandlers {
 export interface EventSink {
 	turnStarted(turn: TurnEvent): void;
 	turnEnded(turn: TurnEndEvent): void;
+	/** Optional, so a sink of your own written before it still fits. */
+	turnProgress?(event: TurnProgressEvent): void;
 	changed(): void;
 }
 

package/src/core/registry/providers.ts

@@ -35,7 +35,7 @@ function defaults(judgeModel: JudgeModel | undefined): Providers {
 		},
 		runtime: () => {
 			throw new ProviderError(
-				"no runtime provider is configured: the agent server builds the Pi runtime when no plugin fills the runtime slot",
+				"no runtime provider is configured: the runtime plugin builds the Pi runtime when no plugin fills the runtime slot; read the running one from services.get(RUNTIME)",
 			);
 		},
 	};

package/src/core/routing/channel-router.ts

@@ -168,4 +168,12 @@ export class ChannelRouter implements ConversationPort {
 	postsInPlace(channel: ChannelKey): boolean {
 		return this.#owner(channel)?.postsInPlace === true;
 	}
+
+	owns(channel: ChannelKey): boolean {
+		return this.#owner(channel) !== undefined;
+	}
+
+	takesBackground(channel: ChannelKey): boolean {
+		return this.#owner(channel)?.background !== undefined;
+	}
 }

package/src/core/routing/conversation-turns.ts

@@ -1,7 +1,13 @@
 import type { AgentRuntime } from "../contract/runtime.ts";
 import type { SurfacePort } from "../contract/surface.ts";
+import type {
+	ConversationRegistry,
+	ConversationVisibility,
+} from "../conversations/conversation-registry.ts";
 import type { TurnAttachments } from "../domain/attachment.ts";
 import type { TurnResult } from "../domain/conversation.ts";
+import type { TurnProgress } from "../domain/progress.ts";
+import { PluginError } from "../errors.ts";
 import { messages } from "../i18n/index.ts";
 import type { Logger } from "../log.ts";
 import type { EventSink } from "../plugin.ts";
@@ -36,6 +42,11 @@ export interface ConversationTurnInput {
 	 * notice); the claim formats its own. A throw is logged, never rethrown.
 	 */
 	reply?(result: TurnResult): Promise<void>;
+	/**
+	 * How the conversation is recorded at its first turn: `private` to the speaker, or `shared`
+	 * (the default). Later turns keep what the first recorded, and give a title only then.
+	 */
+	conversation?: { visibility: ConversationVisibility; title?: string };
 }
 
 /**
@@ -48,7 +59,11 @@ export interface ConversationTurns {
 	 * task. It shows typing and the stop control on the channel's surface, emits `turnStarted` and
 	 * `turnEnded` with the turn's `kind`, settles a runtime that throws into a failed result, and
 	 * posts the reply, or a failure or stopped notice, through the surface unless `reply` is given.
-	 * It rejects during setup (NotLinkedError) and when the host has no runtime to run the turn on.
+	 * It rejects during setup (NotLinkedError), when the host has no runtime to run the turn on,
+	 * and when the conversation cannot be recorded in the host's registry (a database error, or a
+	 * `private` conversation without a speaker). Each of these rejects before the turn starts:
+	 * nothing is shown, no event is emitted, and `reply` is not called, so a claim that answers
+	 * its person tells them itself.
 	 */
 	run(input: ConversationTurnInput): Promise<TurnResult>;
 }
@@ -58,6 +73,8 @@ export interface ConversationTurnsOptions {
 	linked: () => void;
 	/** The runtime that runs the turn; throws PluginError when the host has none yet. */
 	runtime: () => AgentRuntime;
+	/** Where each turn records its conversation; absent, or undefined, records none. */
+	registry?: () => Pick<ConversationRegistry, "register"> | undefined;
 	surfaces: SurfacePort;
 	events: EventSink;
 	/** The plugins' agent selection, read at each turn that gives none of its own. */
@@ -68,6 +85,27 @@ export interface ConversationTurnsOptions {
 /** The selection of a turn that gives none: the plugins' `agentSelection`. */
 const DEFAULT_SELECTION = "turns";
 
+/** Records the conversation of a turn: private to the speaker when asked, else shared. */
+async function record(
+	registry: Pick<ConversationRegistry, "register"> | undefined,
+	input: ConversationTurnInput,
+): Promise<void> {
+	if (!registry) return;
+	const visibility = input.conversation?.visibility ?? "shared";
+	if (visibility === "private" && !input.speaker)
+		throw new PluginError(
+			`a private conversation needs the speaker it belongs to; ${input.channel} was run without one.`,
+		);
+	const title = input.conversation?.title;
+	await registry.register({
+		key: input.channel,
+		kind: input.kind,
+		visibility,
+		...(visibility === "private" ? { principalId: input.speaker.id } : {}),
+		...(title === undefined ? {} : { title }),
+	});
+}
+
 export function conversationTurns(
 	options: ConversationTurnsOptions,
 ): ConversationTurns {
@@ -78,12 +116,26 @@ export function conversationTurns(
 			options.linked();
 			// A host without a runtime is a setup mistake, so it is refused before anything is shown.
 			const runtime = options.runtime();
+			// A conversation that cannot be recorded runs no turn: who it belongs to would be lost.
+			await record(options.registry?.(), input);
 			const stopTyping = surfaces.startTyping(channel);
 			const hideStop = surfaces.showStop(channel);
 			const turn = { kind, channel, speaker };
 			events.turnStarted(turn);
 			// A claim that posts its own reply formats its own text, so only the default reply posts as it goes.
 			const interim = input.reply ? undefined : surfaces.interim(channel);
+			// What the runtime reports as it goes reaches the surface and the handlers until the turn ends.
+			let live = true;
+			const progress = (event: TurnProgress) => {
+				if (!live) return;
+				events.turnProgress?.({ ...turn, progress: event });
+				// pi-lens-ignore: no-unknown-parameters — a rejection reason is unknown; it only reaches the logger
+				surfaces
+					.progress?.(channel, event)
+					?.catch((error: unknown) =>
+						logger.warn({ channel, kind, err: error }, "progress not shown"),
+					);
+			};
 			let result: TurnResult;
 			try {
 				result = await settleTurn(
@@ -105,11 +157,13 @@ export function conversationTurns(
 								...(input.steerable ? { steerable: true } : {}),
 								...(input.interactive ? { interactive: true } : {}),
 								...(interim ? { interim } : {}),
+								progress,
 							}),
 						),
 					"conversation turn",
 				);
 			} finally {
+				live = false;
 				hideStop();
 			}
 			events.turnEnded({

package/src/core/routing/surface-port.ts

@@ -42,5 +42,8 @@ export function surfacePort(linked: () => readonly ChatSurface[]): SurfacePort {
 			of(channel)?.unreact?.(channel, messageId, emoji),
 		prompts: (channel, speaker) => of(channel)?.prompts?.(channel, speaker),
 		interim: (channel) => of(channel)?.interim?.(channel),
+		progress: async (channel, event) => {
+			await of(channel)?.progress?.(channel, event);
+		},
 	};
 }

package/src/core/runtime/extensions/confirmation-gate.ts

@@ -54,6 +54,8 @@ function byCodeUnit(a: string, b: string): number {
 // pi-lens-ignore: large-class — one gate per conversation; its state is the held calls and their approvals
 export class ConfirmationGate {
 	#selectionId: string | undefined;
+	/** The running turn's speaker, whom the actions it holds belong to. */
+	#speakerId: string | undefined;
 	#pending: PendingConfirmation | undefined;
 	#approved: HeldCall[] = [];
 	readonly #holds: HoldCheck;
@@ -91,13 +93,18 @@ export class ConfirmationGate {
 			: pending;
 	}
 
-	/** `addressee` is who the turn is for; without one, the owner. */
+	/**
+	 * `addressee` is who the turn is for; without one, the owner. `speakerId` is who spoke the turn,
+	 * recorded with what it holds; without one, only the owner may approve them.
+	 */
 	beginTurn(
 		selectionId: string,
 		confirmed: boolean,
 		addressee?: OwnerIdentity,
+		speakerId?: string,
 	): void {
 		this.#selectionId = selectionId;
+		this.#speakerId = speakerId;
 		this.#addressee = addressee ?? this.#owner;
 		this.#approved = confirmed ? [...(this.pending()?.calls ?? [])] : [];
 		this.#pending = undefined;
@@ -180,10 +187,11 @@ export class ConfirmationGate {
 		const selectionId = this.#selectionId;
 		if (selectionId === undefined)
 			throw new Error("a call was held outside a turn");
-		const pending = this.#pending ?? {
+		const pending: PendingConfirmation = this.#pending ?? {
 			selectionId,
 			heldAt: new Date(),
 			calls: [],
+			...(this.#speakerId === undefined ? {} : { speakerId: this.#speakerId }),
 		};
 		if (
 			!pending.calls.some((c) => c.tool === call.tool && c.input === call.input)

package/src/core/runtime/extensions/self-compact-guard.ts

@@ -1,8 +1,19 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { ConfigError } from "../../domain/errors.ts";
 
 /** pi-self-compact's tool, active in every session. */
 export const COMPACT_TOOL = "compact_session";
 
+/** The preflight's refusal of a session without the tools it requires, saying where compaction's comes from. */
+export function missingToolsError(missing: readonly string[]): ConfigError {
+	const source = missing.includes(COMPACT_TOOL)
+		? ` ${COMPACT_TOOL} comes from the Pi package pi-self-compact: install it (bun add pi-self-compact) and load it from a plugin with piPackages: ["pi-self-compact"], as the plugins/self-compact.ts of a project roundtable init creates does.`
+		: "";
+	return new ConfigError(
+		`required tools are not registered: ${missing.join(", ")}.${source}`,
+	);
+}
+
 const RESUME_REFUSED =
 	"compact_session cannot take resume here: a resumed run would start outside this conversation and its reply would reach no one. Finish this turn's work, then call compact_session again without resume; the next message starts from the compacted context.";
 

package/src/core/runtime/pending-confirmation-store.ts

@@ -10,6 +10,7 @@ interface Row {
 	selection_id: string;
 	held_at: Date;
 	calls: string;
+	speaker_id: string | null;
 }
 
 /** Each owner channel's held actions, in the database, so a restart keeps them. */
@@ -34,14 +35,46 @@ export class PendingConfirmationStore {
 		},
 	};
 
+	/** Who spoke the turn that held the actions, so only they and the owner approve them. */
+	static readonly speakerMigration: Migration = {
+		name: "held-actions-speaker",
+		up: async (sql) => {
+			await sql`ALTER TABLE held_actions ADD COLUMN IF NOT EXISTS speaker_id text`;
+		},
+	};
+
+	/**
+	 * The hold the speaker belongs to, by its `held_at`. 0.7 replaces a row's held actions and
+	 * leaves `speaker_id` as it was, so after a rollback and an upgrade a speaker counts only while
+	 * the row still holds the actions it was written with.
+	 */
+	static readonly speakerHoldMigration: Migration = {
+		name: "held-actions-speaker-hold",
+		up: async (sql) => {
+			await sql`ALTER TABLE held_actions ADD COLUMN IF NOT EXISTS speaker_held_at timestamptz`;
+		},
+	};
+
+	/** The store's migrations in order. */
+	static migrations(): Migration[] {
+		return [
+			PendingConfirmationStore.migration,
+			PendingConfirmationStore.speakerMigration,
+			PendingConfirmationStore.speakerHoldMigration,
+		];
+	}
+
 	/** The store over the host's migrated pool. */
 	static async attach(sql: SQL): Promise<PendingConfirmationStore> {
 		return new PendingConfirmationStore(sql);
 	}
 
 	async load(channel: ChannelKey): Promise<PendingConfirmation | undefined> {
+		// A speaker written with other held actions than the row's, or without its hold, is none.
 		const rows: Row[] = await this.#sql`
-			SELECT selection_id, held_at, calls FROM held_actions
+			SELECT selection_id, held_at, calls,
+				CASE WHEN speaker_held_at = held_at THEN speaker_id END AS speaker_id
+			FROM held_actions
 			WHERE channel_key = ${channel}`;
 		const row = rows[0];
 		return row
@@ -50,6 +83,7 @@ export class PendingConfirmationStore {
 					heldAt: row.held_at,
 					// pi-lens-ignore: unchecked-throwing-call — this store wrote the JSON; a corrupt row should fail loudly
 					calls: JSON.parse(row.calls) as HeldCall[],
+					...(row.speaker_id === null ? {} : { speakerId: row.speaker_id }),
 				}
 			: undefined;
 	}
@@ -63,11 +97,15 @@ export class PendingConfirmationStore {
 			await this.#sql`DELETE FROM held_actions WHERE channel_key = ${channel}`;
 			return;
 		}
+		const speaker = pending.speakerId ?? null;
 		await this.#sql`
-			INSERT INTO held_actions (channel_key, selection_id, held_at, calls)
+			INSERT INTO held_actions
+				(channel_key, selection_id, held_at, calls, speaker_id, speaker_held_at)
 			VALUES (${channel}, ${pending.selectionId}, ${pending.heldAt},
-				${JSON.stringify(pending.calls)})
+				${JSON.stringify(pending.calls)}, ${speaker},
+				${speaker === null ? null : pending.heldAt})
 			ON CONFLICT (channel_key) DO UPDATE SET selection_id = EXCLUDED.selection_id,
-				held_at = EXCLUDED.held_at, calls = EXCLUDED.calls`;
+				held_at = EXCLUDED.held_at, calls = EXCLUDED.calls,
+				speaker_id = EXCLUDED.speaker_id, speaker_held_at = EXCLUDED.speaker_held_at`;
 	}
 }

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

@@ -35,7 +35,10 @@ import {
 	ConfirmationGate,
 	confirmedTurnText,
 } from "./extensions/confirmation-gate.ts";
-import { COMPACT_TOOL } from "./extensions/self-compact-guard.ts";
+import {
+	COMPACT_TOOL,
+	missingToolsError,
+} from "./extensions/self-compact-guard.ts";
 import { interimPoster } from "./interim-text.ts";
 import { PromptSlot, workTimeout } from "./prompt-slot.ts";
 import {
@@ -47,6 +50,7 @@ import { archiveSessions } from "./session-archive.ts";
 import { SessionFactory } from "./session-factory.ts";
 import { type PromptImages, SteerableRun } from "./steerable-run.ts";
 import { lastReply, turnAnswer } from "./turn-answer.ts";
+import { progressReporter } from "./turn-progress.ts";
 import { workerReport } from "./worker-task.ts";
 
 export {
@@ -117,11 +121,7 @@ export class PiAgentRuntime implements AgentRuntime {
 			),
 		];
 		const missing = expected.filter((name) => !registered.has(name));
-		if (missing.length > 0) {
-			throw new ConfigError(
-				`required tools are not registered: ${missing.join(", ")}`,
-			);
-		}
+		if (missing.length > 0) throw missingToolsError(missing);
 	}
 
 	// 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
@@ -168,6 +168,7 @@ export class PiAgentRuntime implements AgentRuntime {
 			request.selection.id,
 			request.confirmed === true,
 			addressee(request.speaker, this.#options.owner),
+			request.speaker?.id,
 		);
 		if (request.confirmed && pending) {
 			logger.info(
@@ -184,7 +185,12 @@ export class PiAgentRuntime implements AgentRuntime {
 		const toolCalls: string[] = [];
 		// Text written before the final answer is posted as the turn goes; the final reply stays the caller's.
 		const interim = interimPoster(request, this.#options);
+		// The caller's live view: the text as it streams and each tool, never the thinking.
+		const progress = request.progress
+			? progressReporter(request.progress)
+			: undefined;
 		const unsubscribe = session.subscribe((event) => {
+			progress?.observe(event);
 			if (event.type === "tool_execution_start") {
 				toolCalls.push(event.toolName);
 				interim?.toolStart(event.toolName);
@@ -247,6 +253,7 @@ export class PiAgentRuntime implements AgentRuntime {
 			cancelTimeout();
 			slot.unbind();
 			unsubscribe();
+			progress?.close();
 			await interim?.flush();
 			gate.endTurn();
 			const usage = session.getContextUsage();

package/src/core/runtime/prompt-slot.ts

@@ -46,8 +46,8 @@ export class PromptSlot {
 		const prompts = this.#prompts;
 		if (!prompts) return undefined;
 		return {
-			confirm: (title, message, signal) =>
-				this.#waiting(() => prompts.confirm(title, message, signal)),
+			confirm: (title, message, signal, minTier) =>
+				this.#waiting(() => prompts.confirm(title, message, signal, minTier)),
 			ask: (title, question: OwnerQuestion, signal) =>
 				this.#waiting(() => prompts.ask(title, question, signal)),
 		};

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

@@ -0,0 +1,160 @@
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type {
+	AgentRuntime,
+	AgentSessions,
+	HeldActionStore,
+	RuntimeDeps,
+} from "../contract/runtime.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { InterimTextMode } from "../domain/interim.ts";
+import type { OwnerIdentity } from "../identity.ts";
+import { AGENT_BRIEF, EffortJudge } from "../judging/effort-judge.ts";
+import type { ModelRef, ThinkingLevel } from "../models.ts";
+import type { PluginContext, RoundtablePlugin } from "../plugin.ts";
+import { RUNTIME } from "../services.ts";
+import type { Speaker } from "../speakers.ts";
+import { PendingConfirmationStore } from "./pending-confirmation-store.ts";
+import { PiAgentRuntime } from "./pi-agent-runtime.ts";
+
+/** The name of the runtime plugin, as `serviceStarted` events and the migration ledger name it. */
+export const RUNTIME_PLUGIN = "runtime";
+
+/**
+ * Where the agent server hands the runtime its per-agent settings. The runtime is built before the
+ * agent server sets up, so it reads them at each turn; on a host without the agent server they stay
+ * unbound and no agent turn can run.
+ */
+export interface AgentSessionsSlot {
+	/** The agent server's settings, or undefined while none are bound. */
+	current(): AgentSessions | undefined;
+	/** Called once, by the agent server's setup. */
+	bind(sessions: AgentSessions): void;
+}
+
+export function agentSessionsSlot(): AgentSessionsSlot {
+	let bound: AgentSessions | undefined;
+	return {
+		current: () => bound,
+		bind: (sessions) => {
+			if (bound)
+				throw new Error(
+					"the agent sessions are bound once, by the agent server",
+				);
+			bound = sessions;
+		},
+	};
+}
+
+export interface RuntimePluginOptions {
+	/** Who the conversations serve, as prompts and tool results name them. */
+	owner: OwnerIdentity & { id: string };
+	/** Shared with the rest of the host, so logins refresh in one place. */
+	modelRuntime: ModelRuntime;
+	agentDir: string;
+	dataDir: string;
+	/** The assistant's model, and the thinking level the effort judge falls back to. */
+	model: ModelRef;
+	thinking: ThinkingLevel;
+	/** How sure the effort judge must be before its answer is used. */
+	judgeThreshold: number;
+	/** The agent server's settings, bound when it sets up; without a slot no agent turn runs. */
+	agents?: AgentSessionsSlot;
+	/** Whether turns post the text they write before their final answer as they go; default "on". */
+	interimText?: InterimTextMode;
+	/** An intermediate text this long or longer is posted as an ordinary message; default 400. */
+	interimPrimaryChars?: number;
+}
+
+/**
+ * The runtime every conversation turn runs on, built once at setup and provided as `RUNTIME`: the
+ * `runtime` provider slot's when a plugin fills it, Pi's otherwise. It keeps the held actions'
+ * table, so a host without the agent server still holds and restores actions across a restart.
+ */
+export function runtimePlugin(
+	options: RuntimePluginOptions,
+	/** Opens the held actions' store; a test hands a stand-in, so the plugin sets up without a database. */
+	openHeldActions: (
+		context: Pick<PluginContext, "database">,
+	) => Promise<HeldActionStore> = (context) =>
+		PendingConfirmationStore.attach(context.database()),
+): RoundtablePlugin {
+	let runtime: AgentRuntime | undefined;
+	return {
+		name: RUNTIME_PLUGIN,
+		migrations: PendingConfirmationStore.migrations(),
+		provides: [RUNTIME],
+		preflight: async () => {
+			await runtime?.preflight?.();
+		},
+		setup: async (context) => {
+			const { logger, providers } = context;
+			const heldActions = await openHeldActions(context);
+			const prompts = (channel: ChannelKey, speaker?: Speaker) =>
+				context.surfaces.prompts(channel, speaker);
+			const agents = () => options.agents?.current();
+			const running: AgentRuntime = providers.filled.has("runtime")
+				? providers.runtime(
+						runtimeDeps({
+							logger,
+							env: context.env,
+							owner: { id: options.owner.id, name: options.owner.name },
+							sessions: context.sessions,
+							toolTiers: context.toolTiers,
+							prompts,
+							agents,
+							confirmations: heldActions,
+							judge: providers.judge,
+						}),
+					)
+				: new PiAgentRuntime({
+						owner: options.owner,
+						sessions: context.sessions,
+						agentDir: options.agentDir,
+						modelRuntime: options.modelRuntime,
+						dataDir: options.dataDir,
+						model: options.model,
+						thinking: options.thinking,
+						effort: new EffortJudge({
+							judge: providers.judge,
+							brief: AGENT_BRIEF,
+							fallback: options.thinking,
+							threshold: options.judgeThreshold,
+							logger,
+						}),
+						confirmations: heldActions,
+						toolTiers: context.toolTiers,
+						get agents() {
+							return agents();
+						},
+						prompts,
+						logger,
+						...(options.interimText
+							? { interimText: options.interimText }
+							: {}),
+						...(options.interimPrimaryChars
+							? { interimPrimaryChars: options.interimPrimaryChars }
+							: {}),
+					});
+			runtime = running;
+			context.services.provide(RUNTIME, running);
+			return {
+				services: [{ name: "runtime", stop: () => running.dispose?.() }],
+			};
+		},
+	};
+}
+
+/** The deps a runtime provider gets, with `agents` read when asked, after the agent server bound it. */
+function runtimeDeps(
+	deps: Omit<RuntimeDeps, "agents"> & {
+		agents: () => AgentSessions | undefined;
+	},
+): RuntimeDeps {
+	const { agents, ...rest } = deps;
+	return {
+		...rest,
+		get agents() {
+			return agents();
+		},
+	};
+}