pi-improve-interation 0.0.1

package/node_modules/pi-subagents/src/shared/session-file-trust.ts

@@ -0,0 +1,19 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+function pathWithin(base: string, candidate: string): boolean {
+	const resolvedBase = path.resolve(base);
+	const resolvedCandidate = path.resolve(candidate);
+	return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(`${resolvedBase}${path.sep}`);
+}
+
+export function isTrustedRecordedSessionFile(realPath: string, recordedFiles: string[], sessionsBase: string | undefined): boolean {
+	if (!sessionsBase || recordedFiles.length === 0) return false;
+	try {
+		const realSessionsBase = fs.realpathSync(sessionsBase);
+		if (!pathWithin(realSessionsBase, realPath)) return false;
+		return recordedFiles.some((file) => fs.realpathSync(path.resolve(file)) === realPath);
+	} catch {
+		return false;
+	}
+}

package/node_modules/pi-subagents/src/shared/session-identity.ts

@@ -0,0 +1,10 @@
+interface SessionIdentityManager {
+	getSessionFile(): string | null | undefined;
+	getSessionId(): string | null | undefined;
+}
+
+export function resolveCurrentSessionId(sessionManager: SessionIdentityManager): string {
+	const sessionId = sessionManager.getSessionFile() ?? sessionManager.getSessionId();
+	if (!sessionId) throw new Error("Current session identity is unavailable.");
+	return sessionId;
+}

package/node_modules/pi-subagents/src/shared/session-tokens.ts

@@ -0,0 +1,55 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TokenUsage } from "./types.ts";
+
+function findLatestSessionFile(sessionDir: string): string | null {
+	try {
+		const files = fs.readdirSync(sessionDir)
+			.filter((f) => f.endsWith(".jsonl"))
+			.map((f) => path.join(sessionDir, f));
+		if (files.length === 0) return null;
+		files.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+		return files[0] ?? null;
+	} catch {
+		// Session token lookup is optional metadata.
+		return null;
+	}
+}
+
+export function parseSessionTokens(sessionDir: string): TokenUsage | null {
+	const sessionFile = findLatestSessionFile(sessionDir);
+	if (!sessionFile) return null;
+	try {
+		const content = fs.readFileSync(sessionFile, "utf-8");
+		let input = 0;
+		let output = 0;
+		let window: number | undefined;
+		let windowPeak: number | undefined;
+		for (const line of content.split("\n")) {
+			if (!line.trim()) continue;
+			try {
+				const entry = JSON.parse(line);
+				const usage = entry.usage ?? entry.message?.usage;
+				if (usage) {
+					const inputValue = usage.inputTokens ?? usage.input;
+					const outputValue = usage.outputTokens ?? usage.output;
+					const cacheReadValue = usage.cacheReadTokens ?? usage.cacheRead;
+					const turnInput = typeof inputValue === "number" && Number.isFinite(inputValue) ? inputValue : 0;
+					const turnOutput = typeof outputValue === "number" && Number.isFinite(outputValue) ? outputValue : 0;
+					const cacheRead = typeof cacheReadValue === "number" && Number.isFinite(cacheReadValue) ? cacheReadValue : 0;
+					const turnWindow = turnInput + cacheRead;
+					input += turnInput;
+					output += turnOutput;
+					window = turnWindow;
+					windowPeak = Math.max(windowPeak ?? 0, turnWindow);
+				}
+			} catch {
+				// Ignore malformed lines while scanning usage entries.
+			}
+		}
+		return { input, output, total: input + output, ...(window !== undefined ? { window, windowPeak } : {}) };
+	} catch {
+		// Usage extraction should not fail the run.
+		return null;
+	}
+}

package/node_modules/pi-subagents/src/shared/settings.ts

