pi-roundtable 0.17.0 → 0.17.3

package/CHANGELOG.md

@@ -5,6 +5,30 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.17.3] - 2026-10-16
+
+### Fixed
+
+- The 0.17.1 entry and the plugin guide called `turnTimeoutMs` and `turnMaxMs` options of the built-in runtime that a host can set. Nothing public sets them: the runtime plugin passes neither, and the runtime class is not exported. Every host runs a turn with 10 minutes of work, renewed by each steer up to 30 minutes in all. The guide now says the two limits are fixed, and its startup order lists the runtime's own `preflight`, which 0.17.2 moved after every plugin's.
+- `testPlugin` runs the runtime's `preflight` where the host does, right after the plugin's own and before the plugin's services and surfaces start, not after they have. A runtime whose `preflight` throws fails `testPlugin` with that error, with nothing started and the runtime disposed.
+- A time limit on a turn, or on a coding worker (`workTimeout`), that comes due while an owner's card is open looks at the turn again no oftener than once a second, not once a millisecond for as long as the card waits. The limit still fires once; a limit that waiting on a card pushed back can fire up to a second late.
+
+### Changed
+
+- 0.17.2 was tagged but never published: its release run stopped on a LINE plugin test that raced its own frozen clock. 0.17.3 carries 0.17.2's fix, the runtime's startup probe after every plugin's `preflight`; the LINE tests that raced now step their clock, and no shipped LINE code changed.
+
+## [0.17.2] - 2026-10-16
+
+### Fixed
+
+- The runtime's startup probe of the model and the required tools runs after every plugin's `preflight`, not in the runtime plugin's own preflight, which ran first. Since 0.17.0 a plugin that resolves its MCP servers does so in its preflight, so the probe no longer saw the tools they yield, and a required tool that was missing failed only the first session instead of the start. The host now runs the `RUNTIME` service's `preflight` once every plugin's preflight has finished, still before any service starts or any listener opens; a failure stops the start, and the same host may try again. A custom runtime provider's `preflight` moves to the same place. The runtime plugin's claude-bridge memory warning stays in its own preflight. `Roundtable.check()` still runs no preflight.
+
+## [0.17.1] - 2026-10-16
+
+### Changed
+
+- A message steered into a running turn renews the turn's time budget: the built-in runtime gives the turn its full `turnTimeoutMs` (10 minutes by default) again from the steer, so a turn the owner kept steering is no longer aborted, and its final reply lost, at 10 minutes from its start. The new runtime option `turnMaxMs` caps the work of one turn, steered or not, at three times `turnTimeoutMs` by default (30 minutes); once it is reached the turn takes no more steering, the message waits for the next turn, and the turn is aborted as on its timeout. Time waiting on the owner's cards counts towards neither. A renewal is logged at info (`steer renewed the turn's time budget`, with `channel` and `deadlineMs`, the work time left), and the timeout warning names the limit that fired (`limit: "turn"` or `"turnMax"`). Task workers, coding workers and sandbox guests keep their own timeouts.
+
 ## [0.17.0] - 2026-10-16
 
 ### Added

package/docs/plugins.md

@@ -1443,7 +1443,7 @@ An `AgentRuntime` has these methods:
 | `pendingConfirmation(conversation)`, `heldActions(conversation)` | The held actions known in memory, and those restored from the store after a restart: the agent server reads `heldActions` to show an approval card again after a restart. After a restart `pendingConfirmation` knows a conversation's held actions only once `heldActions` or `recentTranscript` has restored them, so a host that decides an approval asks one of them first. A `PendingConfirmation` carries the `selectionId` of the `TurnSelection` whose turn held the calls, an opaque string that the caller resolves again when the owner confirms; the core stores it and never reads it |
 | `recentTranscript(conversation, limit)` | The latest messages, for the owner's and the dashboard's views of a conversation; the built-in runtime gives none of a history recorded, or a session opened, for someone else than the conversation serves now |
 | `contextUsage?(conversation)` | How full the conversation's context is, `{ tokens, contextWindow }`; leave it out and the team status shows no context bar |
