pi-roundtable 0.15.2 → 0.15.3

package/CHANGELOG.md

@@ -5,6 +5,12 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.15.3] - 2026-10-15
+
+### Added
+
+- `effortPolicy` in the configuration (`EffortPolicy`, `EffortRequest` and `EffortRule` in `pi-roundtable/kit`): a host chooses, per turn that thinks at the judge's choice, how the level is decided. The policy gets the turn's `channel`, `kind`, `agent` and `origin` and answers `{ fixed: level }` to run the turn at that level without asking the judge, `{ requiredMass: [0, medium, high, xhigh] }` to run the highest level whose share of the judge's answer at or above it meets its entry (the previous turn's level does not carry over, and a judge that fails gives low), or `undefined` for the default. The `kind` of an agent-server agent's turn is `"agent"`. A `requiredMass` that is not four finite numbers in [0, 1], or a policy that throws, fails the turn with a clear error. Without a policy nothing changes.
+
 ## [0.15.2] - 2026-10-15
 
 ### Fixed

package/docs/plugins.md

@@ -80,7 +80,7 @@ Use the kit's building blocks for a plugin that runs Pi itself, such as a coding
   Two adapters log each skip as `Jev leaves the compaction to Pi's summary` with `reason`, `detail` and `tokensBefore` through the `logger` they take: `jevCompactionExtension({ logger, ...options })`, the `compaction` session tool's extension, placed as `session.compaction.wrap(jevCompactionExtension({ logger }))` under the engine `JEV_COMPACTION_ENGINE` (`pi-jev-compaction`), and `jevCompactor({ logger, ...options })`, a `JevCompactor` for pi-roundtable-sandbox's `compaction` option that returns the compaction or `undefined` and logs with the `channel`.
   A `no_key` skip is logged once per adapter, as `Jev is not configured, so compaction uses Pi's summary`, and then not again; every other skip is logged each time.
   The types are `JevCompactInput`, `JevCompactOptions`, `JevCompactOutcome`, `JevCompactor`, `JevCompactRequest`, `JevExtensionOptions` and `JevSkipReason`.