@@ -0,0 +1,409 @@
+/**
+ * Chain behavior, template resolution, and directory management
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { discoverAgents, formatUnknownAgentError, unknownAgentDiagnosticContext, type AgentConfig, type AgentScope, type UnknownAgentDiagnosticContext } from "../agents/agents.ts";
+import { normalizeSkillInput } from "../agents/skills.ts";
+import { normalizeOutputOverride, type OutputOverrideInput, type ResolvedStepBehavior } from "../runs/shared/child-launch-plan.ts";
+import { CHAIN_RUNS_DIR, type AcceptanceInput, type AgentContract, type ChainGateLayer, type JsonSchemaObject, type OutputMode, type ToolBudgetConfig } from "./types.ts";
+const CHAIN_DIR_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+const INITIAL_PROGRESS_CONTENT = "# Progress\n\n## Status\nIn Progress\n\n## Tasks\n\n## Files Changed\n\n## Notes\n";
+
+export {
+	planChildLaunch,
+	resolveStepBehavior,
+	resolveTaskTextForFileUpdatePolicy,
+	suppressProgressForReadOnlyTask,
+	taskDisallowsFileUpdates,
+} from "../runs/shared/child-launch-plan.ts";
+export type { ChildLaunchPlan, ChildLaunchPlanInput, OutputOverrideInput, ResolvedStepBehavior, StepOverrides } from "../runs/shared/child-launch-plan.ts";
+
+// =============================================================================
+// Chain Step Types
+// =============================================================================
+
+/** Sequential step: single agent execution */
+export interface SequentialStep {
+	agent: string;
+	task?: string;
+	phase?: string;
+	label?: string;
+	as?: string;
+	outputSchema?: JsonSchemaObject;
+	cwd?: string;
+	output?: OutputOverrideInput;
+	outputMode?: OutputMode;
+	reads?: string[] | false;
+	progress?: boolean;
+	skill?: string | string[] | false;
+	model?: string;
+	fast?: boolean;
+	toolBudget?: ToolBudgetConfig;
+	acceptance?: AcceptanceInput;
+	agentContract?: AgentContract;
+	gateOn?: ChainGateLayer;
+	/** Internal workflow child isolation; public workflowScript supplies this on runs.run. */
+	worktree?: boolean;
+}
+
+/** Parallel task item within a parallel step */
+export interface ParallelTaskItem {
+	agent: string;
+	task?: string;
+	phase?: string;
+	label?: string;
+	as?: string;
+	outputSchema?: JsonSchemaObject;
+	cwd?: string;
+	count?: number;
+	output?: OutputOverrideInput;
+	outputMode?: OutputMode;
+	reads?: string[] | false;
+	progress?: boolean;
+	skill?: string | string[] | false;
+	model?: string;
+	fast?: boolean;
+	toolBudget?: ToolBudgetConfig;
+	acceptance?: AcceptanceInput;
+	agentContract?: AgentContract;
+	gateOn?: ChainGateLayer;
+}
+
+export interface DynamicExpandSpec {
+	from: {
+		output: string;
+		path: string;
+	};
+	item?: string;
+	key?: string;
+	maxItems?: number;
+	onEmpty?: "skip" | "fail";
+}
+
+export type DynamicParallelTemplate = Omit<ParallelTaskItem, "as" | "count">;
+
+export interface DynamicCollectSpec {
+	as: string;
+	outputSchema?: JsonSchemaObject;
+}
+
+export interface DynamicParallelStep {
+	expand: DynamicExpandSpec;
+	parallel: DynamicParallelTemplate;
+	collect: DynamicCollectSpec;
+	concurrency?: number;
+	failFast?: boolean;
+	phase?: string;
+	label?: string;
+	acceptance?: AcceptanceInput;
+	agentContract?: AgentContract;
+	gateOn?: ChainGateLayer;
+}
+
+/** Parallel step: multiple agents running concurrently */
+export interface ParallelStep {
+	parallel: ParallelTaskItem[];
+	concurrency?: number;
+	failFast?: boolean;
+	worktree?: boolean;
+	cwd?: string;
+	agentContract?: AgentContract;
+	gateOn?: ChainGateLayer;
+}
+
+/** Union type for chain steps */
+export type ChainStep = SequentialStep | ParallelStep | DynamicParallelStep;
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+export function isParallelStep(step: ChainStep): step is ParallelStep {
+	return "parallel" in step && Array.isArray((step as ParallelStep).parallel);
+}
+
+export function isDynamicParallelStep(step: ChainStep): step is DynamicParallelStep {
+	return "expand" in step && "collect" in step && "parallel" in step && !Array.isArray((step as { parallel?: unknown }).parallel);
+}
+
+/** Get all agent names in a step (single for sequential, multiple for parallel) */
+export function getStepAgents(step: ChainStep): string[] {
+	if (isParallelStep(step)) {
+		return step.parallel.map((t) => t.agent);
+	}
+	if (isDynamicParallelStep(step)) {
+		return [step.parallel.agent];
+	}
+	return [step.agent];
+}
+
+// =============================================================================
+// Chain Directory Management
+// =============================================================================
+
+export function createChainDir(runId: string, baseDir?: string): string {
+	const chainDir = path.join(baseDir ? path.resolve(baseDir) : CHAIN_RUNS_DIR, runId);
+	fs.mkdirSync(chainDir, { recursive: true });
+	return chainDir;
+}
+
+export function removeChainDir(chainDir: string): void {
+	try {
+		fs.rmSync(chainDir, { recursive: true });
+	} catch {
+		// Chain cleanup is best-effort. Runs can already have cleaned their temp dir.
+	}
+}
+
+export function cleanupOldChainDirs(): void {
+	if (!fs.existsSync(CHAIN_RUNS_DIR)) return;
+	const now = Date.now();
+	let dirs: string[];
+	try {
+		dirs = fs.readdirSync(CHAIN_RUNS_DIR);
+	} catch {
+		// Startup cleanup is best-effort. If the scoped temp root is unreadable,
+		// skip cleanup instead of failing extension startup.
+		return;
+	}
+
+	for (const dir of dirs) {
+		try {
+			const dirPath = path.join(CHAIN_RUNS_DIR, dir);
+			const stat = fs.statSync(dirPath);
+			if (stat.isDirectory() && now - stat.mtimeMs > CHAIN_DIR_MAX_AGE_MS) {
+				fs.rmSync(dirPath, { recursive: true });
+			}
+		} catch {
+			// Skip directories that can't be processed; continue with others
+		}
+	}
+}
+
+// =============================================================================
+// Template Resolution
+// =============================================================================
+
+/** Resolved templates for a chain - string for sequential, string[] for parallel */
+export type ResolvedTemplates = (string | string[])[];
+
+/**
+ * Resolve templates for a chain with parallel step support.
+ * Returns string for sequential steps, string[] for parallel steps.
+ */
+export function resolveChainTemplates(
+	steps: ChainStep[],
+): ResolvedTemplates {
+	return steps.map((step, i) => {
+		if (isParallelStep(step)) {
+			// Parallel step: resolve each task's template
+			return step.parallel.map((task) => {
+				if (task.task) return task.task;
+				// Default for parallel tasks is {previous}
+				return "{previous}";
+			});
+		}
+		if (isDynamicParallelStep(step)) {
+			return step.parallel.task ?? "{previous}";
+		}
+		// Sequential step: existing logic
+		const seq = step as SequentialStep;
+		if (seq.task) return seq.task;
+		// Default: first step uses {task}, others use {previous}
+		return i === 0 ? "{task}" : "{previous}";
+	});
+}
+
+// =============================================================================
+// Chain Instruction Injection
+// =============================================================================
+
+/**
+ * Expand a leading `~`/`~/` to the user's home directory. Other forms (relative,
+ * absolute, `~user/`) pass through unchanged.
+ */
+export function expandHomePath(filePath: string): string {
+	if (filePath === "~") return os.homedir();
+	if (filePath.startsWith("~/")) return path.join(os.homedir(), filePath.slice(2));
+	return filePath;
+}
+
+/**
+ * Resolve a file path: `~`/`~/` expand to home first, then absolute paths pass
+ * through and relative paths get chainDir prepended.
+ */
+export function resolveChainPath(filePath: string, chainDir: string): string {
+	const expanded = expandHomePath(filePath);
+	return path.isAbsolute(expanded) ? expanded : path.join(chainDir, expanded);
+}
+
+export function resolveExistingReadInstructionPaths(reads: readonly string[], instructionCwd: string, existenceCwd = instructionCwd): string[] {
+	return reads.flatMap((filePath) => {
+		const instructionPath = resolveChainPath(filePath, instructionCwd);
+		const existencePath = resolveChainPath(filePath, existenceCwd);
+		return fs.existsSync(existencePath) ? [instructionPath] : [];
+	});
+}
+
+export function resolveExistingReadPaths(reads: readonly string[], cwd: string): string[] {
+	return resolveExistingReadInstructionPaths(reads, cwd);
+}
+
+/**
+ * Build chain instructions from resolved behavior.
+ * These are appended to the task to tell the agent what to read/write.
+ */
+export function writeInitialProgressFile(progressDir: string): void {
+	fs.mkdirSync(progressDir, { recursive: true });
+	fs.writeFileSync(path.join(progressDir, "progress.md"), INITIAL_PROGRESS_CONTENT);
+}
+
+export function buildChainInstructions(
+	behavior: ResolvedStepBehavior,
+	chainDir: string,
+	isFirstProgressAgent: boolean,
+	previousSummary?: string,
+	readExistenceDir = chainDir,
+): { prefix: string; suffix: string } {
+	const prefixParts: string[] = [];
+	const suffixParts: string[] = [];
+
+	// READS - prepend to override any hardcoded filenames in task text
+	if (behavior.reads && behavior.reads.length > 0) {
+		const files = resolveExistingReadInstructionPaths(behavior.reads, chainDir, readExistenceDir);
+		if (files.length > 0) prefixParts.push(`[Read from: ${files.join(", ")}]`);
+	}
+
+	// OUTPUT - prepend so agent knows where to write
+	if (behavior.output) {
+		const outputPath = resolveChainPath(behavior.output, chainDir);
+		prefixParts.push(`[Write to: ${outputPath}]`);
+	}
+
+	// Progress instructions in suffix (less critical)
+	if (behavior.progress) {
+		const progressPath = path.join(chainDir, "progress.md");
+		if (isFirstProgressAgent) {
+			suffixParts.push(`Create and maintain progress at: ${progressPath}`);
+		} else {
+			suffixParts.push(`Update progress at: ${progressPath}`);
+		}
+	}
+
+	// Include previous step's summary in suffix if available
+	if (previousSummary && previousSummary.trim()) {
+		suffixParts.push(`Previous step output:\n${previousSummary.trim()}`);
+	}
+
+	const prefix = prefixParts.length > 0 
+		? prefixParts.join("\n") + "\n\n"
+		: "";
+	
+	const suffix = suffixParts.length > 0
+		? "\n\n---\n" + suffixParts.join("\n")
+		: "";
+
+	return { prefix, suffix };
+}
+
+// =============================================================================
+// Parallel Step Support
+// =============================================================================
+
+/**
+ * Resolve behaviors for all tasks in a parallel step.
+ * Creates namespaced output paths to avoid collisions.
+ */
+/** Exact discovery context, or explicit input for defensive fallback discovery. */
+export type ParallelBehaviorDiagnostics = UnknownAgentDiagnosticContext | { cwd: string; scope?: AgentScope };
+
+export function resolveParallelBehaviors(
+	tasks: ParallelTaskItem[],
+	agentConfigs: AgentConfig[],
+	stepIndex: number,
+	chainSkills?: string[],
+	diagnostics?: ParallelBehaviorDiagnostics,
+): ResolvedStepBehavior[] {
+	return tasks.map((task, taskIndex) => {
+		const config = agentConfigs.find((a) => a.name === task.agent);
+		if (!config) {
+			if (!diagnostics) throw new Error("resolveParallelBehaviors requires unknown-agent diagnostic context or fallback discovery input.");
+			const context = "directories" in diagnostics
+				? diagnostics
+				: unknownAgentDiagnosticContext(discoverAgents(path.resolve(diagnostics.cwd), diagnostics.scope ?? "both"));
+			throw new Error(formatUnknownAgentError(task.agent, context));
+		}
+
+		// Build subdirectory path for this parallel task
+		const subdir = path.join(`parallel-${stepIndex}`, `${taskIndex}-${task.agent}`);
+
+		// Output: task override > agent default (namespaced) > false
+		// Absolute paths pass through unchanged; relative paths get namespaced under subdir
+		let output: string | false = false;
+		const taskOutput = normalizeOutputOverride(task.output);
+		const configOutput = normalizeOutputOverride(config.output);
+		if (taskOutput !== undefined) {
+			if (taskOutput === false) {
+				output = false;
+			} else if (path.isAbsolute(taskOutput)) {
+				output = taskOutput; // Absolute path: use as-is
+			} else {
+				output = path.join(subdir, taskOutput); // Relative: namespace under subdir
+			}
+		} else if (configOutput) {
+			// Agent defaults are always relative, so namespace them
+			output = path.join(subdir, configOutput);
+		}
+
+		// Reads: task override > agent default > false
+		const reads =
+			task.reads !== undefined ? task.reads : config.defaultReads ?? false;
+
+		// Progress: task override > agent default > false
+		const progress =
+			task.progress !== undefined
+				? task.progress
+				: config.defaultProgress ?? false;
+
+		const taskSkillInput = normalizeSkillInput(task.skill);
+		let skills: string[] | false;
+		if (taskSkillInput === false) {
+			skills = false;
+		} else if (taskSkillInput !== undefined) {
+			skills = [...taskSkillInput];
+			if (chainSkills && chainSkills.length > 0) {
+				skills = [...new Set([...skills, ...chainSkills])];
+			}
+		} else {
+			skills = config.skills ? [...config.skills] : [];
+			if (chainSkills && chainSkills.length > 0) {
+				skills = [...new Set([...skills, ...chainSkills])];
+			}
+		}
+
+		const outputMode = task.outputMode ?? config.outputMode ?? "inline";
+		const model = task.model ?? config.model;
+		return { output, outputMode, reads, progress, skills, model };
+	});
+}
+
+/**
+ * Create subdirectories for parallel step outputs
+ */
+export function createParallelDirs(
+	chainDir: string,
+	stepIndex: number,
+	taskCount: number,
+	agentNames: string[],
+): void {
+	for (let i = 0; i < taskCount; i++) {
+		const subdir = path.join(chainDir, `parallel-${stepIndex}`, `${i}-${agentNames[i]}`);
+		fs.mkdirSync(subdir, { recursive: true });
+	}
+}
+
+export type { ParallelTaskResult } from "../runs/shared/parallel-utils.ts";
+export { aggregateParallelOutputs } from "../runs/shared/parallel-utils.ts";

