@oh-my-pi/pi-coding-agent 14.9.9 → 15.0.1

package/src/commit/analysis/conventional.ts

@@ -1,52 +1,16 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
-import { completeSimple, validateToolCall } from "@oh-my-pi/pi-ai";
+import type { Api, Model } from "@oh-my-pi/pi-ai";
+import { completeSimple } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
-import { Type } from "@sinclair/typebox";
 import analysisSystemPrompt from "../../commit/prompts/analysis-system.md" with { type: "text" };
 import analysisUserPrompt from "../../commit/prompts/analysis-user.md" with { type: "text" };
-import type { ChangelogCategory, ConventionalAnalysis } from "../../commit/types";
+import type { ConventionalAnalysis } from "../../commit/types";
 import { toReasoningEffort } from "../../thinking";
-import { extractTextContent, extractToolCall, normalizeAnalysis, parseJsonPayload } from "../utils";
+import { createConventionalAnalysisTool, parseConventionalAnalysisResponse } from "../shared-llm";
 
-const ConventionalAnalysisTool = {
-	name: "create_conventional_analysis",
-	description: "Analyze a diff and return conventional commit classification.",
-	parameters: Type.Object({
-		type: Type.Union([
-			Type.Literal("feat"),
-			Type.Literal("fix"),
-			Type.Literal("refactor"),
-			Type.Literal("docs"),
-			Type.Literal("test"),
-			Type.Literal("chore"),
-			Type.Literal("style"),
-			Type.Literal("perf"),
-			Type.Literal("build"),
-			Type.Literal("ci"),
-			Type.Literal("revert"),
-		]),
-		scope: Type.Union([Type.String(), Type.Null()]),
-		details: Type.Array(
-			Type.Object({
-				text: Type.String(),
-				changelog_category: Type.Optional(
-					Type.Union([
-						Type.Literal("Added"),
-						Type.Literal("Changed"),
-						Type.Literal("Fixed"),
-						Type.Literal("Deprecated"),
-						Type.Literal("Removed"),
-						Type.Literal("Security"),
-						Type.Literal("Breaking Changes"),
-					]),
-				),
-				user_visible: Type.Optional(Type.Boolean()),
-			}),
-		),
-		issue_refs: Type.Array(Type.String()),
-	}),
-};
+const ConventionalAnalysisTool = createConventionalAnalysisTool(
+	"Analyze a diff and return conventional commit classification.",
+);
 
 export interface ConventionalAnalysisInput {
 	model: Model<Api>;
@@ -96,27 +60,5 @@ export async function generateConventionalAnalysis({
 		{ apiKey, maxTokens: 2400, reasoning: toReasoningEffort(thinkingLevel) },
 	);
 
-	return parseAnalysisFromResponse(response);
-}
-
-function parseAnalysisFromResponse(message: AssistantMessage): ConventionalAnalysis {
-	const toolCall = extractToolCall(message, "create_conventional_analysis");
-	if (toolCall) {
-		const parsed = validateToolCall([ConventionalAnalysisTool], toolCall) as {
-			type: ConventionalAnalysis["type"];
-			scope: string | null;
-			details: Array<{ text: string; changelog_category?: ChangelogCategory; user_visible?: boolean }>;
-			issue_refs: string[];
-		};
-		return normalizeAnalysis(parsed);
-	}
-
-	const text = extractTextContent(message);
-	const parsed = parseJsonPayload(text) as {
-		type: ConventionalAnalysis["type"];
-		scope: string | null;
-		details: Array<{ text: string; changelog_category?: ChangelogCategory; user_visible?: boolean }>;
-		issue_refs: string[];
-	};
-	return normalizeAnalysis(parsed);
+	return parseConventionalAnalysisResponse(response, ConventionalAnalysisTool);
 }

package/src/commit/map-reduce/reduce-phase.ts

@@ -1,52 +1,14 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
-import { completeSimple, validateToolCall } from "@oh-my-pi/pi-ai";
+import type { Api, Model } from "@oh-my-pi/pi-ai";
+import { completeSimple } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
-import { Type } from "@sinclair/typebox";
 import reduceSystemPrompt from "../../commit/prompts/reduce-system.md" with { type: "text" };
 import reduceUserPrompt from "../../commit/prompts/reduce-user.md" with { type: "text" };
-import type { ChangelogCategory, ConventionalAnalysis, FileObservation } from "../../commit/types";
+import type { ConventionalAnalysis, FileObservation } from "../../commit/types";
 import { toReasoningEffort } from "../../thinking";
-import { extractTextContent, extractToolCall, normalizeAnalysis, parseJsonPayload } from "../utils";
+import { createConventionalAnalysisTool, parseConventionalAnalysisResponse } from "../shared-llm";
 
-const ReduceTool = {
-	name: "create_conventional_analysis",
-	description: "Synthesize file observations into a conventional commit analysis.",
-	parameters: Type.Object({
-		type: Type.Union([
-			Type.Literal("feat"),
-			Type.Literal("fix"),
-			Type.Literal("refactor"),
-			Type.Literal("docs"),
-			Type.Literal("test"),
-			Type.Literal("chore"),
-			Type.Literal("style"),
-			Type.Literal("perf"),
-			Type.Literal("build"),
-			Type.Literal("ci"),
-			Type.Literal("revert"),
-		]),
-		scope: Type.Union([Type.String(), Type.Null()]),
-		details: Type.Array(
-			Type.Object({
-				text: Type.String(),
-				changelog_category: Type.Optional(
-					Type.Union([
-						Type.Literal("Added"),
-						Type.Literal("Changed"),
-						Type.Literal("Fixed"),
-						Type.Literal("Deprecated"),
-						Type.Literal("Removed"),
-						Type.Literal("Security"),
-						Type.Literal("Breaking Changes"),
-					]),
-				),
-				user_visible: Type.Optional(Type.Boolean()),
-			}),
-		),
-		issue_refs: Type.Array(Type.String()),
-	}),
-};
+const ReduceTool = createConventionalAnalysisTool("Synthesize file observations into a conventional commit analysis.");
 
 export interface ReducePhaseInput {
 	model: Model<Api>;
@@ -83,26 +45,5 @@ export async function runReducePhase({
 		{ apiKey, maxTokens: 2400, reasoning: toReasoningEffort(thinkingLevel) },
 	);
 
-	return parseAnalysisResponse(response);
-}
-
-function parseAnalysisResponse(message: AssistantMessage): ConventionalAnalysis {
-	const toolCall = extractToolCall(message, "create_conventional_analysis");
-	if (toolCall) {
-		const parsed = validateToolCall([ReduceTool], toolCall) as {
-			type: ConventionalAnalysis["type"];
-			scope: string | null;
-			details: Array<{ text: string; changelog_category?: ChangelogCategory; user_visible?: boolean }>;
-			issue_refs: string[];
-		};
-		return normalizeAnalysis(parsed);
-	}
-	const text = extractTextContent(message);
-	const parsed = parseJsonPayload(text) as {
-		type: ConventionalAnalysis["type"];
-		scope: string | null;
-		details: Array<{ text: string; changelog_category?: ChangelogCategory; user_visible?: boolean }>;
-		issue_refs: string[];
-	};
-	return normalizeAnalysis(parsed);
+	return parseConventionalAnalysisResponse(response, ReduceTool);
 }

package/src/commit/pipeline.ts

@@ -25,8 +25,8 @@ import type { CommitCommandArgs, ConventionalAnalysis } from "./types";
 
 const SUMMARY_MAX_CHARS = 72;
 const RECENT_COMMITS_COUNT = 8;
-let _typesDescription: string | undefined;
-const TYPES_DESCRIPTION = (): string => (_typesDescription ??= prompt.render(typesDescriptionPrompt));
+let typesDescription: string | undefined;
+const TYPES_DESCRIPTION = (): string => (typesDescription ??= prompt.render(typesDescriptionPrompt));
 
 /**
  * Execute the omp commit pipeline for staged changes.

package/src/commit/shared-llm.ts

@@ -0,0 +1,89 @@
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import { validateToolCall } from "@oh-my-pi/pi-ai";
+import { Type } from "@sinclair/typebox";
+import type { ChangelogCategory, ConventionalAnalysis } from "./types";
+import { extractTextContent, extractToolCall, normalizeAnalysis, parseJsonPayload } from "./utils";
+
+/**
+ * Shared TypeBox schema for the `create_conventional_analysis` tool used by
+ * both the single-pass analysis call and the map-reduce reduce phase. Schemas
+ * are identical across phases — only the surrounding tool `description`
+ * differs to reflect the input the phase is summarizing.
+ */
+export const conventionalAnalysisParameters = Type.Object({
+	type: Type.Union([
+		Type.Literal("feat"),
+		Type.Literal("fix"),
+		Type.Literal("refactor"),
+		Type.Literal("docs"),
+		Type.Literal("test"),
+		Type.Literal("chore"),
+		Type.Literal("style"),
+		Type.Literal("perf"),
+		Type.Literal("build"),
+		Type.Literal("ci"),
+		Type.Literal("revert"),
+	]),
+	scope: Type.Union([Type.String(), Type.Null()]),
+	details: Type.Array(
+		Type.Object({
+			text: Type.String(),
+			changelog_category: Type.Optional(
+				Type.Union([
+					Type.Literal("Added"),
+					Type.Literal("Changed"),
+					Type.Literal("Fixed"),
+					Type.Literal("Deprecated"),
+					Type.Literal("Removed"),
+					Type.Literal("Security"),
+					Type.Literal("Breaking Changes"),
+				]),
+			),
+			user_visible: Type.Optional(Type.Boolean()),
+		}),
+	),
+	issue_refs: Type.Array(Type.String()),
+});
+
+export interface ConventionalAnalysisTool {
+	name: "create_conventional_analysis";
+	description: string;
+	parameters: typeof conventionalAnalysisParameters;
+}
+
+/**
+ * Build a `create_conventional_analysis` tool descriptor. Phase-specific
+ * `description` text is the only thing that varies between callers.
+ */
+export function createConventionalAnalysisTool(description: string): ConventionalAnalysisTool {
+	return {
+		name: "create_conventional_analysis",
+		description,
+		parameters: conventionalAnalysisParameters,
+	};
+}
+
+interface ParsedConventionalAnalysis {
+	type: ConventionalAnalysis["type"];
+	scope: string | null;
+	details: Array<{ text: string; changelog_category?: ChangelogCategory; user_visible?: boolean }>;
+	issue_refs: string[];
+}
+
+/**
+ * Extract a {@link ConventionalAnalysis} from an assistant response, preferring
+ * a structured tool call and falling back to JSON embedded in text content.
+ */
+export function parseConventionalAnalysisResponse(
+	message: AssistantMessage,
+	tool: ConventionalAnalysisTool,
+): ConventionalAnalysis {
+	const toolCall = extractToolCall(message, tool.name);
+	if (toolCall) {
+		const parsed = validateToolCall([tool], toolCall) as ParsedConventionalAnalysis;
+		return normalizeAnalysis(parsed);
+	}
+	const text = extractTextContent(message);
+	const parsed = parseJsonPayload(text) as ParsedConventionalAnalysis;
+	return normalizeAnalysis(parsed);
+}

package/src/config/config-file.ts

@@ -0,0 +1,210 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import type { ErrorObject } from "ajv";
+import { JSONC, YAML } from "bun";
+
+function migrateJsonToYml(jsonPath: string, ymlPath: string) {
+	try {
+		if (fs.existsSync(ymlPath)) return;
+		if (!fs.existsSync(jsonPath)) return;
+
+		const content = fs.readFileSync(jsonPath, "utf-8");
+		const parsed = JSON.parse(content);
+		if (!parsed) {
+			logger.warn("migrateJsonToYml: invalid json structure", { path: jsonPath });
+			return;
+		}
+		fs.writeFileSync(ymlPath, YAML.stringify(parsed, null, 2));
+	} catch (error) {
+		logger.warn("migrateJsonToYml: migration failed", { error: String(error) });
+	}
+}
+
+export interface IConfigFile<T> {
+	readonly id: string;
+	readonly schema: TSchema;
+	path?(): string;
+	load(): T | null;
+	invalidate?(): void;
+}
+
+export class ConfigError extends Error {
+	readonly #message: string;
+	constructor(
+		public readonly id: string,
+		public readonly schemaErrors: ErrorObject[] | null | undefined,
+		public readonly other?: { err: unknown; stage: string },
+	) {
+		let messages: string[] | undefined;
+		let cause: Error | undefined;
+		let klass: string;
+
+		if (schemaErrors) {
+			klass = "Schema";
+			messages = schemaErrors.map(e => `${e.instancePath || "root"}: ${e.message}`);
+		} else if (other) {
+			klass = other.stage;
+			if (other.err instanceof Error) {
+				messages = [other.err.message];
+				cause = other.err;
+			} else {
+				messages = [String(other.err)];
+			}
+		} else {
+			klass = "Unknown";
+		}
+
+		const title = `Failed to load config file ${id}, ${klass} error:`;
+		let message: string;
+		switch (messages?.length ?? 0) {
+			case 0:
+				message = title.slice(0, -1);
+				break;
+			case 1:
+				message = `${title} ${messages![0]}`;
+				break;
+			default:
+				message = `${title}\n${messages!.map(m => `  - ${m}`).join("\n")}`;
+				break;
+		}
+
+		super(message, { cause });
+		this.name = "LoadError";
+		this.#message = message;
+	}
+
+	get message(): string {
+		return this.#message;
+	}
+
+	toString(): string {
+		return this.message;
+	}
+}
+
+export type LoadStatus = "ok" | "error" | "not-found";
+
+export type LoadResult<T> =
+	| { value?: null; error: ConfigError; status: "error" }
+	| { value: T; error?: undefined; status: "ok" }
+	| { value?: null; error?: unknown; status: "not-found" };
+
+export class ConfigFile<T> implements IConfigFile<T> {
+	readonly #basePath: string;
+	#cache?: LoadResult<T>;
+	#auxValidate?: (value: T) => void;
+
+	constructor(
+		readonly id: string,
+		readonly schema: TSchema,
+		configPath: string = path.join(getAgentDir(), `${id}.yml`),
+	) {
+		this.#basePath = configPath;
+		if (configPath.endsWith(".yml")) {
+			const jsonPath = `${configPath.slice(0, -4)}.json`;
+			migrateJsonToYml(jsonPath, configPath);
+		} else if (configPath.endsWith(".yaml")) {
+			const jsonPath = `${configPath.slice(0, -5)}.json`;
+			migrateJsonToYml(jsonPath, configPath);
+		} else if (configPath.endsWith(".json") || configPath.endsWith(".jsonc")) {
+			// JSON configs are still supported without migration.
+		} else {
+			throw new Error(`Invalid config file path: ${configPath}`);
+		}
+	}
+
+	relocate(configPath?: string): ConfigFile<T> {
+		if (!configPath || configPath === this.#basePath) return this;
+		const result = new ConfigFile<T>(this.id, this.schema, configPath);
+		result.#auxValidate = this.#auxValidate;
+		return result;
+	}
+
+	getMtimeMs(): number | null {
+		try {
+			return fs.statSync(this.path()).mtimeMs;
+		} catch (err) {
+			if (isEnoent(err)) return null;
+			throw err;
+		}
+	}
+
+	withValidation(name: string, validate: (value: T) => void): this {
+		const prev = this.#auxValidate;
+		this.#auxValidate = (value: T) => {
+			prev?.(value);
+			try {
+				validate(value);
+			} catch (error) {
+				throw new ConfigError(this.id, undefined, { err: error, stage: `Validate(${name})` });
+			}
+		};
+		return this;
+	}
+
+	createDefault(): T {
+		return Value.Default(this.schema, [], undefined) as T;
+	}
+
+	#storeCache(result: LoadResult<T>): LoadResult<T> {
+		this.#cache = result;
+		return result;
+	}
+
+	tryLoad(): LoadResult<T> {
+		if (this.#cache) return this.#cache;
+
+		try {
+			const content = fs.readFileSync(this.path(), "utf-8").trim();
+
+			let parsed: unknown;
+			if (this.#basePath.endsWith(".json") || this.#basePath.endsWith(".jsonc")) {
+				parsed = JSONC.parse(content);
+			} else if (this.#basePath.endsWith(".yml") || this.#basePath.endsWith(".yaml")) {
+				parsed = YAML.parse(content);
+			} else {
+				throw new Error(`Invalid config file path: ${this.#basePath}`);
+			}
+
+			if (!Value.Check(this.schema, parsed)) {
+				const schemaErrors: ErrorObject[] = [];
+				for (const err of Value.Errors(this.schema, parsed)) {
+					schemaErrors.push({ instancePath: err.path, message: err.message } as ErrorObject);
+					if (schemaErrors.length >= 50) break;
+				}
+				const error = new ConfigError(this.id, schemaErrors);
+				logger.warn("Failed to parse config file", { path: this.path(), error });
+				return this.#storeCache({ error, status: "error" });
+			}
+			return this.#storeCache({ value: parsed as T, status: "ok" });
+		} catch (error) {
+			if (isEnoent(error)) {
+				return this.#storeCache({ status: "not-found" });
+			}
+			logger.warn("Failed to parse config file", { path: this.path(), error });
+			return this.#storeCache({
+				error: new ConfigError(this.id, undefined, { err: error, stage: "Unexpected" }),
+				status: "error",
+			});
+		}
+	}
+
+	load(): T | null {
+		return this.tryLoad().value ?? null;
+	}
+
+	loadOrDefault(): T {
+		return this.tryLoad().value ?? this.createDefault();
+	}
+
+	path(): string {
+		return this.#basePath;
+	}
+
+	invalidate() {
+		this.#cache = undefined;
+	}
+}