-- Effort: `effortJudge` picks a turn's thinking level from a message with your own brief (`EffortBrief`, `JUDGE_WORK`).
+- Effort: `effortJudge` picks a turn's thinking level from a message with your own brief (`EffortBrief`, `JUDGE_WORK`). A host that wants other turns decided differently sets `effortPolicy` (an `EffortPolicy`) in its configuration: it gets the turn's `channel`, `kind`, `agent` and `origin` and answers `{ fixed: level }` (no judge call), `{ requiredMass: [0, medium, high, xhigh] }` (the highest level whose share of the judge's answer at or above it meets its entry; the previous level does not carry over and a failed judge gives low), or `undefined` for the default. The `kind` of an agent-server agent's turn is `"agent"`; a policy that throws, or a `requiredMass` that is not four finite numbers in [0, 1], fails the turn.
 - Presentation and small helpers: `thinkingLine`, `zonedStamp(date, timeZone)`, `channelQueue()` (a queue of your own, so work does not wait behind a running turn), `checkRepoName` and `SKILL_LIST_TOOL` with `skillListExtension` for repositories and skills, and `searchTerms` for memory search.
 
 The [coding package source][coding-source] shows these helpers in an out-of-process Pi worker.
@@ -3847,6 +3847,9 @@ Import from the entries listed below; source area files are internal.
 | `EffortJudgeOptions` | `pi-roundtable/kit` | type |
 | `EffortLevel` | `pi-roundtable/kit` | type |
 | `EffortPicker` | `pi-roundtable/kit` | type |
+| `EffortPolicy` | `pi-roundtable/kit` | type |
+| `EffortRequest` | `pi-roundtable/kit` | type |
+| `EffortRule` | `pi-roundtable/kit` | type |
 | `GroupMessage` | `pi-roundtable/kit` | type |
 | `JUDGE_WORK` | `pi-roundtable/kit` | value |
 | `McpEndpoint` | `pi-roundtable/kit` | type |

package/package.json

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

package/src/core/config/config.ts

@@ -8,6 +8,7 @@ import { isLocale, type Locale } from "../i18n/index.ts";
 import type { AccessRules } from "../identity/access-policy.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import {
+	type EffortPolicy,
 	type ModelRef,
 	parseModelRef,
 	THINKING_LEVELS,
@@ -109,6 +110,8 @@ export interface RoundtableConfig {
 	thinking?: ThinkingLevel;
 	/** The model that judges small questions and the delegated tasks' model; default the agents' model. */
 	judge?: { model?: string; threshold?: number };
+	/** How each turn that thinks at the judge's choice is decided, instead of the default; see `EffortPolicy`. */
+	effortPolicy?: EffortPolicy;
 	delegation?: { model?: string; thinking?: ThinkingLevel };
 	/** The language of what the bot shows in Discord; default "en". */
 	locale?: Locale;
@@ -200,6 +203,8 @@ const tierMembers = shape({
 	everyone: optional(bool),
 });
 
+const isPolicy = (value: unknown): value is EffortPolicy =>
+	typeof value === "function";
 const isPlugin = (value: unknown): value is RoundtablePlugin =>
 	typeof value === "object" &&
 	value !== null &&
@@ -225,6 +230,9 @@ const schema = shape({
 	judge: optional(
 		shape({ model: optional(text), threshold: optional(number(0, 1)) }),
 	),
+	effortPolicy: optional(
+		guarded("a function from a turn to its effort rule", isPolicy),
+	),
 	delegation: optional(
 		shape({
 			model: optional(text),
@@ -320,6 +328,7 @@ export interface ResolvedConfig {
 	model: ModelRef;
 	thinking: ThinkingLevel;
 	judge: { model: ModelRef; threshold: number };
+	effortPolicy?: EffortPolicy;
 	delegation: { model: ModelRef; thinking: ThinkingLevel };
 	locale: Locale;
 	timeZone: string;
@@ -443,6 +452,7 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 				: model,
 			threshold: config.judge?.threshold ?? 0.6,
 		},
+		...(config.effortPolicy ? { effortPolicy: config.effortPolicy } : {}),
 		delegation: {
 			model: config.delegation?.model
 				? modelOf(config.delegation.model, "delegation.model")

package/src/core/define-roundtable.ts

@@ -329,6 +329,7 @@ export async function defineRoundtable(
 				model: config.model,
 				thinking: config.thinking,
 				judgeThreshold: config.judge.threshold,
+				...(config.effortPolicy ? { effortPolicy: config.effortPolicy } : {}),
 				agents: agentSessions,
 				interimText: config.interimText,
 				interimPrimaryChars: config.interimPrimaryChars,

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

@@ -72,6 +72,7 @@ export interface EffortPicker<Fallback extends ThinkingLevel = ThinkingLevel> {
 	judge(
 		message: string,
 		previous?: PreviousTurn<EffortLevel | Fallback>,
+		rule?: { requiredMass: readonly [number, number, number, number] },
 	): Promise<EffortLevel | Fallback>;
 }
 
@@ -96,6 +97,7 @@ export class EffortJudge<Fallback extends ThinkingLevel = ThinkingLevel>
 	async judge(
 		message: string,
 		previous: PreviousTurn<EffortLevel | Fallback> = {},
+		rule?: { requiredMass: readonly [number, number, number, number] },
 	): Promise<EffortLevel | Fallback> {
 		const { judge, brief, fallback, threshold, logger } = this.#options;
 		try {
@@ -113,10 +115,13 @@ export class EffortJudge<Fallback extends ThinkingLevel = ThinkingLevel>
 					criteria: brief.criteria,
 				},
 			);
-			const from = EFFORT_LEVELS.indexOf(previous.level as EffortLevel);
+			// A rule picks each turn on its own: the previous turn's level does not carry over.
+			const from = rule
+				? -1
+				: EFFORT_LEVELS.indexOf(previous.level as EffortLevel);
 			const index =
 				from === -1
-					? levelIndex(probabilities)
+					? levelIndex(probabilities, rule?.requiredMass)
 					: moveIndex(from, probabilities, threshold);
 			const level =
 				index === from && previous.level
@@ -128,7 +133,7 @@ export class EffortJudge<Fallback extends ThinkingLevel = ThinkingLevel>
 			);
 			return level;
 		} catch (error) {
-			const level = previous.level ?? fallback;
+			const level = rule ? "low" : (previous.level ?? fallback);
 			logger.warn({ err: error, level }, "effort request failed");
 			return level;
 		}
@@ -140,11 +145,14 @@ export class EffortJudge<Fallback extends ThinkingLevel = ThinkingLevel>
  * meets REQUIRED_MASS. Below the top level that is the median of an ordinal answer, which
  * unlike the mean never lands on a middle level nothing voted for.
  */
-export function levelIndex(probabilities: readonly number[]): number {
+export function levelIndex(
+	probabilities: readonly number[],
+	requiredMass: readonly number[] = REQUIRED_MASS,
+): number {
 	let reached = 0;
 	for (let index = probabilities.length - 1; index > 0; index--) {
 		reached += probabilities[index] ?? 0;
-		if (reached >= (REQUIRED_MASS[index] ?? 0.5)) return index;
+		if (reached >= (requiredMass[index] ?? 0.5)) return index;
 	}
 	return 0;
 }

package/src/core/models.ts

@@ -1,4 +1,5 @@
 import { messages } from "./i18n/index.ts";
+import type { ChannelKey } from "./sessions.ts";
 /** Models and thinking levels as Pi names them, and the settings built on them. */
 
 export type ThinkingLevel =
@@ -43,10 +44,40 @@ export function parseModelRef(text: string): ModelRef | undefined {
 export const formatModelRef = (model: ModelRef): string =>
 	`${model.provider}/${model.id}`;
 
+/** What a host's effort policy is told about a turn that thinks at the judge's choice. */
+export interface EffortRequest {
+	/** Where the turn's message arrived, as `<surface>:<channel id>`. */
+	channel: ChannelKey;
+	/** The conversation's kind, as a claim's `startFresh` set it; "agent" for an agent-server agent's turn; absent otherwise (an owner's turn). */
+	kind?: string;
+	/** The agent-server agent's name, for an agent's turn. */
+	agent?: string;
+	/** Where the request came from, as the transport knows it; see `TurnRequest.origin`. */
+	origin?: string;
+}
+
+/**
+ * How one turn's level is chosen, instead of the default. `fixed` runs the turn at that level
+ * without asking the judge. `requiredMass` asks the judge and runs the highest level whose share
+ * of the answer at or above it meets its entry (index 0 is low and never read; 1 medium, 2 high,
+ * 3 xhigh, each a finite number in [0, 1], else the turn fails); the previous turn's level does not
+ * carry over, and a judge that fails gives low.
+ */
+export type EffortRule =
+	| { fixed: ThinkingLevel }
+	| { requiredMass: readonly [number, number, number, number] };
+
+/**
+ * Picks the rule of a turn, or undefined for the default (sticky judging with the host's threshold).
+ * A policy that throws, or returns an invalid `requiredMass`, fails that turn.
+ */
+export type EffortPolicy = (request: EffortRequest) => EffortRule | undefined;
+
 /** 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 },
+		rule?: Exclude<EffortRule, { fixed: ThinkingLevel }>,
 	): Promise<ThinkingLevel>;
 }

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

@@ -151,6 +151,7 @@ export class PiAgentRuntime implements AgentRuntime {
 			{
 				modelRuntime: this.#modelRuntime,
 				effort: this.#options.effort,
+				policy: this.#options.effortPolicy,
 				judged: this.#sessions.judged,
 			},
 			key,

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

@@ -12,6 +12,7 @@ import type { OwnerIdentity } from "../identity.ts";
 import type { PromptScope } from "../interactions/prompts.ts";
 import { AGENT_BRIEF, EffortJudge } from "../judging/effort-judge.ts";
 import {
+	type EffortPolicy,
 	formatModelRef,
 	type ModelRef,
 	type ThinkingLevel,
@@ -69,6 +70,8 @@ export interface RuntimePluginOptions {
 	thinking: ThinkingLevel;
 	/** How sure the effort judge must be before its answer is used. */
 	judgeThreshold: number;
+	/** Picks a rule per turn instead of the judge's default; see `EffortPolicy`. */
+	effortPolicy?: EffortPolicy;
 	/** 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". */
@@ -159,6 +162,9 @@ export function runtimePlugin(
 						dataDir: options.dataDir,
 						model: options.model,
 						thinking: options.thinking,
+						...(options.effortPolicy
+							? { effortPolicy: options.effortPolicy }
+							: {}),
 						effort: new EffortJudge({
 							judge: providers.judge,
 							brief: AGENT_BRIEF,

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

@@ -13,7 +13,7 @@ import type { Principal } from "../identity/principal-store.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import type { PromptScope, Prompts } from "../interactions/prompts.ts";
 import type { Logger } from "../log.ts";
-import type { ThinkingLevel, ThinkingPicker } from "../models.ts";
+import type { EffortPolicy, ThinkingLevel, ThinkingPicker } from "../models.ts";
 import type { LinkedSessions } from "../plugin.ts";
 import {
 	planOrder,
@@ -60,6 +60,8 @@ export interface PiAgentRuntimeOptions {
 	thinking: ThinkingLevel;
 	/** Picks the level of the assistant's turns and of agents whose thinking is `auto`. */
 	effort: ThinkingPicker;
+	/** Chooses a turn's rule for the picker, or a fixed level; absent = the judge decides alike for every turn. */
+	effortPolicy?: EffortPolicy;
 	/** Held actions survive a restart here, so a confirmation after one still runs. */
 	confirmations: Pick<PendingConfirmationStore, "load" | "save">;
 	logger: Logger;

package/src/core/runtime/thinking-level.ts

@@ -4,7 +4,11 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import type { ChannelKey } from "../domain/conversation.ts";
 import type { TurnRequest } from "../domain/ports.ts";
-import { AUTO_THINKING, type ThinkingLevel } from "../models.ts";
+import {
+	AUTO_THINKING,
+	type EffortPolicy,
+	type ThinkingLevel,
+} from "../models.ts";
 import {
 	type AgentModelSettings,
 	useChosenAgentModel,
@@ -12,6 +16,20 @@ import {
 import type { PiAgentRuntimeOptions } from "./runtime-types.ts";
 import { lastReply } from "./turn-answer.ts";
 
+function checkRequiredMass(mass: readonly number[]): void {
+	if (
+		!Array.isArray(mass) ||
+		mass.length !== 4 ||
+		!mass.every(
+			(n) => typeof n === "number" && Number.isFinite(n) && n >= 0 && n <= 1,
+		)
+	) {
+		throw new Error(
+			`effortPolicy requiredMass must be four finite numbers in [0, 1], got ${JSON.stringify(mass)}`,
+		);
+	}
+}
+
 /** Uses the checked model snapshot; auto thinking keeps the last pick while the judge is unsure. */
 export async function thinkingLevel(
 	parts: {
@@ -19,6 +37,8 @@ export async function thinkingLevel(
 		effort: PiAgentRuntimeOptions["effort"];
 		/** The level last judged for each conversation. */
 		judged: Map<ChannelKey, ThinkingLevel>;
+		/** The host's rule for a turn that thinks at the judge's choice. */
+		policy?: EffortPolicy | undefined;
 	},
 	key: ChannelKey,
 	session: AgentSession,
@@ -38,10 +58,23 @@ export async function thinkingLevel(
 		judged.delete(key);
 		return setting;
 	}
-	const level = await effort.judge(request.text, {
-		reply: lastReply(session.messages),
-		level: judged.get(key),
+	const kind = request.kind ?? (request.agent ? "agent" : undefined);
+	const rule = parts.policy?.({
+		channel: request.channel,
+		...(kind !== undefined ? { kind } : {}),
+		...(request.agent ? { agent: request.agent.name } : {}),
+		...(request.origin !== undefined ? { origin: request.origin } : {}),
 	});
+	if (rule && "requiredMass" in rule) checkRequiredMass(rule.requiredMass);
+	if (rule && "fixed" in rule) {
+		judged.delete(key);
+		return rule.fixed;
+	}
+	const level = await effort.judge(
+		request.text,
+		{ reply: lastReply(session.messages), level: judged.get(key) },
+		rule,
+	);
 	judged.set(key, level);
 	return level;
 }

package/src/kit/index.ts

@@ -133,6 +133,9 @@ export type {
 	ChannelMessage,
 	DashboardBoard,
 	DelegationWorker,
+	EffortPolicy,
+	EffortRequest,
+	EffortRule,
 	GroupMessage,
 	Notifier,
 	OwnerNotifier,

package/src/kit/support.ts

@@ -14,7 +14,12 @@ export type { Backlog, GroupMessage } from "../core/agents/agent-rules.ts";
 export type { AgentOps } from "../core/agents/agent-tools.ts";
 export type { ThreadHost } from "../core/discord/dispatch-threads.ts";
 export type { Notifier, OwnerNotifier } from "../core/domain/ports.ts";
-export type { ThinkingPicker } from "../core/models.ts";
+export type {
+	EffortPolicy,
+	EffortRequest,
+	EffortRule,
+	ThinkingPicker,
+} from "../core/models.ts";
 export type { DelegationWorker } from "../core/modules/delegation/delegator.ts";
 export type { AgentChannelLookup } from "../core/modules/schedules/schedules.ts";
 export type { AssistantLike } from "../core/shared/session-messages.ts";