package/node_modules/pi-subagents/src/shared/shortcuts.ts

@@ -0,0 +1,17 @@
+import { Key, type KeyId } from "@earendil-works/pi-tui";
+
+export const FLEET_OPEN_SHORTCUT: KeyId = Key.ctrlAlt("f");
+
+export function formatShortcutLabel(shortcut: string): string {
+	return shortcut
+		.split("+")
+		.map((part) => {
+			const normalized = part.trim().toLowerCase();
+			if (normalized === "ctrl") return "Ctrl";
+			if (normalized === "alt") return "Alt";
+			if (normalized === "shift") return "Shift";
+			if (normalized === "super") return "Super";
+			return normalized.length === 1 ? normalized.toUpperCase() : part.trim();
+		})
+		.join("+");
+}

package/node_modules/pi-subagents/src/shared/status-format.ts

@@ -0,0 +1,55 @@
+import type { ActivityState, AsyncJobStep } from "./types.ts";
+
+type StepStatusLike = Pick<AsyncJobStep, "status">;
+
+function formatActivityAge(ms: number): string {
+	if (ms < 1000) return "now";
+	if (ms < 60000) return `${Math.floor(ms / 1000)}s`;
+	return `${Math.floor(ms / 60000)}m`;
+}
+
+export function formatActivityLabel(lastActivityAt: number | undefined, activityState?: ActivityState, now = Date.now()): string | undefined {
+	if (lastActivityAt === undefined) {
+		if (activityState === "needs_attention") return "needs attention";
+		if (activityState === "active_long_running") return "active but long-running";
+		return undefined;
+	}
+	const age = formatActivityAge(Math.max(0, now - lastActivityAt));
+	if (activityState === "needs_attention") return `no activity for ${age}`;
+	if (activityState === "active_long_running") {
+		const activityAge = age === "now" ? "now" : `${age} ago`;
+		return `active but long-running · last activity ${activityAge}`;
+	}
+	return age === "now" ? "active now" : `active ${age} ago`;
+}
+
+function isCompletedStepStatus(status: AsyncJobStep["status"]): boolean {
+	return status === "complete" || status === "completed";
+}
+
+export function aggregateStepStatus(steps: StepStatusLike[]): AsyncJobStep["status"] {
+	if (steps.some((step) => step.status === "running")) return "running";
+	if (steps.some((step) => step.status === "failed")) return "failed";
+	if (steps.some((step) => step.status === "stopped")) return "stopped";
+	if (steps.some((step) => step.status === "paused")) return "paused";
+	if (steps.length > 0 && steps.every((step) => isCompletedStepStatus(step.status))) return "complete";
+	return "pending";
+}
+
+export function formatAgentRunningLabel(count: number): string {
+	return count === 1 ? "1 agent running" : `${count} agents running`;
+}
+
+export function formatParallelOutcome(steps: StepStatusLike[], total: number, options: { showRunning?: boolean } = {}): string {
+	const running = steps.filter((step) => step.status === "running").length;
+	const done = steps.filter((step) => isCompletedStepStatus(step.status)).length;
+	const failed = steps.filter((step) => step.status === "failed").length;
+	const stopped = steps.filter((step) => step.status === "stopped").length;
+	const paused = steps.filter((step) => step.status === "paused").length;
+	const parts = [`${done}/${total} done`];
+	if (options.showRunning !== false && running > 0) parts.unshift(formatAgentRunningLabel(running));
+	if (failed > 0) parts.push(`${failed} failed`);
+	if (stopped > 0) parts.push(`${stopped} stopped`);
+	if (paused > 0) parts.push(`${paused} paused`);
+	return parts.join(" · ");
+}

