@zhushanwen/pi-permission 0.0.1

package/src/index.ts

@@ -0,0 +1,291 @@
+/**
+ * @zhushanwen/pi-permission — Pi permission 扩展
+ *
+ * 四档权限模式（yolo/auto/approve/strict）+ 三层管道（AST + 规则 + AI Classifier）。
+ *
+ * W5 阶段：tool_call handler 接入三层管道（checkPermission）。
+ *  - G5：显式 approvalChain promise chain 串行化（Pi 不保证 tool_call handler 串行，
+ *    但权限检查涉及共享状态/UI 对话框，必须串行避免竞态）。
+ *  - fail-closed：handler 异常 → block + reason（不放行）。
+ *  - session 隔离：config 在 session_start 重建的闭包，每 session 独立。
+ *  - yolo 快速路径：mode=yolo 或 enabled=false → 直接 return undefined（不跑管道）。
+ *
+ * W6 阶段：session_start 注册权限 footer（ctx.ui.setFooter），显示当前 mode + enabled。
+ *  - 单例限制：Pi 只有一个 footer 槽位，会覆盖其他扩展的 footer（README 注明）。
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+	} from "@earendil-works/pi-coding-agent";
+
+import { listAvailableModels } from "./classifier/model-resolver.js";
+import { handlePermissionCommand, handlePermissionModelCommand, handlePermissionRuleCommand } from "./commands.js";
+import { getConfigPath, loadAndWatchConfig, saveConfig } from "./config.js";
+import { setDefaultListAvailableModels } from "./model-picker.js";
+import { editRulesViaOverlay } from "./rule-editor.js";
+import { makeNextIdCounter } from "./rule-templates.js";
+import { checkPermission, type CheckPermissionDeps } from "./pipeline.js";
+import { createPipelineDeps } from "./production.js";
+import { registerPermissionFooter } from "./statusline.js";
+import type { PermissionConfig } from "./types.js";
+
+// ──────────────────────── tool_call event 最小子集 ────────────────────────
+
+/**
+ * Pi tool_call event 的最小子集（duck typing，不依赖完整 SDK 类型）。
+ *
+ * event.type='tool_call'，event.toolCallId，event.toolName，event.input。
+ * bash input={command, timeout?}，其他工具 input={path, ...}。
+ */
+interface ToolCallEventLike {
+	toolName: string;
+	input: Record<string, unknown>;
+	toolCallId?: string;
+}
+
+/** Pi tool_call handler 返回值：{block:true, reason} → Pi 转 isError tool_result；undefined → 放行。 */
+interface ToolCallResult {
+	block?: boolean;
+	reason?: string;
+}
+
+// ──────────────────────── 扩展工厂 ────────────────────────
+
+/**
+ * 扩展工厂。每个 session 独立闭包状态（遵循 Pi session 隔离约束，
+ * 不用模块级 let 避免多 session 共享）。
+ */
+export default function permissionExtension(pi: ExtensionAPI): void {
+	// ──────────────────────── 闭包状态（每 session 独立） ────────────────────────
+	let config: PermissionConfig = loadAndWatchConfig(getConfigPath(), (msg) => {
+		console.warn(msg);
+	});
+
+	// W7：注入 listAvailableModels 真实实现（model-picker.ts 默认返回空 Map）。
+	// G1 口径：(onWarning?, filePath?) → 封装读盘；warning 透传到 console.warn。
+	setDefaultListAvailableModels((onWarning, filePath) =>
+		listAvailableModels(onWarning ?? ((m) => console.warn(m)), filePath),
+	);
+
+	/** 读取最新配置到闭包变量（mtime 缓存内部去重，未变化不读 fs） */
+	function refreshConfig(): void {
+		config = loadAndWatchConfig(getConfigPath(), (msg) => console.warn(msg));
+	}
+
+	// W6 T2：footer invalidator。session_start 注册 footer 时由 registerPermissionFooter
+	// 返回（headless/mock 返回 noop）。mode/enabled 切换成功后调用，使 footer 立即重绘
+	// 新标签（FooterHandle.render 有缓存，不 invalidate 会显示旧 mode 直到 resize）。
+	let invalidateFooter: () => void = () => {};
+
+	// ──────────────────────── session_start：重载配置 + 注册 footer ────────────────────────
+	pi.on("session_start", (_event: unknown, ctx: ExtensionContext) => {
+		refreshConfig();
+		// W6 T2：注册权限 footer（显示当前 mode + enabled）。
+		// 单例限制：Pi 只有一个 footer 槽位，会覆盖（或被覆盖）其他扩展的 footer
+		// （如 @zhushanwen/pi-statusline）。已知限制，README 注明。
+		// getMode/getEnabled 闭包读最新 config（session 内 mode 可变）。
+		// registerPermissionFooter 内部 duck typing：headless/mock ctx 无 setFooter/theme 时
+		// 跳过，返回 noop invalidator。
+		invalidateFooter = registerPermissionFooter(
+			ctx.ui as { setFooter?: unknown; theme?: unknown },
+			() => config.mode,
+			() => config.enabled,
+		);
+	});
+
+	// ──────────────────────── /permission 命令 ────────────────────────
+	pi.registerCommand("permission", {
+		description: "View or switch permission mode. Usage: /permission [mode|status|rule|model]",
+		handler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
+			// 命令执行前重载配置（确保最新，用户可能手动改过文件）
+			refreshConfig();
+			const trimmed = (args ?? "").trim();
+			// W8：/permission rule → overlay CRUD 编辑 userRules（异步路径）
+			if (trimmed === "rule") {
+				await handlePermissionRuleCommand(
+					{
+						mode: ctx.mode,
+						ui: {
+							notify: (msg: string, type?: "info" | "warning" | "error") => ctx.ui.notify(msg, type),
+							select: (title: string, options: string[], opts?: Parameters<typeof ctx.ui.select>[2]) =>
+								ctx.ui.select(title, options, opts),
+							custom: <T,>(
+								factory: (tui: unknown, theme: unknown, kb: unknown, done: (result: T) => void) => unknown,
+								options?: { overlay?: boolean },
+							) =>
+								ctx.ui.custom<T>(factory as Parameters<typeof ctx.ui.custom<T>>[0], options),
+							// 连接 ctx.ui.input（rule-editor custom 模板文本输入用）。
+							// approval.ts 已声明可选 input（SDK 提供，mock 可能缺失）。
+							...(typeof ctx.ui.input === "function"
+								? { input: (title: string, placeholder?: string, opts?: Parameters<typeof ctx.ui.input>[2]) => ctx.ui.input(title, placeholder, opts) }
+								: {}),
+						},
+					},
+					config,
+					makeNextIdCounter(config.userRules),
+					{
+						save: (newConfig) => {
+							const result = saveConfig(newConfig);
+							if (result.success) {
+								config = newConfig; // 更新闭包状态
+							}
+							return result;
+						},
+						editRulesViaOverlay: (ctx, initialRules, sessionIdCounter, rpcDeps) =>
+							editRulesViaOverlay(ctx, initialRules, sessionIdCounter, rpcDeps),
+					},
+				);
+				return;
+			}
+			// W7：/permission model → overlay 选择 classifier model（异步路径）
+			if (trimmed === "model") {
+				await handlePermissionModelCommand(
+					{
+						mode: ctx.mode,
+						ui: {
+							notify: (msg: string, type?: "info" | "warning" | "error") => ctx.ui.notify(msg, type),
+							select: (title: string, options: string[], opts?: Parameters<typeof ctx.ui.select>[2]) =>
+								ctx.ui.select(title, options, opts),
+							custom: <T,>(
+								factory: (tui: unknown, theme: unknown, kb: unknown, done: (result: T) => void) => unknown,
+								options?: { overlay?: boolean },
+							) =>
+								ctx.ui.custom<T>(factory as Parameters<typeof ctx.ui.custom<T>>[0], options),
+							// 连接 ctx.ui.input（与 rule handler 一致；model picker 当前不用，但保持 ctx 对称）。
+							...(typeof ctx.ui.input === "function"
+								? { input: (title: string, placeholder?: string, opts?: Parameters<typeof ctx.ui.input>[2]) => ctx.ui.input(title, placeholder, opts) }
+								: {}),
+						},
+					},
+					config,
+					{
+						listModels: () => listAvailableModels((m) => console.warn(m)),
+						save: (newConfig) => {
+							const result = saveConfig(newConfig);
+							if (result.success) {
+								config = newConfig; // 更新闭包状态
+							}
+							return result;
+						},
+					},
+				);
+				return;
+			}
+			// 原同步路径（yolo/auto/approve/strict/status/无参）
+			const message = handlePermissionCommand(args, config, (newConfig) => {
+				const result = saveConfig(newConfig);
+				if (result.success) {
+					config = newConfig; // 更新闭包状态
+					// footer 仅显示 mode + enabled；切换成功后刷缓存 + 重绘，避免显示旧 mode。
+					invalidateFooter();
+				}
+				return result;
+			});
+			ctx.ui.notify(message, "info");
+		},
+	});
+
+	// ──────────────────────── tool_call handler（W5 三层管道 + G5 串行化） ────────────────────────
+	// G5：显式 approvalChain promise chain。Pi 不保证 tool_call handler 串行调用，
+	// 但权限检查可能弹出 UI 对话框（共享终端），必须串行避免多个对话框叠加。
+	let approvalChain: Promise<ToolCallResult | undefined> = Promise.resolve(undefined);
+
+	pi.on("tool_call", (event: unknown, ctx: ExtensionContext): Promise<ToolCallResult | undefined> => {
+		const run = (): Promise<ToolCallResult | undefined> => processToolCall(event, ctx, () => config, refreshConfig);
+		// 串行：前一个完成（无论 resolve/reject）后才跑下一个。失败不影响后续。
+		approvalChain = approvalChain.then(run, run);
+		return approvalChain;
+	});
+}
+
+// ──────────────────────── processToolCall（单次工具调用处理） ────────────────────────
+
+/**
+ * 处理单次 tool_call：提 config → checkPermission → 映射为 Pi ToolCallResult。
+ *
+ * fail-closed：任何异常 → block + reason（不放行）。
+ * yolo 快速路径：mode=yolo 或 enabled=false → return undefined（不跑管道，最小开销）。
+ *
+ * @param event tool_call event（duck typing 为 ToolCallEventLike）
+ * @param ctx Pi ExtensionContext
+ * @param getConfig 获取最新 config 的闭包（session 隔离）
+ * @param _refreshConfig 重载配置（保留参数位，便于未来扩展）
+ */
+async function processToolCall(
+	event: unknown,
+	ctx: ExtensionContext,
+	getConfig: () => PermissionConfig,
+	_refreshConfig: () => void,
+): Promise<ToolCallResult | undefined> {
+	const cfg = getConfig();
+
+	// 快速路径：yolo 或 disabled → 完全放行（不跑管道，最小开销）
+	if (cfg.mode === "yolo" || !cfg.enabled) {
+		return undefined;
+	}
+
+	// 提取 event 字段（duck typing，防御非预期形状）
+	const evt = event as ToolCallEventLike;
+	const toolName = typeof evt?.toolName === "string" ? evt.toolName : "";
+	const input = evt?.input !== null && typeof evt?.input === "object" && !Array.isArray(evt.input)
+		? (evt.input as Record<string, unknown>)
+		: {};
+
+	if (toolName.length === 0) {
+		// 无法识别工具名 → fail-closed block
+		return { block: true, reason: "[pi-permission] tool_call event missing toolName" };
+	}
+
+	// 装配 deps（每次 tool_call 重新装配，捕获当前 ctx.mode/ui；classifier 单例在 createPipelineDeps 内）
+	const approvalCtx = {
+		mode: ctx.mode,
+		ui: {
+			notify: (msg: string, type?: "info" | "warning" | "error") => ctx.ui.notify(msg, type),
+			select: (title: string, options: string[], opts?: Parameters<typeof ctx.ui.select>[2]) => ctx.ui.select(title, options, opts),
+			custom: <T,>(
+				factory: (tui: unknown, theme: unknown, kb: unknown, done: (result: T) => void) => unknown,
+				options?: { overlay?: boolean },
+			) =>
+				ctx.ui.custom<T>(factory as Parameters<typeof ctx.ui.custom<T>>[0], options),
+			// W6 T9 G3：Reject-with-Reason。ctx.ui.input 存在则透传（采集真实拒绝理由）。
+			// approval.ts 的 collectRejectReason 会用 typeof 判断是否可用，不可用则 fallback。
+			...(typeof ctx.ui.input === "function"
+				? { input: (title: string, placeholder?: string, opts?: Parameters<typeof ctx.ui.input>[2]) => ctx.ui.input(title, placeholder, opts) }
+				: {}),
+		},
+	};
+	const deps: CheckPermissionDeps = createPipelineDeps(approvalCtx);
+
+	try {
+		const decision = await checkPermission(
+			toolName,
+			input,
+			cfg.mode,
+			cfg.classifier,
+			cfg.userRules,
+			deps,
+			{ cwd: ctx.cwd, signal: ctx.signal },
+		);
+
+		if (decision.action === "allow") {
+			// 放行：return undefined（Pi 不拦截）
+			return undefined;
+		}
+		// deny / ask → block + reason（Pi 转 isError tool_result）
+		// ask 在 checkPermission 内已转 user 决策；若到这仍是 ask，fail-closed 当 deny
+		return {
+			block: true,
+			reason: `[pi-permission] ${decision.action}: ${decision.reason} (source=${decision.source})`,
+		};
+	} catch (error) {
+		// fail-closed：异常 → block + reason（绝不放行）
+		const msg = error instanceof Error ? error.message : String(error);
+		console.warn(`[pi-permission] tool_call handler exception for ${toolName}: ${msg}`);
+		return {
+			block: true,
+			reason: `[pi-permission] internal error (fail-closed): ${msg}`,
+		};
+	}
+}

