@oh-my-pi/pi-coding-agent 16.2.13 → 16.3.0

package/src/tools/output-schema-validator.ts

@@ -8,11 +8,13 @@
  * cannot be rejected post-mortem (or vice versa).
  */
 import {
+	dereferenceJsonSchema,
 	isValidJsonSchema,
 	type JsonSchemaValidationIssue,
 	type JsonSchemaValidationResult,
 	validateJsonSchemaValue,
 } from "@oh-my-pi/pi-ai/utils/schema";
+import { isRecord } from "@oh-my-pi/pi-utils";
 import { jtdToJsonSchema, normalizeSchema } from "./jtd-to-json-schema";
 
 /** A validator bound to a specific output schema. */
@@ -25,12 +27,15 @@ export interface OutputValidator {
 	 * Per-label validators for incremental yields (`type: ["<label>"]`). Each entry validates the
 	 * `data` payload of a single section against the matching top-level property's sub-schema —
 	 * array-typed properties (e.g. `findings`) use the items schema since each yield contributes
-	 * one element, while scalar properties use the property schema directly. Unknown labels (not
-	 * top-level properties) have no entry and skip per-call validation. Lets the yield tool give
-	 * the model retry feedback on a section as soon as it arrives, instead of deferring every
-	 * mismatch to the parent's post-mortem `schema_violation`.
+	 * one element, while scalar properties use the property schema directly.
 	 */
 	readonly validateSection: ReadonlyMap<string, (value: unknown) => JsonSchemaValidationResult>;
+	/** Whether top-level schema closure makes unknown incremental yield labels invalid. */
+	readonly rejectUnknownSections: boolean;
+	/** Finite top-level section labels declared directly by the schema. Pattern-backed labels are accepted via `isKnownSection`. */
+	readonly knownSectionLabels: readonly string[];
+	/** Whether an incremental yield label is accepted by the top-level schema declaration. */
+	isKnownSection(label: string): boolean;
 }
 
 export interface BuildOutputValidatorResult {
@@ -75,14 +80,28 @@ export function buildOutputValidator(schema: unknown): BuildOutputValidatorResul
 	if (!isValidJsonSchema(jsonSchema)) return { error: "invalid JSON schema", normalized };
 
 	const jsonSchemaRecord = jsonSchema as Record<string, unknown>;
-	const required = extractRequiredFields(jsonSchemaRecord);
+	// Resolve a root `$ref` (e.g. caller schemas exported as `{ $ref: "#/$defs/Closed", $defs: ... }`)
+	// before deriving incremental-label metadata. AJV-style validation chases the ref at runtime, so
+	// `validate()` accepts the resolved object — but `properties` and `additionalProperties` live on
+	// the inlined node, not the wrapper. Without this, unknown labels slipped past the yield gate and
+	// only fired as parent-side schema_violations.
+	const dereferenced = dereferenceJsonSchema(jsonSchemaRecord);
+	const labelSchema =
+		dereferenced && typeof dereferenced === "object" && !Array.isArray(dereferenced)
+			? (dereferenced as Record<string, unknown>)
+			: jsonSchemaRecord;
+	const required = extractRequiredFields(labelSchema);
+	const sectionLabels = buildSectionLabelMetadata(labelSchema);
 	return {
 		normalized,
 		jsonSchema: jsonSchemaRecord,
 		validator: {
 			requiredFields: required,
 			validate: value => validateJsonSchemaValue(jsonSchemaRecord, value),
-			validateSection: buildSectionValidators(jsonSchemaRecord),
+			validateSection: buildSectionValidators(labelSchema),
+			rejectUnknownSections: sectionLabels.rejectUnknownSections,
+			knownSectionLabels: sectionLabels.labels,
+			isKnownSection: sectionLabels.isKnown,
 		},
 	};
 }
@@ -93,27 +112,145 @@ export function buildOutputValidator(schema: unknown): BuildOutputValidatorResul
  * Each entry validates the `data` payload of one `type: ["<label>"]` section against the
  * matching property's sub-schema — array-typed properties (e.g. `findings`, derived from JTD
  * `elements`) use the items schema since each yield contributes one element, while scalar