-| `preflight?()` | Runs in the host's preflight, before anything starts; a throw stops the boot |
+| `preflight?()` | Runs after every plugin's preflight, before anything starts; a throw stops the boot |
 | `dispose?()` | Runs when the host stops the runtime plugin's `runtime` service |
 
 A request has the turn's `channel`, `selection` (its tools), `text`, `attachments`, `speaker` (required: the person the turn is for, at whose tier it runs; the built-in runtime refuses a request without one with an `AgentRunError` before asking the model, and a plugin that starts a turn on someone's behalf gets theirs from `IDENTITY.speakerFor`), `conversation` (`TurnConversation`: `private` to a `principalId`, or `shared`, as `context.turns` records it; shared when absent), flags (`steerable`, `interactive`, `confirmed`: the speaker's message approved the conversation's held calls, which the runtime releases for the speaker, except those that [name approvers](#a-hold-that-names-its-approvers) the speaker is neither among nor an owner of, which stay held), and `interim`, where the turn may post the text it writes before its final answer ([interim text](#interim-text-what-a-turn-writes-before-its-final-answer)).
@@ -1698,6 +1698,10 @@ test("only one plugin may fill the runtime slot", async () => {
 `preflight` also sits on the plugin.
 It runs once every plugin is set up and linked, before any command is registered or any service starts.
 A throw stops the boot, so a missing setting is caught before Discord connects.
+Plugins' preflights run in plugin order.
+Once every one has finished, the host runs the runtime's own `preflight` (the `RUNTIME` service's), which for Pi's runtime builds throwaway sessions and checks the model and the required tools.
+So tools a plugin fills in during its preflight, such as MCP servers it resolves there, are in those sessions, and a required tool still missing stops the start before any service starts or any listener opens.
+`Roundtable.check()` runs no preflight.
 
 <!-- example: examples/preflight.ts -->
 ```ts
@@ -3367,6 +3371,7 @@ The host's `run()` handles startup:
    From here `sessions()`, `conversations`, `surfaces`, `turns`, and `dashboard()` work.
 5. Every plugin's `preflight` runs, in plugin order.
    The Discord plugin's preflight is where it composes the slash commands every plugin added in `setup`; a clash stops the start here.
+   Once every one has finished, the runtime's own `preflight` (the `RUNTIME` service's) runs, so its check of the model and the required tools sees the tools that other plugins filled in during theirs.
 6. Every service starts: the plugins' in plugin order, and each plugin's own in the order it listed them, after the plugin's chat surfaces (the `surface:<prefix>` services).
 7. The HTTP listeners open.
 8. Every service's `startInBackground` runs, at once and without holding up the boot, and every plugin hears `serviceStarted` as each ends; the agent server's `team` service starts the agents' channels and the dashboard there.
@@ -3395,6 +3400,7 @@ On `SIGTERM` or `SIGINT` the bot takes no new work at once, finishes what runs,
 `shutdown()` returns exit code `0`, or `1` if a listener, service, or pool failed to stop.
 Every call shares the same shutdown.
 Give the service manager a stop timeout longer than the drain limit plus about a minute for the steps after it, such as systemd's `TimeoutStopSec=5min` with the default three-minute drain; a shorter one has the manager kill the process in the middle of the drain.
+The built-in runtime aborts a turn that works 10 minutes, not counting time spent waiting on the owner's cards. Each message steered into the running turn gives it the full 10 minutes again from that moment, up to a cap of 30 minutes of work for the whole turn; once the cap is reached the turn takes no more steering, so a message waits for the next turn, and the turn is aborted as on its timeout. Both limits are fixed: the runtime plugin passes no option for them, so a host cannot change them, and a limit that waiting on an owner's card pushed back can fire up to a second late. The log says `steer renewed the turn's time budget` with `deadlineMs`, the work time left, and the timeout warning names the limit that fired (`limit: "turn"` or `"turnMax"`). Task workers (`task.timeoutMs`), coding workers (`workTimeout`) and sandbox guests (their own `turnTimeoutMs`) keep their own limits, which steering does not renew.
 A turn whose model ignores its abort (a subprocess that does not exit) is given up on too: a turn that outlives its timeout, or is stopped, gets `turnAbortGraceMs` (15 seconds by default) to end, and then its session is disposed of and the turn is reported failed, so it cannot hold the queue.
 `listen()`, called by the command line and a host's own entry point, exits the process with that code.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.17.0",
+	"version": "0.17.3",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/contract/runtime.ts

@@ -72,7 +72,7 @@ export interface AgentRuntime {
 	): Promise<TranscriptEntry[]>;
 	/** Undefined when unknown; the team status shows no context bar for the conversation then. */
 	contextUsage?(conversation: ChannelKey): ContextUse | undefined;
-	/** Runs in the host's preflight, before anything starts; a throw stops the boot. */
+	/** Runs after every plugin's preflight, before anything starts; a throw stops the boot. */
 	preflight?(): Promise<void>;
 	/** Runs when the host stops the agent server's runtime service. */
 	dispose?(): Promise<void> | void;

package/src/core/host.ts

@@ -11,6 +11,7 @@ import type { Locale } from "./i18n/index.ts";
 import type { JudgeModel } from "./judging/model-judge.ts";
 import type { Logger } from "./log.ts";
 import type { RoundtablePlugin, Service } from "./plugin.ts";
+import { RUNTIME } from "./services.ts";
 import type { ChannelKey } from "./sessions.ts";
 import type { ToolTierTable } from "./tool-tiers.ts";
 
@@ -149,6 +150,8 @@ export class Roundtable {
 			return this.#pool;
 		});
 		for (const plugin of link.active) await plugin.preflight?.();
+		// Last, so the probe sees the tools other plugins fill in during their preflight.
+		await link.services?.find(RUNTIME)?.preflight?.();
 		for (const service of [...link.registry.services, ...retention]) {
 			await service.start?.();
 			this.#started.push(service);

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

@@ -33,7 +33,7 @@ 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, runningTurn } from "./running-turn.ts";
 import type { PiAgentRuntimeOptions, TurnMessage } from "./runtime-types.ts";
@@ -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. */
@@ -114,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?.())
@@ -272,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);
@@ -313,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();
@@ -358,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/prompt-slot.ts