package/node_modules/pi-subagents/src/shared/thinking-ceiling.ts

@@ -0,0 +1,52 @@
+import { resolveEffectiveThinking, THINKING_LEVELS, type ThinkingLevel } from "./model-info.ts";
+export type { ThinkingLevel } from "./model-info.ts";
+
+export const SUBAGENT_THINKING_CEILING_ENV = "PI_SUBAGENT_THINKING_CEILING";
+
+const thinkingLevelRanks = new Map<ThinkingLevel, number>(THINKING_LEVELS.map((level, index) => [level, index]));
+
+export function parseThinkingLevel(value: unknown, field = "thinking level"): ThinkingLevel {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (thinkingLevelRanks.has(trimmed as ThinkingLevel)) return trimmed as ThinkingLevel;
+	}
+	throw new Error(`Invalid ${field}; expected one of ${THINKING_LEVELS.join(", ")}.`);
+}
+
+export function compareThinkingLevels(left: ThinkingLevel, right: ThinkingLevel): number {
+	const leftRank = thinkingLevelRanks.get(left);
+	const rightRank = thinkingLevelRanks.get(right);
+	if (leftRank === undefined || rightRank === undefined) throw new Error(`Invalid thinking level comparison; expected one of ${THINKING_LEVELS.join(", ")}.`);
+	return leftRank - rightRank;
+}
+
+export function intersectThinkingCeilings(...ceilings: Array<ThinkingLevel | undefined>): ThinkingLevel | undefined {
+	const active = ceilings.filter((ceiling): ceiling is ThinkingLevel => ceiling !== undefined);
+	if (active.length === 0) return undefined;
+	return active.reduce((lowest, ceiling) => compareThinkingLevels(ceiling, lowest) < 0 ? ceiling : lowest);
+}
+
+export function decodeThinkingCeiling(value: string | undefined): ThinkingLevel | undefined {
+	if (value === undefined || value === "") return undefined;
+	return parseThinkingLevel(value, "inherited thinking ceiling");
+}
+
+export interface ThinkingCeilingCheck {
+	model?: string;
+	configThinking?: string | false;
+	ceiling?: ThinkingLevel;
+	agent?: string;
+	runId?: string;
+}
+
+export function assertThinkingWithinCeiling(input: ThinkingCeilingCheck): void {
+	if (!input.ceiling) return;
+	const requested = resolveEffectiveThinking(input.model, input.configThinking);
+	if (!requested) return;
+	const requestedLevel = parseThinkingLevel(requested, "requested thinking level");
+	if (compareThinkingLevels(requestedLevel, input.ceiling) <= 0) return;
+	const subject = [input.agent ? `agent '${input.agent}'` : undefined, input.runId ? `run '${input.runId}'` : undefined]
+		.filter((value): value is string => Boolean(value))
+		.join(" ");
+	throw new Error(`Thinking level '${requestedLevel}' exceeds configured maximum '${input.ceiling}'${subject ? ` for ${subject}` : ""}.`);
+}