package/src/model-picker.ts

@@ -0,0 +1,398 @@
+/**
+ * W7：/permission model overlay 选择器。
+ *
+ * 两级 TUI 选择：
+ *  - 第一级（provider stage）：列出 'Auto' + 所有可用 provider（listAvailableModels）
+ *  - 第二级（model stage）：选中具体 provider 后，列出该 provider 下的 model（按 cost 升序）
+ *  - 选 'Auto' 或具体 provider/model → done(SelectionResult)；Esc 回退 / 取消
+ *
+ * 三模式分发（pickModelViaOverlay）：
+ *  - tui：ctx.ui.custom（ProviderModelSelectorComponent，overlay）。custom 的 factory 接收
+ *    done 回调，comp 内部 onSelect/onCancel 最终调 done（参考 approval.ts ApprovalComponent）。
+ *  - rpc：两次 ctx.ui.select（provider 含 auto，model）
+ *  - headless（json/print）：返回 undefined（无交互 UI，降级）
+ *
+ * 关键设计：
+ *  - ProviderModelSelectorComponent extends Container：Container 无 handleInput，必须 override
+ *    委托给当前 stage 的 SelectList（WC9/WC15 critical）。
+ *  - stage 切换用 clear() + addChild 重建（两态状态机）。
+ *  - _resolved 守卫防二次 done（switchToModelStage 等异步路径可能重复触发）。
+ */
+
+import { type Component, Container, type SelectItem, SelectList, type SelectListTheme, truncateToWidth } from "@earendil-works/pi-tui";
+
+import type { ResolvedModelEntry } from "./classifier/model-resolver.js";
+
+// ──────────────────────── 类型 ────────────────────────
+
+/** 选择结果（discriminated union）；undefined = cancel / 降级。 */
+export type SelectionResult =
+	| { kind: "auto" }
+	| { kind: "specific"; provider: string; modelId: string };
+
+// ──────────────────────── DEFAULT_SELECT_THEME（G2 修正） ────────────────────────
+
+/**
+ * SelectList 默认主题。
+ *
+ * G2/WR2 修正：selectedPrefix 实现为 `(t) => '▶ ' + t`（非 identity），
+ * 选中行有视觉区分（▶ 前缀）。
+ */
+export const DEFAULT_SELECT_THEME: SelectListTheme = {
+	selectedPrefix: (t: string): string => "\u25B6 " + t,
+	selectedText: (t: string): string => t,
+	description: (t: string): string => t,
+	scrollInfo: (t: string): string => t,
+	noMatch: (t: string): string => t,
+};
+
+/** provider stage 的 'auto' 项 value（用特殊标记区分真实 provider 名）。 */
+const AUTO_VALUE = "__auto__";
+
+/** SelectList 最大可见行数（picker overlay 不超过终端高度）。 */
+const MAX_VISIBLE_ITEMS = 10;
+
+// ──────────────────────── 辅助组件（inline Component stub，避免依赖 Box 的 padding/bg） ────────────────────────
+
+/**
+ * 最小 inline Component：渲染固定文本行（title / hint）。
+ * Container 不要求 children 有 handleInput，只要 render + invalidate。
+ */
+class TextLines implements Component {
+	private readonly lines: string[];
+
+	constructor(lines: string[]) {
+		this.lines = lines;
+	}
+
+	render(_width: number): string[] {
+		return [...this.lines];
+	}
+
+	invalidate(): void {
+		// 无缓存，no-op
+	}
+}
+
+// ──────────────────────── ProviderModelSelectorComponent ────────────────────────
+
+/**
+ * 两级 TUI 选择组件（provider → model）。
+ *
+ * 状态机：
+ *  - stage='provider'：SelectList 列出 'Auto' + providers
+ *  - stage='model'：SelectList 列出所选 provider 的 models
+ *
+ * 切换：clear() + addChild 重建（两态，无回退栈，model stage Esc 回退到 provider stage）。
+ *
+ * WC9/WC15 critical：Container 没有 handleInput，必须 override 委托给当前 stage 的 SelectList。
+ * 测试 WR1：直接调 comp.handleInput('\r') 验证 SelectList.onSelect 被触发（锁定键盘委托通路）。
+ *
+ * done 桥接：comp 构造时传入 done（由 ctx.ui.custom 的 factory 提供），内部 onSelect/onCancel
+ * 最终调 done（参考 ApprovalComponent）。_resolved 守卫防二次 done。
+ */
+export class ProviderModelSelectorComponent extends Container {
+	private stage: "provider" | "model" = "provider";
+	private readonly currentSpec: string;
+	private readonly providers: readonly string[];
+	private readonly modelsByProvider: ReadonlyMap<string, readonly ResolvedModelEntry[]>;
+	private readonly done: (result: SelectionResult | undefined) => void;
+	private readonly theme: SelectListTheme;
+	private _resolved = false;
+	private currentList: SelectList | null = null;
+
+	constructor(
+		currentSpec: string,
+		providers: readonly string[],
+		modelsByProvider: ReadonlyMap<string, readonly ResolvedModelEntry[]>,
+		done: (result: SelectionResult | undefined) => void,
+		theme: SelectListTheme = DEFAULT_SELECT_THEME,
+	) {
+		super();
+		this.currentSpec = currentSpec;
+		this.providers = providers;
+		this.modelsByProvider = modelsByProvider;
+		this.done = done;
+		this.theme = theme;
+		this.switchToProviderStage();
+	}
+
+	/**
+	 * Container 无 handleInput（Container implements Component 但未声明 handleInput），
+	 * 必须在此声明委托给当前 stage 的 SelectList（WC9/WC15 critical）。
+	 * 不能用 override（Container 未声明该方法），直接新增方法满足 Component 接口。
+	 */
+	handleInput(data: string): void {
+		this.currentList?.handleInput(data);
+	}
+
+	/** box 边框左右各占用 1 列（│ × 2） */
+	private static readonly BORDER_OVERHEAD = 2;
+
+	/**
+	 * 重写 render：用 box 边框包裹 Container 子组件的输出。
+	 */
+	override render(width: number): string[] {
+		const innerWidth = Math.max(0, width - ProviderModelSelectorComponent.BORDER_OVERHEAD);
+		const inner = super.render(innerWidth);
+		const lines: string[] = [];
+		lines.push(`\u250C${"\u2500".repeat(innerWidth)}\u2510`);
+		for (const line of inner) {
+			const padded = truncateToWidth(line, innerWidth, "", true);
+			lines.push(`\u2502${padded}\u2502`);
+		}
+		lines.push(`\u2514${"\u2500".repeat(innerWidth)}\u2518`);
+		return lines;
+	}
+
+	/** 退出（外部 abort 用）。复用 _resolved 守卫防二次 done。 */
+	cancel(): void {
+		this.settle(undefined);
+	}
+
+	private settle(result: SelectionResult | undefined): void {
+		if (this._resolved) return;
+		this._resolved = true;
+		this.done(result);
+	}
+
+	// ──────────────────────── provider stage ────────────────────────
+
+	private switchToProviderStage(): void {
+		this.stage = "provider";
+		this.clear();
+		this.currentList = this.buildProviderList();
+		this.addChild(this.buildTitleBox("Select Provider", this.formatProviderHint()));
+		this.addChild(this.currentList);
+	}
+
+	/** 构建 provider stage 的 SelectList（title + list 由调用方组装）。 */
+	private buildProviderList(): SelectList {
+		const selectedIndex = this.computeProviderSelectedIndex();
+		const items = this.buildProviderItems();
+		const list = new SelectList(items, MAX_VISIBLE_ITEMS, this.theme);
+		list.setSelectedIndex(selectedIndex);
+		list.onSelect = (item: SelectItem): void => {
+			if (item.value === AUTO_VALUE) {
+				this.settle({ kind: "auto" });
+				return;
+			}
+			this.switchToModelStage(item.value);
+		};
+		list.onCancel = (): void => {
+			this.settle(undefined);
+		};
+		return list;
+	}
+
+	/** provider stage items：'Auto' + 各 provider（含 model 数量）。 */
+	private buildProviderItems(): SelectItem[] {
+		const items: SelectItem[] = [
+			{ value: AUTO_VALUE, label: "Auto", description: "auto-select cheapest available model" },
+		];
+		for (const provider of this.providers) {
+			const models = this.modelsByProvider.get(provider) ?? [];
+			items.push({
+				value: provider,
+				label: provider,
+				description: `${models.length} model(s)`,
+			});
+		}
+		return items;
+	}
+
+	/** 计算 provider stage 预选 index（currentSpec='auto' → 0；'provider/model' → findIndex）。 */
+	private computeProviderSelectedIndex(): number {
+		if (this.currentSpec === "auto") return 0;
+		const slashIdx = this.currentSpec.indexOf("/");
+		if (slashIdx <= 0) return 0;
+		const provider = this.currentSpec.slice(0, slashIdx);
+		const idx = this.providers.indexOf(provider);
+		return idx >= 0 ? idx + 1 : 0; // +1 跳过 'Auto'
+	}
+
+	private formatProviderHint(): string {
+		return `Current: ${this.currentSpec}  |  [Up/Down] navigate  [Enter] select  [Esc] cancel`;
+	}
+
+	// ──────────────────────── model stage ────────────────────────
+
+	private switchToModelStage(provider: string): void {
+		this.stage = "model";
+		this.clear();
+		const models = this.modelsByProvider.get(provider) ?? [];
+		this.currentList = this.buildModelList(provider, models);
+		this.addChild(this.buildTitleBox(`Select Model - ${provider}`, this.formatModelHint()));
+		this.addChild(this.currentList);
+	}
+
+	/** 构建 model stage 的 SelectList（按 cost 升序，由 modelsByProvider 保证）。 */
+	private buildModelList(provider: string, models: readonly ResolvedModelEntry[]): SelectList {
+		const items: SelectItem[] = models.map((m) => ({
+			value: m.id,
+			label: m.id,
+			description: `input cost: ${m.cost.input}`,
+		}));
+		const list = new SelectList(items, MAX_VISIBLE_ITEMS, this.theme);
+		const preSelected = this.computeModelSelectedIndex(models);
+		list.setSelectedIndex(preSelected);
+		list.onSelect = (item: SelectItem): void => {
+			this.settle({ kind: "specific", provider, modelId: item.value });
+		};
+		list.onCancel = (): void => {
+			// Esc 退回 provider stage（不 settle）
+			this.switchToProviderStage();
+		};
+		return list;
+	}
+
+	/** 计算 model stage 预选 index。 */
+	private computeModelSelectedIndex(models: readonly ResolvedModelEntry[]): number {
+		const slashIdx = this.currentSpec.indexOf("/");
+		if (slashIdx <= 0) return 0;
+		const modelId = this.currentSpec.slice(slashIdx + 1);
+		const idx = models.findIndex((m) => m.id === modelId);
+		return idx >= 0 ? idx : 0;
+	}
+
+	private formatModelHint(): string {
+		return "[Up/Down] navigate  [Enter] select  [Esc] back to provider list";
+	}
+
+	// ──────────────────────── title box（G4） ────────────────────────
+
+	/**
+	 * G4：title/hint box（含当前选中提示 + 键位提示）。
+	 * 用 Container 包裹 TextLines（保持纯文本，不依赖 Box 的 padding/bg）。
+	 */
+	private buildTitleBox(title: string, hint: string): Container {
+		const box = new Container();
+		box.addChild(new TextLines([`[pi-permission] ${title}`]));
+		box.addChild(new TextLines([hint, ""]));
+		return box;
+	}
+}
+
+// ──────────────────────── pickModelViaOverlay ────────────────────────
+
+/** overlay 上下文（从 Pi ExtensionContext 提取的最小子集）。 */
+export interface ModelPickerContext {
+	mode: "tui" | "rpc" | "json" | "print";
+	ui: {
+		notify(msg: string, type?: "info" | "warning" | "error"): void;
+		select(title: string, options: string[], opts?: { signal?: AbortSignal; timeout?: number }): Promise<string | undefined>;
+		custom<T = void>(
+			factory: (tui: unknown, theme: unknown, kb: unknown, done: (result: T) => void) => unknown,
+			options?: { overlay?: boolean },
+		): Promise<T>;
+	};
+}
+
+/** listAvailableModels 注入签名（便于测试 mock）。 */
+export type ListAvailableModelsFn = (
+	onWarning?: (msg: string) => void,
+	filePath?: string,
+) => Map<string, ResolvedModelEntry[]>;
+
+/**
+ * 通过 overlay 选择模型（provider/model 或 auto）。
+ *
+ * @param ctx UI 上下文（mode + ui.*）
+ * @param currentSpec 当前 classifier.model（'auto' 或 'provider/model-id'），用于预选
+ * @param models 可选，预加载的 models Map（避免重复读盘）；未传则用默认 listAvailableModels
+ * @returns 'auto' / 'provider/model-id' / undefined（cancel 或 headless 降级）
+ */
+export async function pickModelViaOverlay(
+	ctx: ModelPickerContext,
+	currentSpec: string,
+	models?: Map<string, ResolvedModelEntry[]>,
+): Promise<string | undefined> {
+	const modelsByProvider = models ?? listAvailableModelsDefault();
+	if (modelsByProvider.size === 0) return undefined;
+
+	const providers = [...modelsByProvider.keys()];
+
+	switch (ctx.mode) {
+		case "tui":
+			return await pickViaTui(ctx, currentSpec, providers, modelsByProvider);
+		case "rpc":
+			return await pickViaRpc(ctx, currentSpec, providers, modelsByProvider);
+		case "json":
+		case "print":
+		default:
+			return undefined;
+	}
+}
+
+/** 默认 listAvailableModels（生产路径用，index.ts 装配时注入真实实现）。 */
+let listAvailableModelsDefault: ListAvailableModelsFn = (): Map<string, ResolvedModelEntry[]> => new Map();
+
+/** 注入默认 listAvailableModels 实现（index.ts 装配时调用，或测试覆盖）。 */
+export function setDefaultListAvailableModels(fn: ListAvailableModelsFn): void {
+	listAvailableModelsDefault = fn;
+}
+
+// ──────────────────────── TUI 分支 ────────────────────────
+
+/**
+ * TUI 分支：ctx.ui.custom + ProviderModelSelectorComponent。
+ * custom 的 factory 接收 done 回调；comp 内部 onSelect/onCancel 最终调 done。
+ */
+async function pickViaTui(
+	ctx: ModelPickerContext,
+	currentSpec: string,
+	providers: readonly string[],
+	modelsByProvider: ReadonlyMap<string, readonly ResolvedModelEntry[]>,
+): Promise<string | undefined> {
+	const result = await ctx.ui.custom<SelectionResult | undefined>(
+		(_tui, _theme, _kb, done) => {
+			const comp = new ProviderModelSelectorComponent(
+				currentSpec,
+				providers,
+				modelsByProvider,
+				done,
+			);
+			return comp;
+		},
+		{ overlay: true },
+	);
+	return selectionResultToString(result);
+}
+
+// ──────────────────────── RPC 分支 ────────────────────────
+
+async function pickViaRpc(
+	ctx: ModelPickerContext,
+	currentSpec: string,
+	providers: readonly string[],
+	modelsByProvider: ReadonlyMap<string, readonly ResolvedModelEntry[]>,
+): Promise<string | undefined> {
+	// 第一次 select：provider（含 Auto）
+	const providerOptions = ["Auto", ...providers];
+	const providerChoice = await ctx.ui.select(
+		`[pi-permission] Select provider (current: ${currentSpec})`,
+		providerOptions,
+	);
+	if (providerChoice === undefined) return undefined;
+	if (providerChoice === "Auto") return "auto";
+
+	// 第二次 select：model
+	const models = modelsByProvider.get(providerChoice) ?? [];
+	if (models.length === 0) return undefined;
+	const modelOptions = models.map((m) => m.id);
+	const modelChoice = await ctx.ui.select(
+		`[pi-permission] Select model for ${providerChoice}`,
+		modelOptions,
+	);
+	if (modelChoice === undefined) return undefined;
+	return `${providerChoice}/${modelChoice}`;
+}
+
+// ──────────────────────── 辅助 ────────────────────────
+
+/** SelectionResult → config 字符串（'auto' / 'provider/model-id'）。 */
+function selectionResultToString(result: SelectionResult | undefined): string | undefined {
+	if (result === undefined) return undefined;
+	if (result.kind === "auto") return "auto";
+	return `${result.provider}/${result.modelId}`;
+}