@@ -1,6 +1,7 @@
 import type { HoldRefusal } from "../domain/progress.ts";
 import { assistantName } from "../i18n/index.ts";
 import type { OwnerQuestion, Prompts } from "../interactions/prompts.ts";
+import { turnBudget } from "./turn-budget.ts";
 
 /**
  * A run's way to ask the owner while it works. A turn they started or a report turn binds the
@@ -101,22 +102,13 @@ export function promptSlot(): PromptSlot {
 
 /**
  * Calls `expire` once the run has worked `ms`, not counting time the slot spent waiting on the
- * owner's cards; returns a function that cancels it.
+ * owner's cards; returns a function that cancels it. It is a turn budget with nothing to renew,
+ * so it looks again at a run that waits on a card no oftener than `turnBudget` does.
  */
 export function workTimeout(
 	ms: number,
 	slot: Pick<PromptSlot, "waitedMs">,
 	expire: () => void,
 ): () => void {
-	const started = Date.now();
-	let timer: ReturnType<typeof setTimeout> | undefined;
-	const arm = (delay: number) => {
-		timer = setTimeout(() => {
-			const left = ms - (Date.now() - started - slot.waitedMs());
-			if (left > 0) return arm(left);
-			expire();
-		}, delay);
-	};
-	arm(ms);
-	return () => clearTimeout(timer);
+	return turnBudget(ms, ms, slot, () => expire()).cancel;
 }

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

@@ -97,7 +97,6 @@ export function runtimePlugin(
 	) => Promise<HeldActionStore> = (context) =>
 		PendingConfirmationStore.attach(context.database()),
 ): RoundtablePlugin {
-	let runtime: AgentRuntime | undefined;
 	let identity: IdentityService | undefined;
 	let warn: ((message: string) => void) | undefined;
 	// Admission is a startup risk warning, not proof that this conversation holds private history.
@@ -119,7 +118,6 @@ export function runtimePlugin(
 						`${bridgeMemoryProblem(formatModelRef(options.model), why)} ${BRIDGE_MEMORY_FIX}`,
 					);
 			}
-			await runtime?.preflight?.();
 		},
 		setup: async (context) => {
 			const { logger, providers, services } = context;
@@ -194,7 +192,6 @@ export function runtimePlugin(
 							? { interimPrimaryChars: options.interimPrimaryChars }
 							: {}),
 					});
-			runtime = running;
 			context.services.provide(RUNTIME, running);
 			return {
 				services: [{ name: "runtime", stop: () => running.dispose?.() }],

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

@@ -88,8 +88,18 @@ export interface PiAgentRuntimeOptions {
 	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

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

@@ -0,0 +1,121 @@
+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);
+	},
+};
+
+/**
+ * The shortest wait before a budget looks again at a turn that still has time. While a card is
+ * open the turn's work time stands still, so a timer that fires with a few milliseconds left would
+ * otherwise re-arm for those milliseconds, again and again, for as long as the card waits. The
+ * floor bounds that to one look a second; the cost is that a limit that waiting on a card pushed
+ * back, by less than the floor, may fire up to this much late.
+ */
+const REARM_FLOOR_MS = 1_000;
+
+/**
+ * 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(Math.max(left, REARM_FLOOR_MS));
+			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/testing.ts

@@ -608,17 +608,18 @@ export async function testPlugin(
 	// The plugin's own surfaces start as services; the injected ones start beside them, after.
 	const deliver = (message: InboundMessage) =>
 		void conversations.handle(message);
-	// As the host does, the plugin's preflight runs once everything is set up and before any service starts.
+	// As the host does, the plugin's preflight runs once everything is set up and before any service
+	// starts, and the runtime's own after it, so it sees what the preflight filled in.
 	try {
 		await plugin.preflight?.();
+		await runtime?.preflight?.();
 	} catch (error) {
-		// The runtime the provider built is not left running when the plugin refuses.
+		// The runtime the provider built is not left running when the plugin or the runtime refuses.
 		await runtime?.dispose?.();
 		throw error;
 	}
 	for (const service of registry.services) await service.start?.();
 	for (const surface of options.surfaces ?? []) await surface.start(deliver);
-	await runtime?.preflight?.();
 	let stopped = false;
 	const files: { channel: ChannelKey; file: ReplyFile }[] = [];
 	const images: { channel: ChannelKey; image: ClientPart }[] = [];