package/src/config/model-equivalence.ts

@@ -72,15 +72,12 @@ const TRAILING_MARKER_SUFFIXES: readonly string[] = (() => {
 })();
 const WRAPPER_PREFIXES = ["duo-chat-"] as const;
 
-let __referenceDataCache: CanonicalReferenceData | undefined;
+let referenceDataCache: CanonicalReferenceData | undefined;
 const EMPTY_COMPILED_EQUIVALENCE: CompiledEquivalenceConfig = {
 	overrides: new Map<string, string>(),
 	exclude: new Set<string>(),
 };
-const __resolutionCache: WeakMap<
-	CompiledEquivalenceConfig,
-	WeakMap<Model<Api>, ResolvedCanonicalModel>
-> = new WeakMap();
+const resolutionCache: WeakMap<CompiledEquivalenceConfig, WeakMap<Model<Api>, ResolvedCanonicalModel>> = new WeakMap();
 const FAMILY_EXTRACTION_PATTERNS = [
 	/(?:^|[/:._-])((?:claude|gemini|gpt|grok|glm|qwen|minimax|kimi|deepseek|llama|gemma|nova|mistral|ministral|pixtral|codestral|devstral|magistral|ernie|doubao|seed|aion|olmo|molmo|nemotron|palmyra|command|codex|coder|o[1345])[-a-z0-9.]+)(?::|$)/i,
 	/(?:^|[/:._-])((?:claude|gemini|gpt|grok|glm|qwen|minimax|kimi|deepseek|llama|gemma|nova|mistral|ministral|pixtral|codestral|devstral|magistral|ernie|doubao|seed|aion|olmo|molmo|nemotron|palmyra|command|codex|coder|o[1345])[-a-z0-9.]+(?:[-_/][a-z0-9.]+)*)(?::|$)/i,
@@ -98,8 +95,8 @@ function shouldReplaceReference(existing: Model<Api> | undefined, candidate: Mod
 }
 
 function createCanonicalReferenceData(): CanonicalReferenceData {
-	if (__referenceDataCache) {
-		return __referenceDataCache;
+	if (referenceDataCache) {
+		return referenceDataCache;
 	}
 	const references = new Map<string, Model<Api>>();
 	for (const provider of getBundledProviders()) {
@@ -112,11 +109,11 @@ function createCanonicalReferenceData(): CanonicalReferenceData {
 		}
 	}
 	const officialIds = new Set(references.keys());
-	__referenceDataCache = {
+	referenceDataCache = {
 		references: Object.freeze(references) as Map<string, Model<Api>>,
 		officialIds: Object.freeze(officialIds) as Set<string>,
 	};
-	return __referenceDataCache;
+	return referenceDataCache;
 }
 
 function normalizeSelectorKey(selector: string): string {
@@ -668,10 +665,10 @@ export function buildCanonicalModelIndex(
 	const byId = new Map<string, CanonicalModelRecord>();
 	const bySelector = new Map<string, string>();
 
-	let modelCache = __resolutionCache.get(compiledEquivalence);
+	let modelCache = resolutionCache.get(compiledEquivalence);
 	if (!modelCache) {
 		modelCache = new WeakMap<Model<Api>, ResolvedCanonicalModel>();
-		__resolutionCache.set(compiledEquivalence, modelCache);
+		resolutionCache.set(compiledEquivalence, modelCache);
 	}
 
 	for (const model of models) {

package/src/config/model-registry.ts

@@ -18,6 +18,8 @@ import {
 	registerCustomApi,
 	type SimpleStreamOptions,
 	type ThinkingConfig,
+	UNK_CONTEXT_WINDOW,
+	UNK_MAX_TOKENS,
 	unregisterCustomApis,
 } from "@oh-my-pi/pi-ai";
 
@@ -29,10 +31,10 @@ import { registerOAuthProvider, unregisterOAuthProviders } from "@oh-my-pi/pi-ai
 import type { OAuthCredentials, OAuthLoginCallbacks } from "@oh-my-pi/pi-ai/utils/oauth/types";
 import { isRecord, logger } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { type ConfigError, ConfigFile } from "../config";
 import { parseModelString, resolveProviderModelReference } from "../config/model-resolver";
 import { isValidThemeColor, type ThemeColor } from "../modes/theme/theme";
 import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
+import { type ConfigError, ConfigFile } from "./config-file";
 import {
 	buildCanonicalModelIndex,
 	type CanonicalModelIndex,
@@ -1053,7 +1055,16 @@ export class ModelRegistry {
 			const key = `${replacementModel.provider}\u0000${replacementModel.id}`;
 			const existingIndex = indexByKey.get(key);
 			if (existingIndex !== undefined) {
-				merged[existingIndex] = replacementModel;
+				const existing = merged[existingIndex];
+				merged[existingIndex] = {
+					...replacementModel,
+					contextWindow:
+						replacementModel.contextWindow === UNK_CONTEXT_WINDOW
+							? existing.contextWindow
+							: replacementModel.contextWindow,
+					maxTokens:
+						replacementModel.maxTokens === UNK_MAX_TOKENS ? existing.maxTokens : replacementModel.maxTokens,
+				};
 			} else {
 				merged.push(replacementModel);
 				indexByKey.set(key, merged.length - 1);

package/src/config/model-resolver.ts

@@ -12,10 +12,10 @@ import {
 	type Model,
 	modelsAreEqual,
 } from "@oh-my-pi/pi-ai";
+import { fuzzyMatch } from "@oh-my-pi/pi-tui";
 import chalk from "chalk";
 import MODEL_PRIO from "../priority.json" with { type: "json" };
 import { parseThinkingLevel, resolveThinkingLevelForModel } from "../thinking";
-import { fuzzyMatch } from "../utils/fuzzy";
 import { isAuthenticated, kNoAuth, MODEL_ROLE_IDS, type ModelRegistry, type ModelRole } from "./model-registry";
 import type { Settings } from "./settings";
 
@@ -607,9 +607,6 @@ export function resolveModelRoleValue(
 		return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning: undefined };
 	}
 
-	const lastColonIndex = normalized.lastIndexOf(":");
-	const _thinkingSelector =
-		lastColonIndex > PREFIX_MODEL_ROLE.length ? parseThinkingLevel(normalized.slice(lastColonIndex + 1)) : undefined;
 	const effectivePatterns = resolveConfiguredRolePattern(normalized, options?.settings);
 	if (!effectivePatterns || effectivePatterns.length === 0) {
 		return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning: undefined };
@@ -956,6 +953,36 @@ export async function resolveModelScope(
 	return scopedModels;
 }
 
+/**
+ * Resolve the set of models a session is allowed to use, given the active
+ * settings. Starts from `modelRegistry.getAvailable()` (so disabled providers
+ * and providers without credentials are already filtered out) and, when
+ * `enabledModels` is configured for the current path scope, further restricts
+ * the result to models matching those patterns.
+ *
+ * Returns the unfiltered available list when `enabledModels` is empty.
+ * Returns an empty list when `enabledModels` is configured but no available
+ * model matches any pattern — callers MUST treat this as "no usable model"
+ * rather than falling back to the global default (see issue #1022).
+ */
+export async function resolveAllowedModels(
+	modelRegistry: Pick<ModelRegistry, "getAvailable" | "getCanonicalVariants">,
+	settings: Settings | undefined,
+	preferences?: ModelMatchPreferences,
+): Promise<Model<Api>[]> {
+	const available = modelRegistry.getAvailable();
+	const patterns = settings?.get("enabledModels");
+	if (!patterns || patterns.length === 0) {
+		return available;
+	}
+	const scoped = await resolveModelScope(patterns, modelRegistry, preferences);
+	if (scoped.length === 0) {
+		return [];
+	}
+	const allowed = new Set(scoped.map(entry => `${entry.model.provider}/${entry.model.id}`));
+	return available.filter(model => allowed.has(`${model.provider}/${model.id}`));
+}
+
 export interface ResolveCliModelResult {
 	model: Model<Api> | undefined;
 	selector?: string;