- * properties use the property schema directly. Unknown labels (anything not declared as a
- * top-level property) are deliberately omitted so user-defined section labels still pass.
+ * properties use the property schema directly. Closed top-level schemas reject labels that are
+ * not declared as properties.
  */
 function buildSectionValidators(
 	jsonSchema: Record<string, unknown>,
 ): ReadonlyMap<string, (value: unknown) => JsonSchemaValidationResult> {
 	const validators = new Map<string, (value: unknown) => JsonSchemaValidationResult>();
 	const properties = jsonSchema.properties;
-	if (properties === null || typeof properties !== "object") return validators;
-	for (const [label, raw] of Object.entries(properties as Record<string, unknown>)) {
-		if (raw === null || typeof raw !== "object") continue;
-		const propRecord = raw as Record<string, unknown>;
+	if (!isRecord(properties)) return validators;
+	for (const label in properties) {
+		const raw = properties[label];
+		const propRecord = isRecord(raw) ? raw : undefined;
 		const sectionSchema =
-			propRecord.type === "array" && propRecord.items !== undefined && propRecord.items !== null
-				? (propRecord.items as Record<string, unknown>)
-				: propRecord;
+			propRecord?.type === "array" && propRecord.items !== undefined && propRecord.items !== null
+				? propRecord.items
+				: raw;
 		validators.set(label, value => validateJsonSchemaValue(sectionSchema, value));
 	}
 	return validators;
 }
 
+interface SectionLabelMetadata {
+	readonly labels: readonly string[];
+	readonly rejectUnknownSections: boolean;
+	isKnown(label: string): boolean;
+}
+
+/**
+ * Derive incremental-label metadata from top-level schema closure.
+ *
+ * The unknown-label gate (`rejectUnknownSections`) engages when the schema constrains top-level
+ * property names anywhere: a closed conjunct (root or recursive `allOf` child with
+ * `additionalProperties: false`) or a `oneOf`/`anyOf` union whose EVERY variant is closed. A label
+ * is known iff every closed conjunct accepts it AND, per closed union, at least one variant
+ * accepts it (union semantics are disjunctive — the assembled output only has to match one
+ * variant). Unions containing any open variant never gate: the open variant accepts arbitrary
+ * labels, so rejection would be a false positive.
+ */
+function buildSectionLabelMetadata(jsonSchema: Record<string, unknown>): SectionLabelMetadata {
+	const closedConjuncts = collectClosedTopLevelSchemas(jsonSchema);
+	const closedUnions = collectClosedTopLevelUnions(jsonSchema);
+	const closed = closedConjuncts.length > 0 || closedUnions.length > 0;
+	const acceptedByAll = (conjuncts: readonly Record<string, unknown>[], label: string): boolean =>
+		conjuncts.every(schema => schemaAcceptsSectionLabel(schema, label));
+	const labels = [
+		...new Set([
+			...closedConjuncts.flatMap(schema => declaredPropertyLabels(schema)),
+			...closedUnions.flatMap(variants =>
+				variants.flatMap(conjuncts => conjuncts.flatMap(schema => declaredPropertyLabels(schema))),
+			),
+		]),
+	];
+	return {
+		labels,
+		rejectUnknownSections: closed,
+		isKnown: label =>
+			!closed ||
+			(acceptedByAll(closedConjuncts, label) &&
+				closedUnions.every(variants => variants.some(conjuncts => acceptedByAll(conjuncts, label)))),
+	};
+}
+
+function collectClosedTopLevelSchemas(jsonSchema: Record<string, unknown>): Record<string, unknown>[] {
+	const schemas: Record<string, unknown>[] = [];
+	if (jsonSchema.additionalProperties === false) schemas.push(jsonSchema);
+	const allOf = jsonSchema.allOf;
+	if (Array.isArray(allOf)) {
+		for (const raw of allOf) {
+			if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+				schemas.push(...collectClosedTopLevelSchemas(raw as Record<string, unknown>));
+			}
+		}
+	}
+	return schemas;
+}
+
+/** One fully-closed `oneOf`/`anyOf` union: per variant, that variant's closed conjunct schemas. */
+type ClosedUnionVariants = Record<string, unknown>[][];
+
+/**
+ * Collect top-level `oneOf`/`anyOf` unions in which EVERY variant is closed — i.e. each variant
+ * (or one of its `allOf` conjuncts, resolved via `collectClosedTopLevelSchemas`) carries
+ * `additionalProperties: false`. JTD discriminator output schemas compile to exactly this shape:
+ * a root `oneOf` of closed object variants. Unions with any open (or non-object) variant are
+ * skipped entirely so the unknown-label gate cannot fire false rejections. Unions nested under
+ * `allOf` conjuncts gate identically (intersection semantics).
+ */
+function collectClosedTopLevelUnions(jsonSchema: Record<string, unknown>): ClosedUnionVariants[] {
+	const unions: ClosedUnionVariants[] = [];
+	for (const key of ["oneOf", "anyOf"] as const) {
+		const rawVariants = jsonSchema[key];
+		if (!Array.isArray(rawVariants) || rawVariants.length === 0) continue;
+		const variants: ClosedUnionVariants = [];
+		let allClosed = true;
+		for (const raw of rawVariants) {
+			const conjuncts = isRecord(raw) ? collectClosedTopLevelSchemas(raw) : [];
+			if (conjuncts.length === 0) {
+				allClosed = false;
+				break;
+			}
+			variants.push(conjuncts);
+		}
+		if (allClosed) unions.push(variants);
+	}
+	const allOf = jsonSchema.allOf;
+	if (Array.isArray(allOf)) {
+		for (const raw of allOf) {
+			if (isRecord(raw)) unions.push(...collectClosedTopLevelUnions(raw));
+		}
+	}
+	return unions;
+}
+
+function declaredPropertyLabels(jsonSchema: Record<string, unknown>): string[] {
+	const properties = jsonSchema.properties;
+	if (properties === null || typeof properties !== "object" || Array.isArray(properties)) return [];
+	const labels: string[] = [];
+	for (const label in properties) labels.push(label);
+	return labels;
+}
+
+function schemaAcceptsSectionLabel(jsonSchema: Record<string, unknown>, label: string): boolean {
+	const properties = jsonSchema.properties;
+	if (properties !== null && typeof properties === "object" && !Array.isArray(properties) && label in properties) {
+		return true;
+	}
+	const patternProperties = jsonSchema.patternProperties;
+	if (patternProperties !== null && typeof patternProperties === "object" && !Array.isArray(patternProperties)) {
+		for (const pattern in patternProperties) {
+			try {
+				if (new RegExp(pattern).test(label)) return true;
+			} catch {
+				// `isValidJsonSchema` already rejected malformed regexes; ignore any unexpected runtime mismatch.
+			}
+		}
+	}
+	return jsonSchema.additionalProperties !== false;
+}
+
 /** Produce the executor's headline+missing-required summary from a failed validation. */
 export function summarizeValidationFailure(
 	result: JsonSchemaValidationResult,

package/src/tools/path-utils.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as url from "node:url";
-import { isEnoent, stripWindowsExtendedLengthPathPrefix } from "@oh-my-pi/pi-utils";
+import { isEnoent, isEnotdir, stripWindowsExtendedLengthPathPrefix } from "@oh-my-pi/pi-utils";
 import type { Skill } from "../extensibility/skills";
 import { InternalUrlRouter, type LocalProtocolOptions } from "../internal-urls";
 import { ToolError } from "./tool-errors";
@@ -435,6 +435,16 @@ export function isSshUrl(path: string): boolean {
 	return /^ssh:\/\//i.test(path.trim());
 }
 
+/**
+ * True when the read tool's URL parser (`parseReadUrlTarget` in fetch.ts) would
+ * recognize this path as a readable external URL: a strict `http(s)://`, a
+ * collapsed `http(s):/host` (Node path normalization folds `//` → `/`), or a
+ * scheme-less `www.` spelling. Keep in sync with `parseReadUrlTarget`.
+ */
+export function isReadableUrlPath(value: string): boolean {
+	return /^https?:\/\/?/i.test(value) || /^www\./i.test(value);
+}
+
 /**
  * Resolve a path relative to the given cwd.
  * Handles ~ expansion and absolute paths.
@@ -1026,6 +1036,14 @@ export function resolveReadPath(filePath: string, cwd: string): string {
 // Tool-scope resolution (search/ast tools)
 // =============================================================================
 
+/** Local file materialized from a readable external URL for shared tool-scope resolution. */
+export interface ResolvedExternalSearchUrl {
+	/** Absolute or cwd-relative file path to search. */
+	sourcePath: string;
+	/** True when the materialized file must not mint editable anchors. */
+	immutable?: boolean;
+}
+
 export interface ToolScopeOptions {
 	rawPaths: string[];
 	cwd: string;
@@ -1049,6 +1067,8 @@ export interface ToolScopeOptions {
 	localProtocolOptions?: LocalProtocolOptions;
 	/** Calling session's loaded skills — lets skill:// resolve without process-global state. */
 	skills?: readonly Skill[];
+	/** Materialize readable external URLs to local text files before scope derivation. */
+	resolveExternalUrl?: (rawPath: string) => Promise<ResolvedExternalSearchUrl | undefined>;
 }
 
 export interface ToolScopeResolution {
@@ -1080,19 +1100,44 @@ export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<To
 	if (rawPaths.some(rawPath => rawPath.length === 0)) {
 		throw new ToolError("`paths` must contain non-empty paths or globs");
 	}
-	// External (http/https/ftp/file) URLs are not searchable; route the caller
-	// to `read` instead of letting the path-resolver surface a confusing
-	// "Path not found" for a slash-stripped URL.
-	const externalUrl = rawPaths.find(rawPath => /^(?:https?|ftp|file|ws|wss):\/\//i.test(rawPath));
-	if (externalUrl) {
-		throw new ToolError(
-			`Cannot ${internalUrlAction} external URL: ${externalUrl}. Use \`read\` to fetch web content, then search the returned text.`,
-		);
-	}
+	// Strict external-URL schemes. `file://` is intentionally absent: it has
+	// local-path semantics (expandPath strips it downstream), so it flows through
+	// the ordinary filesystem pipeline instead of the external-URL resolver.
+	const strictExternalUrlRe = /^(?:https?|ftp|ws|wss):\/\//i;
 	const internalRouter = InternalUrlRouter.instance();
 	const resolvedPathInputs: string[] = [];
 	const immutableSourcePaths = new Set<string>();
 	for (const rawPath of rawPaths) {
+		let externalUrl = strictExternalUrlRe.test(rawPath);
+		if (!externalUrl && isReadableUrlPath(rawPath) && !hasGlobPathChars(rawPath)) {
+			// Fuzzy spelling the read parser accepts (`www.host/…`, collapsed
+			// `https:/host/…`). An existing local path wins over URL
+			// interpretation so a directory literally named `www.foo` stays
+			// searchable; only a definitive ENOENT/ENOTDIR flips to URL handling
+			// (any other stat error means the path exists — let the local
+			// pipeline surface it).
+			try {
+				await fs.promises.stat(resolveToCwd(rawPath, cwd));
+			} catch (err) {
+				externalUrl = isEnoent(err) || isEnotdir(err);
+			}
+		}
+		if (externalUrl) {
+			const resolved = opts.resolveExternalUrl ? await opts.resolveExternalUrl(rawPath) : undefined;
+			if (resolved) {
+				resolvedPathInputs.push(resolved.sourcePath);
+				if (opts.trackImmutableSources && resolved.immutable) {
+					immutableSourcePaths.add(path.resolve(resolved.sourcePath));
+				}
+				continue;
+			}
+			// Resolver missing or declined (e.g. ftp/ws/wss): fail explicitly
+			// instead of letting the local-path fallthrough surface a confusing
+			// "Path not found" for a URL-shaped input.
+			throw new ToolError(
+				`Cannot ${internalUrlAction} external URL: ${rawPath}. Use \`read\` to fetch web content, then search the returned text.`,
+			);
+		}
 		if (!internalRouter.canHandle(rawPath)) {
 			resolvedPathInputs.push(rawPath);
 			continue;

package/src/tools/read.ts

@@ -77,7 +77,6 @@ import {
 } from "./conflict-detect";
 import {
 	executeReadUrl,
-	isReadableUrlPath,
 	loadReadUrlCacheEntry,
 	parseReadUrlTarget,
 	type ReadUrlToolDetails,
@@ -95,6 +94,7 @@ import {
 import {
 	expandPath,
 	formatPathRelativeToCwd,
+	isReadableUrlPath,
 	type LineRange,
 	parseLineRanges,
 	pathTargetsSsh,

package/src/tools/render-utils.ts

@@ -222,19 +222,21 @@ export function previewWindowRows(): number {
  * (ctrl+o) uncaps it.
  *
  * `prefix` (raw, e.g. a dim tree gutter) is prepended to the marker line so
- * nested previews stay aligned.
+ * nested previews stay aligned. `expandHint: false` drops the "ctrl+o: Expand"
+ * suffix for callers that cap even inside the expanded view (task recent
+ * output), where the hint would point the wrong way.
  */
 export function capPreviewLines(
 	lines: string[],
 	theme: Theme,
-	options: { max?: number; expanded?: boolean; prefix?: string } = {},
+	options: { max?: number; expanded?: boolean; prefix?: string; expandHint?: boolean } = {},
 ): string[] {
 	if (options.expanded) return lines;
 	const max = options.max ?? previewWindowRows();
 	if (lines.length <= max) return lines;
 	const visible = max <= 1 ? [] : lines.slice(lines.length - (max - 1));
 	const hidden = lines.length - visible.length;
-	const hint = formatExpandHint(theme, false, true);
+	const hint = options.expandHint === false ? "" : formatExpandHint(theme, false, true);
 	const marker = `… ${hidden} earlier ${pluralize("line", hidden)}${hint ? ` ${hint}` : ""}`;
 	return [`${options.prefix ?? ""}${theme.fg("dim", marker)}`, ...visible];
 }

package/src/tools/yield.ts

@@ -213,11 +213,17 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 
 	readonly #validate?: (value: unknown) => JsonSchemaValidationResult;
 	readonly #validateSection?: ReadonlyMap<string, (value: unknown) => JsonSchemaValidationResult>;
+	#rejectUnknownSections = false;
+	#knownSectionLabels: readonly string[] = [];
+	#isKnownSection?: (label: string) => boolean;
 	#schemaValidationFailures = 0;
 
 	constructor(session: ToolSession) {
 		let validate: ((value: unknown) => JsonSchemaValidationResult) | undefined;
 		let validateSection: ReadonlyMap<string, (value: unknown) => JsonSchemaValidationResult> | undefined;
+		let rejectUnknownSections = false;
+		let knownSectionLabels: readonly string[] = [];
+		let isKnownSection: ((label: string) => boolean) | undefined;
 		let parameters: TSchema;
 
 		try {
@@ -230,6 +236,9 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 			if (validator) {
 				validate = value => validator.validate(value);
 				validateSection = validator.validateSection;
+				rejectUnknownSections = validator.rejectUnknownSections;
+				knownSectionLabels = validator.knownSectionLabels;
+				isKnownSection = label => validator.isKnownSection(label);
 			}
 
 			const schemaHint = formatSchema(normalizedSchema ?? session.outputSchema);
@@ -280,6 +289,9 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 
 		this.#validate = validate;
 		this.#validateSection = validateSection;
+		this.#rejectUnknownSections = rejectUnknownSections;
+		this.#knownSectionLabels = knownSectionLabels;
+		this.#isKnownSection = isKnownSection;
 		this.parameters = parameters;
 	}
 
@@ -317,6 +329,21 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 
 		const status = errorMessage !== undefined ? "aborted" : "success";
 		let schemaValidationOverridden = false;
+		// Unknown incremental labels are a hard contract mismatch with the closed caller
+		// schema. Reject before the last-turn short-circuit too: `type: ["findings"], result: {}`
+		// would otherwise be accepted as a typed last-turn incremental yield, then a sibling
+		// section's MAX_SCHEMA_RETRIES override flips schemaOverridden in finalization and the
+		// stale section rides along untouched.
+		if (status === "success" && isIncremental) {
+			const unknownLabels = this.#unknownIncrementalLabels(yieldType as string[]);
+			if (unknownLabels.length > 0) {
+				const validLabels =
+					this.#knownSectionLabels.length > 0 ? formatYieldLabels(this.#knownSectionLabels) : "none";
+				throw new Error(
+					`Section ${formatYieldLabels(yieldType as string[])} uses unknown incremental yield label(s): ${formatYieldLabels(unknownLabels)}. Resubmit with one of the schema's labels: ${validLabels}.`,
+				);
+			}
+		}
 		if (status === "success" && !useLastTurn) {
 			if (data === null) {
 				throw new Error("data is required when yield indicates success");
@@ -362,13 +389,26 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 		};
 	}
 
+	/**
+	 * Return incremental yield labels the closed caller schema does not accept. Closure covers the
+	 * root, `allOf` conjuncts, and `oneOf`/`anyOf` unions whose every variant is closed (e.g. JTD
+	 * discriminators). Open schemas accept any label.
+	 */
+	#unknownIncrementalLabels(labels: string[]): string[] {
+		if (!this.#rejectUnknownSections) return [];
+		const isKnown = this.#isKnownSection;
+		if (!isKnown) return [];
+		return labels.filter(label => !isKnown(label));
+	}
+
 	/**
 	 * Validate the `data` payload of an incremental yield (`type: ["<label>", …]`) against
 	 * the matching property's sub-validator. Returns the first failure across all known labels,
 	 * or `undefined` when no label is recognised (user-defined section labels stay loose) or
 	 * when all known labels accept the value. Lets the model see the same retry feedback that
 	 * the terminal-yield path already produces, instead of leaking the mismatch through to
-	 * the parent's post-mortem `schema_violation`.
+	 * the parent's post-mortem `schema_violation`. Unknown labels under a closed schema are
+	 * handled separately by `#unknownIncrementalLabels` and never reach this validator.
 	 */
 	#validateIncrementalSection(labels: string[], data: unknown): JsonSchemaValidationResult | undefined {
 		const subValidators = this.#validateSection;

package/src/utils/commit-message-generator.ts

@@ -12,7 +12,7 @@ import { getModelMatchPreferences, resolveModelRoleValue } from "../config/model
 import type { Settings } from "../config/settings";
 import MODEL_PRIO from "../priority.json" with { type: "json" };
 import commitSystemPrompt from "../prompts/system/commit-message-system.md" with { type: "text" };
-import { toReasoningEffort } from "../thinking";
+import { concreteThinkingLevel, toReasoningEffort } from "../thinking";
 
 const COMMIT_SYSTEM_PROMPT = prompt.render(commitSystemPrompt);
 const MAX_DIFF_CHARS = 4000;
@@ -56,7 +56,7 @@ function getSmolModelCandidates(
 		settings,
 		matchPreferences,
 	});
-	addCandidate(configuredSmol.model, configuredSmol.thinkingLevel);
+	addCandidate(configuredSmol.model, concreteThinkingLevel(configuredSmol.thinkingLevel));
 
 	for (const pattern of MODEL_PRIO.smol) {
 		const needle = pattern.toLowerCase();