@oh-my-pi/pi-coding-agent 15.7.5 → 15.8.0

package/src/task/output-manager.ts

@@ -1,29 +1,28 @@
 /**
  * Session-scoped manager for agent output IDs.
  *
- * Ensures unique output IDs across task tool invocations within a session.
- * Prefixes each ID with a sequential number (e.g., "0-AuthProvider", "1-AuthApi").
- * If a parent prefix is provided, IDs are nested (e.g., "0-Auth.1-Subtask").
+ * Keeps every subagent output id unique within a session without polluting the
+ * common case with bookkeeping. A requested name is used verbatim the first
+ * time it appears; only a *repeated* name gets a numeric suffix to disambiguate
+ * it (e.g. "Anna", "Anna-2", "Anna-3"). When a parent prefix is configured, ids
+ * are nested under it (e.g. "Anna.Bob") so hierarchical outputs stay grouped.
  *
- * This enables reliable agent:// URL resolution and prevents artifact collisions.
+ * This enables reliable agent:// URL resolution and prevents artifact
+ * collisions across repeated or nested task invocations.
  */
 import * as fs from "node:fs/promises";
 
-function escapeRegExp(value: string): string {
-	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
 /**
  * Manages agent output ID allocation to ensure uniqueness.
  *
- * Each allocated ID gets a numeric prefix based on allocation order.
- * If configured with a parent prefix, the numeric prefix is appended after
- * the parent (e.g., "0-Parent.0-Child").
- * On resume, scans existing files to find the next available index.
+ * The first allocation of a given name keeps the name as-is; subsequent
+ * allocations of the same name get a `-2`, `-3`, … suffix. On resume, scans
+ * existing output files so previously written outputs are never overwritten.
  */
 export class AgentOutputManager {
-	#nextId = 0;
 	#initialized = false;
+	/** Final ids already handed out, relative to this manager's scope. */
+	readonly #taken = new Set<string>();
 	readonly #getArtifactsDir: () => string | null;
 	readonly #parentPrefix: string | undefined;
 
@@ -33,8 +32,8 @@ export class AgentOutputManager {
 	}
 
 	/**
-	 * Scan existing agent output files to find the next available ID.
-	 * This ensures we don't overwrite outputs when resuming a session.
+	 * Seed the taken-id set from output files already on disk so a resumed
+	 * session never reuses a name that would clobber a prior subagent's output.
 	 */
 	async #ensureInitialized(): Promise<void> {
 		if (this.#initialized) return;
@@ -50,31 +49,41 @@ export class AgentOutputManager {
 			return; // Directory doesn't exist yet
 		}
 
-		const pattern = this.#parentPrefix
-			? new RegExp(`^${escapeRegExp(this.#parentPrefix)}\\.(\\d+)-.*\\.md$`)
-			: /^(\d+)-.*\.md$/;
-
-		let maxId = -1;
+		const prefix = this.#parentPrefix ? `${this.#parentPrefix}.` : "";
 		for (const file of files) {
-			const match = file.match(pattern);
-			if (match) {
-				const id = Number.parseInt(match[1], 10);
-				if (id > maxId) maxId = id;
+			if (!file.endsWith(".md")) continue;
+			let rest = file.slice(0, -3); // drop ".md"
+			if (prefix) {
+				if (!rest.startsWith(prefix)) continue;
+				rest = rest.slice(prefix.length);
 			}
+			// Requested ids never contain "."; a dot marks a nested child, so this
+			// manager only owns the first segment of whatever remains.
+			const dot = rest.indexOf(".");
+			const segment = dot === -1 ? rest : rest.slice(0, dot);
+			if (segment) this.#taken.add(segment);
 		}
-		this.#nextId = maxId + 1;
+	}
+
+	/** Pick the first free name (base, then `base-2`, `base-3`, …) and reserve it. */
+	#allocateUnique(id: string): string {
+		let candidate = id;
+		for (let n = 2; this.#taken.has(candidate); n++) {
+			candidate = `${id}-${n}`;
+		}
+		this.#taken.add(candidate);
+		return this.#parentPrefix ? `${this.#parentPrefix}.${candidate}` : candidate;
 	}
 
 	/**
-	 * Allocate a unique ID with numeric prefix.
+	 * Allocate a unique ID.
 	 *
-	 * @param id Requested ID (e.g., "AuthProvider")
-	 * @returns Unique ID with prefix (e.g., "0-AuthProvider")
+	 * @param id Requested ID (e.g., "Anna")
+	 * @returns Unique ID ("Anna" first, then "Anna-2", "Anna-3", …)
 	 */
 	async allocate(id: string): Promise<string> {
 		await this.#ensureInitialized();
-		const prefix = this.#parentPrefix ? `${this.#parentPrefix}.` : "";
-		return `${prefix}${this.#nextId++}-${id}`;
+		return this.#allocateUnique(id);
 	}
 
 	/**
@@ -85,23 +94,6 @@ export class AgentOutputManager {
 	 */
 	async allocateBatch(ids: string[]): Promise<string[]> {
 		await this.#ensureInitialized();
-		const prefix = this.#parentPrefix ? `${this.#parentPrefix}.` : "";
-		return ids.map(id => `${prefix}${this.#nextId++}-${id}`);
-	}
-
-	/**
-	 * Get the next ID that would be allocated (without allocating).
-	 */
-	async peekNextIndex(): Promise<number> {
-		await this.#ensureInitialized();
-		return this.#nextId;
-	}
-
-	/**
-	 * Reset state (primarily for testing).
-	 */
-	reset(): void {
-		this.#nextId = 0;
-		this.#initialized = false;
+		return ids.map(id => this.#allocateUnique(id));
 	}
 }

package/src/task/render.ts

@@ -128,15 +128,10 @@ function formatJsonScalar(value: unknown, _theme: Theme): string {
 }
 
 function formatTaskId(id: string): string {
+	// Ids are name-based (e.g. "Anna", "Anna-2"); a "." separates nesting levels
+	// (e.g. "Anna.Bob"). Render the hierarchy with a ">" breadcrumb.
 	const segments = id.split(".");
-	if (segments.length < 2) return id;
-
-	const parsed = segments.map(segment => segment.match(/^(\d+)-(.+)$/));
-	if (parsed.some(match => !match)) return id;
-
-	const indices = parsed.map(match => match![1]).join(".");
-	const labels = parsed.map(match => match![2]).join(">");
-	return `${indices} ${labels}`;
+	return segments.length < 2 ? id : segments.join(">");
 }
 
 const MISSING_YIELD_WARNING_PREFIX = "SYSTEM WARNING: Subagent exited without calling yield tool";

package/src/tools/ask.ts

@@ -20,6 +20,7 @@ import { type Component, Container, Markdown, renderInlineMarkdown, TERMINAL, Te
 import { prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { ExtensionUISelectItem } from "../extensibility/extensions";
 import { getMarkdownTheme, type Theme, theme } from "../modes/theme/theme";
 import askDescription from "../prompts/tools/ask.md" with { type: "text" };
 import { renderStatusLine } from "../tui";
@@ -33,6 +34,7 @@ import { ToolAbortError } from "./tool-errors";
 
 const OptionItem = z.object({
 	label: z.string().describe("display label"),
+	description: z.string().describe("optional explanatory text displayed below the label").optional(),
 });
 
 const QuestionItem = z.object({
@@ -69,6 +71,23 @@ export interface AskToolDetails {
 	results?: QuestionResult[];
 }
 
+interface AskOption {
+	label: string;
+	description?: string;
+}
+
+function getAskOptionLabel(option: AskOption): string {
+	return option.label;
+}
+
+function getSelectOptionLabel(option: ExtensionUISelectItem): string {
+	return typeof option === "string" ? option : option.label;
+}
+
+function toSelectOption(option: AskOption, label = option.label): ExtensionUISelectItem {
+	return option.description ? { label, description: option.description } : label;
+}
+
 // =============================================================================
 // Constants
 // =============================================================================
@@ -81,24 +100,25 @@ function getDoneOptionLabel(): string {
 }
 
 /** Add "(Recommended)" suffix to the option at the given index if not already present */
-function addRecommendedSuffix(labels: string[], recommendedIndex?: number): string[] {
-	if (recommendedIndex === undefined || recommendedIndex < 0 || recommendedIndex >= labels.length) {
-		return labels;
+function addRecommendedSuffix(options: AskOption[], recommendedIndex?: number): ExtensionUISelectItem[] {
+	if (recommendedIndex === undefined || recommendedIndex < 0 || recommendedIndex >= options.length) {
+		return options.map(option => toSelectOption(option));
 	}
-	return labels.map((label, i) => {
-		if (i === recommendedIndex && !label.endsWith(RECOMMENDED_SUFFIX)) {
-			return label + RECOMMENDED_SUFFIX;
-		}
-		return label;
+	return options.map((option, i) => {
+		const label =
+			i === recommendedIndex && !option.label.endsWith(RECOMMENDED_SUFFIX)
+				? option.label + RECOMMENDED_SUFFIX
+				: option.label;
+		return toSelectOption(option, label);
 	});
 }
 
-function getAutoSelectionOnTimeout(optionLabels: string[], recommended?: number): string[] {
-	if (optionLabels.length === 0) return [];
-	if (typeof recommended === "number" && recommended >= 0 && recommended < optionLabels.length) {
-		return [optionLabels[recommended]];
+function getAutoSelectionOnTimeout(options: AskOption[], recommended?: number): string[] {
+	if (options.length === 0) return [];
+	if (typeof recommended === "number" && recommended >= 0 && recommended < options.length) {
+		return [options[recommended]!.label];
 	}
-	return [optionLabels[0]];
+	return [options[0]!.label];
 }
 
 /** Strip "(Recommended)" suffix from a label */
@@ -134,7 +154,7 @@ interface AskSingleQuestionOptions {
 interface UIContext {
 	select(
 		prompt: string,
-		options: string[],
+		options: ExtensionUISelectItem[],
 		options_?: {
 			initialIndex?: number;
 			timeout?: number;
@@ -157,7 +177,7 @@ interface UIContext {
 async function askSingleQuestion(
 	ui: UIContext,
 	question: string,
-	optionLabels: string[],
+	questionOptions: AskOption[],
 	multi: boolean,
 	options: AskSingleQuestionOptions = {},
 ): Promise<SelectionResult> {
@@ -169,7 +189,7 @@ async function askSingleQuestion(
 
 	const selectOption = async (
 		prompt: string,
-		optionsToShow: string[],
+		optionsToShow: ExtensionUISelectItem[],
 		initialIndex?: number,
 	): Promise<{ choice: string | undefined; timedOut: boolean; navigation?: "back" | "forward" }> => {
 		let timeoutTriggered = false;
@@ -218,18 +238,19 @@ async function askSingleQuestion(
 	const promptWithProgress = navigation?.progressText ? `${question} (${navigation.progressText})` : question;
 	if (multi) {
 		const selected = new Set<string>(selectedOptions);
-		let cursorIndex = Math.min(Math.max(recommended ?? 0, 0), Math.max(optionLabels.length - 1, 0));
+		let cursorIndex = Math.min(Math.max(recommended ?? 0, 0), Math.max(questionOptions.length - 1, 0));
 		const firstSelected = selectedOptions[0];
 		if (firstSelected) {
-			const selectedIndex = optionLabels.indexOf(firstSelected);
+			const selectedIndex = questionOptions.findIndex(option => option.label === firstSelected);
 			if (selectedIndex >= 0) cursorIndex = selectedIndex;
 		}
 		while (true) {
-			const opts: string[] = [];
+			const opts: ExtensionUISelectItem[] = [];
 
-			for (const opt of optionLabels) {
-				const checkbox = selected.has(opt) ? theme.checkbox.checked : theme.checkbox.unchecked;
-				opts.push(`${checkbox} ${opt}`);
+			for (const opt of questionOptions) {
+				const checkbox = selected.has(opt.label) ? theme.checkbox.checked : theme.checkbox.unchecked;
+				const displayLabel = `${checkbox} ${opt.label}`;
+				opts.push(toSelectOption(opt, displayLabel));
 			}
 
 			if (!navigation?.allowForward && selected.size > 0) {
@@ -269,7 +290,7 @@ async function askSingleQuestion(
 				break;
 			}
 
-			const selectedIdx = opts.indexOf(choice);
+			const selectedIdx = opts.findIndex(opt => getSelectOptionLabel(opt) === choice);
 			if (selectedIdx >= 0) {
 				cursorIndex = selectedIdx;
 			}
@@ -297,16 +318,16 @@ async function askSingleQuestion(
 		}
 		selectedOptions = Array.from(selected);
 	} else {
-		const displayLabels = addRecommendedSuffix(optionLabels, recommended);
-		const optionsWithNavigation = [...displayLabels, OTHER_OPTION];
+		const displayOptions = addRecommendedSuffix(questionOptions, recommended);
+		const optionsWithNavigation: ExtensionUISelectItem[] = [...displayOptions, OTHER_OPTION];
 
 		let initialIndex = recommended;
 		const previouslySelected = selectedOptions[0];
 		if (previouslySelected) {
-			const selectedIndex = optionLabels.indexOf(previouslySelected);
+			const selectedIndex = questionOptions.findIndex(option => option.label === previouslySelected);
 			if (selectedIndex >= 0) initialIndex = selectedIndex;
 		} else if (customInput !== undefined) {
-			initialIndex = displayLabels.length;
+			initialIndex = displayOptions.length;
 		}
 		if (initialIndex !== undefined) {
 			const maxIndex = Math.max(optionsWithNavigation.length - 1, 0);
@@ -346,7 +367,7 @@ async function askSingleQuestion(
 	}
 
 	if (timedOut && selectedOptions.length === 0 && customInput === undefined) {
-		selectedOptions = getAutoSelectionOnTimeout(optionLabels, recommended);
+		selectedOptions = getAutoSelectionOnTimeout(questionOptions, recommended);
 	}
 
 	return { selectedOptions, customInput, timedOut };
@@ -442,12 +463,16 @@ export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 			q: AskParams["questions"][number],
 			options?: { previous?: QuestionResult; navigation?: NavigationControls },
 		) => {
-			const optionLabels = q.options.map(o => o.label);
+			const questionOptions = q.options.map(option => ({
+				label: option.label,
+				...(option.description?.trim() ? { description: option.description.trim() } : {}),
+			}));
+			const optionLabels = questionOptions.map(getAskOptionLabel);
 			try {
 				const { selectedOptions, customInput, navigation, cancelled, timedOut } = await askSingleQuestion(
 					ui,
 					q.question,
-					optionLabels,
+					questionOptions,
 					q.multi ?? false,
 					{
 						recommended: q.recommended,
@@ -568,14 +593,19 @@ export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 // TUI Renderer
 // =============================================================================
 
+interface AskRenderOption {
+	label: string;
+	description?: string;
+}
+
 interface AskRenderArgs {
 	question?: string;
-	options?: Array<{ label: string }>;
+	options?: AskRenderOption[];
 	multi?: boolean;
 	questions?: Array<{
 		id: string;
 		question: string;
-		options: Array<{ label: string }>;
+		options: AskRenderOption[];
 		multi?: boolean;
 	}>;
 }
@@ -634,6 +664,13 @@ export const askToolRenderer = {
 						const optBranch = isLastOpt ? uiTheme.tree.last : uiTheme.tree.branch;
 						const optLabel = renderInlineMarkdown(opt.label, mdTheme, t => uiTheme.fg("muted", t));
 						optText += `\n ${uiTheme.fg("dim", continuation)}   ${uiTheme.fg("dim", optBranch)} ${uiTheme.fg("dim", uiTheme.checkbox.unchecked)} ${optLabel}`;
+						if (opt.description?.trim()) {
+							const optContinuation = isLastOpt ? " " : uiTheme.tree.vertical;
+							const description = renderInlineMarkdown(opt.description.trim(), mdTheme, t =>
+								uiTheme.fg("dim", t),
+							);
+							optText += `\n ${uiTheme.fg("dim", continuation)}   ${uiTheme.fg("dim", optContinuation)}   ${uiTheme.fg("dim", "↳")} ${description}`;
+						}
 					}
 					container.addChild(new Text(optText, 0, 0));
 				}
@@ -661,6 +698,11 @@ export const askToolRenderer = {
 				const branch = isLast ? uiTheme.tree.last : uiTheme.tree.branch;
 				const optLabel = renderInlineMarkdown(opt.label, mdTheme, t => uiTheme.fg("muted", t));
 				optText += `\n ${uiTheme.fg("dim", branch)} ${uiTheme.fg("dim", uiTheme.checkbox.unchecked)} ${optLabel}`;
+				if (opt.description?.trim()) {
+					const continuation = isLast ? " " : uiTheme.tree.vertical;
+					const description = renderInlineMarkdown(opt.description.trim(), mdTheme, t => uiTheme.fg("dim", t));
+					optText += `\n ${uiTheme.fg("dim", continuation)}   ${uiTheme.fg("dim", "↳")} ${description}`;
+				}
 			}
 			container.addChild(new Text(optText, 0, 0));
 		}

package/src/tools/browser/tab-worker.ts

@@ -815,18 +815,21 @@ export class WorkerCore {
 			{ maxWidth: 1024, maxHeight: 1024, maxBytes: 150 * 1024, jpegQuality: 70 },
 		);
 		const explicitPath = opts.save ? resolveToCwd(opts.save, session.cwd) : undefined;
+		const saveFullRes = !!(explicitPath || session.browserScreenshotDir);
+		const savedBuffer = saveFullRes ? buffer : resized.buffer;
+		const savedMimeType = saveFullRes ? "image/png" : resized.mimeType;
+		// Auto-generated names must match the bytes we actually write: full-res is always
+		// PNG, but the resized buffer is whichever of PNG/JPEG/WebP encoded smallest.
+		const ext = savedMimeType === "image/webp" ? "webp" : savedMimeType === "image/jpeg" ? "jpg" : "png";
 		const dest =
 			explicitPath ??
 			(session.browserScreenshotDir
 				? path.join(
 						session.browserScreenshotDir,
-						`screenshot-${new Date().toISOString().replace(/[:.]/g, "-").slice(0, -1)}.png`,
+						`screenshot-${new Date().toISOString().replace(/[:.]/g, "-").slice(0, -1)}.${ext}`,
 					)
-				: path.join(os.tmpdir(), `omp-sshots-${Snowflake.next()}.png`));
+				: path.join(os.tmpdir(), `omp-sshots-${Snowflake.next()}.${ext}`));
 		await fs.promises.mkdir(path.dirname(dest), { recursive: true });
-		const saveFullRes = !!(explicitPath || session.browserScreenshotDir);
-		const savedBuffer = saveFullRes ? buffer : resized.buffer;
-		const savedMimeType = saveFullRes ? "image/png" : resized.mimeType;
 		await Bun.write(dest, savedBuffer);
 		const info: ScreenshotResult = {
 			dest,

package/src/tools/eval-backends.ts

@@ -0,0 +1,38 @@
+import { $env, $flag } from "@oh-my-pi/pi-utils";
+import type { ToolSession } from ".";
+
+export interface EvalBackendsAllowance {
+	python: boolean;
+	js: boolean;
+}
+
+/**
+ * Parse PI_PY / PI_JS environment variables. Each is a boolean flag; unset
+ * means "not specified, defer to settings". Returns null when neither is set
+ * so the caller can fall through to `readEvalBackendsAllowance` per key.
+ */
+function getEvalBackendsFromEnv(): EvalBackendsAllowance | null {
+	const pyEnv = $env.PI_PY;
+	const jsEnv = $env.PI_JS;
+	if (pyEnv === undefined && jsEnv === undefined) return null;
+	return {
+		python: pyEnv === undefined ? true : $flag("PI_PY"),
+		js: jsEnv === undefined ? true : $flag("PI_JS"),
+	};
+}
+
+/** Read per-backend allowance from settings (defaults true). */
+export function readEvalBackendsAllowance(session: ToolSession): EvalBackendsAllowance {
+	return {
+		python: session.settings.get("eval.py") ?? true,
+		js: session.settings.get("eval.js") ?? true,
+	};
+}
+
+/**
+ * Materialize the active eval backend allowance: PI_PY / PI_JS env flags
+ * override the per-key settings; otherwise settings (defaults true) win.
+ */
+export function resolveEvalBackends(session: ToolSession): EvalBackendsAllowance {
+	return getEvalBackendsFromEnv() ?? readEvalBackendsAllowance(session);
+}