@co0ontty/wand 4.83.1 → 4.84.0

package/dist/model-group-runner.js

@@ -0,0 +1,72 @@
+import { getDefaultModelForProvider } from "./config.js";
+import { findModelGroup, resolveModelGroupModels } from "./model-groups.js";
+import { OPENROUTER_FREE_SELECTOR } from "./openrouter-free-selection.js";
+import { classifyStructuredFailure, hasStructuredExecutionProgress } from "./structured-failure.js";
+/** Resolve at execution time; persist the selection, normalize attempt facts even without a group. */
+export function withModelGroups(runner, config) {
+    return { start(context, observer) {
+            const provider = context.session.provider ?? context.session.structuredState?.provider ?? "claude";
+            const selected = context.session.selectedModel?.trim();
+            const selector = selected && selected !== "default" ? selected : getDefaultModelForProvider(config, provider);
+            const groupOptions = { preferDefault: !selected || selected === "default" };
+            const models = resolveModelGroupModels(config.modelGroups, provider, selector, groupOptions);
+            const group = findModelGroup(config.modelGroups, provider, selector, groupOptions);
+            const grouped = !!group && models[0] !== OPENROUTER_FREE_SELECTOR;
+            let cancelled = false;
+            let current;
+            const start = (model) => {
+                let active = true;
+                let output = false;
+                let progress = false;
+                const isActive = () => active && !cancelled && observer.isActive();
+                const execution = runner.start({ ...context, ...(grouped ? { modelGroupModels: models } : {}),
+                    session: { ...context.session, selectedModel: model || null },
+                }, { ...observer, isActive,
+                    onStdout(text) { if (!isActive())
+                        return; if (text.trim())
+                        output = true; observer.onStdout?.(text); },
+                    onEvent(event) {
+                        if (!isActive())
+                            return;
+                        if (event.type !== "wand_pi_resource_selection")
+                            output = true;
+                        observer.onEvent?.(event);
+                    },
+                    onUpdate(state) {
+                        if (!isActive())
+                            return;
+                        progress ||= hasStructuredExecutionProgress(state);
+                        output ||= !!state.sessionId || progress;
+                        observer.onUpdate({ ...state, model: state.model ?? model });
+                    },
+                });
+                return { ...execution, get args() { return execution.args; }, get pid() { return execution.pid; },
+                    completion: execution.completion.then((result) => {
+                        const failed = result.spawnError ? { ...result, exitCode: result.exitCode ?? 1,
+                            primaryError: result.primaryError || result.spawnError.message } : result;
+                        const failure = classifyStructuredFailure(failed, { output, progress });
+                        return { ...failed, failure: failure && cancelled ? { ...failure, kind: "cancelled", retryable: false } : failure,
+                            state: { ...failed.state, model: failed.state.model ?? model } };
+                    }).finally(() => { active = false; }) };
+            };
+            // Synchronous registration is essential for queue/recovery ownership.
+            current = start(models[0] ?? "");
+            const first = current;
+            const completion = (async () => {
+                for (let index = 0;; index++) {
+                    const result = await current.completion;
+                    if (!grouped || !result.failure?.retryable || cancelled || !observer.isActive()
+                        || index + 1 >= models.length)
+                        return result;
+                    current = start(models[index + 1]);
+                }
+            })();
+            return { ...first, get args() { return first.args; }, get pid() { return first.pid; }, completion, interrupt() {
+                    cancelled = true;
+                    try {
+                        current.interrupt();
+                    }
+                    catch { /* best effort, never replay after cancellation */ }
+                } };
+        } };
+}

package/dist/model-groups.d.ts

@@ -0,0 +1,38 @@
+import { type SessionProvider } from "./provider-catalog.js";
+/** Stable identities, not names, are saved in sessions/employees/default model preferences. */
+export interface ModelGroup {
+    id: string;
+    provider: SessionProvider;
+    name: string;
+    /** First is preferred; later entries are pre-execution fallbacks, never replay after acceptance. */
+    models: string[];
+}
+export declare const MODEL_GROUP_PREFIX = "wand-model-group/";
+/**
+ * 「智能分配」：不是一个分组，而是一条只能在真实提示词到手后结算的选择。
+ * 结构化会话的第一轮、终端会话带首条输入创建时才解析成本次真正使用的分组；
+ * 没有提示词的同步场景（构建命令行、一次性文本调用）退化成默认分组。
+ */
+export declare const AUTO_ASSIGN_SELECTOR = "wand-auto-assign/auto";
+export declare const AUTO_ASSIGN_LABEL = "\u667A\u80FD\u5206\u914D";
+export declare const FREE_MODEL_GROUP_ID = "openrouter-free";
+export declare const MODEL_GROUP_MAX_PER_PROVIDER = 32;
+export declare const MODEL_GROUP_MAX_MEMBERS = 32;
+export declare const DEFAULT_MODEL_GROUP_NAMES: readonly ["默认分组", "默认", "default"];
+export declare function isModelGroupSelector(value: string | null | undefined): boolean;
+export declare function isAutoAssignSelector(value: string | null | undefined): boolean;
+export declare function modelGroupSelector(group: Pick<ModelGroup, "id" | "provider">): string;
+export declare function normalizeModelGroups(value: unknown): ModelGroup[];
+/** Names are exact and provider-scoped; stable selectors keep working after a rename. */
+export declare function findModelGroup(groups: readonly ModelGroup[] | undefined, provider: SessionProvider, selector?: string | null, options?: {
+    preferDefault?: boolean;
+}): ModelGroup | undefined;
+/** A configured group wins; do not silently replace a deleted configured group. */
+export declare function defaultModelGroupSelector(groups: readonly ModelGroup[] | undefined, provider: SessionProvider, configured?: string | null): string | undefined;
+/** Native default is one executable candidate, not an empty candidate chain. */
+export declare function resolveModelGroupModels(groups: readonly ModelGroup[] | undefined, provider: SessionProvider, selector: string | null | undefined, options?: {
+    preferDefault?: boolean;
+}): string[];
+export declare function freeModelOrder(groups: readonly ModelGroup[] | undefined): string[];
+/** Used for free pools: saved priority first; newly verified models append, vanished models are skipped. */
+export declare function orderModelIds(ids: readonly string[], preferred: readonly string[]): string[];

package/dist/model-groups.js

@@ -0,0 +1,138 @@
+import { isSessionProvider, SESSION_PROVIDERS } from "./provider-catalog.js";
+import { OPENROUTER_FREE_GROUP, OPENROUTER_FREE_PROVIDER, OPENROUTER_FREE_SELECTOR, isOpenRouterFreeSelector } from "./openrouter-free-selection.js";
+export const MODEL_GROUP_PREFIX = "wand-model-group/";
+/**
+ * 「智能分配」：不是一个分组，而是一条只能在真实提示词到手后结算的选择。
+ * 结构化会话的第一轮、终端会话带首条输入创建时才解析成本次真正使用的分组；
+ * 没有提示词的同步场景（构建命令行、一次性文本调用）退化成默认分组。
+ */
+export const AUTO_ASSIGN_SELECTOR = "wand-auto-assign/auto";
+export const AUTO_ASSIGN_LABEL = "智能分配";
+export const FREE_MODEL_GROUP_ID = "openrouter-free";
+export const MODEL_GROUP_MAX_PER_PROVIDER = 32;
+export const MODEL_GROUP_MAX_MEMBERS = 32;
+export const DEFAULT_MODEL_GROUP_NAMES = ["默认分组", "默认", "default"];
+const GROUP_ID = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+export function isModelGroupSelector(value) {
+    return value?.startsWith(MODEL_GROUP_PREFIX) === true;
+}
+export function isAutoAssignSelector(value) {
+    return value?.trim() === AUTO_ASSIGN_SELECTOR;
+}
+/** 「智能分配」在只拿到选择器、拿不到提示词时的等价写法：按默认分组解析。 */
+function modelSelectorWithoutAutoAssign(selector) {
+    const value = selector?.trim() ?? "";
+    return isAutoAssignSelector(value) ? "" : value;
+}
+export function modelGroupSelector(group) {
+    return group.id === FREE_MODEL_GROUP_ID && group.provider === "pi"
+        ? OPENROUTER_FREE_SELECTOR : `${MODEL_GROUP_PREFIX}${group.provider}/${group.id}`;
+}
+export function normalizeModelGroups(value) {
+    if (!Array.isArray(value) || value.length > MODEL_GROUP_MAX_PER_PROVIDER * SESSION_PROVIDERS.length + 1) {
+        throw new Error("模型分组必须是有界数组。");
+    }
+    const identities = new Set();
+    const names = new Set();
+    const counts = new Map();
+    return value.map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            throw new Error("模型分组格式无效。");
+        const row = entry;
+        const id = typeof row.id === "string" ? row.id.trim() : "";
+        const name = typeof row.name === "string" ? row.name.trim() : "";
+        if (!GROUP_ID.test(id) || !isSessionProvider(row.provider))
+            throw new Error("模型分组标识或工具无效。");
+        const provider = row.provider;
+        if (!name || name.length > 40 || /[\x00-\x1f\x7f]/.test(name))
+            throw new Error("分组名称需为 1–40 个字符。");
+        const free = id === FREE_MODEL_GROUP_ID;
+        if (free && (provider !== "pi" || name !== OPENROUTER_FREE_GROUP))
+            throw new Error("免费分组的工具与名称不可修改。");
+        if (!free && provider === "pi" && name === OPENROUTER_FREE_GROUP)
+            throw new Error("免费分组是内置分组，请直接调整它的顺序。");
+        const identity = `${provider}/${id}`;
+        const named = `${provider}/${name}`;
+        if (identities.has(identity) || names.has(named))
+            throw new Error("同一工具的分组标识或名称不能重复。");
+        identities.add(identity);
+        names.add(named);
+        const count = (counts.get(provider) ?? 0) + (free ? 0 : 1);
+        if (count > MODEL_GROUP_MAX_PER_PROVIDER)
+            throw new Error(`每个工具最多 ${MODEL_GROUP_MAX_PER_PROVIDER} 个分组。`);
+        counts.set(provider, count);
+        if (!Array.isArray(row.models) || (!free && !row.models.length)
+            || row.models.length > (free ? 128 : MODEL_GROUP_MAX_MEMBERS)) {
+            throw new Error(`分组需包含 1–${MODEL_GROUP_MAX_MEMBERS} 个模型；免费分组可留空使用自动顺序。`);
+        }
+        const models = row.models.map((model) => {
+            const trimmed = typeof model === "string" ? model.trim() : "";
+            if (!trimmed || trimmed === "default" || trimmed.length > 256 || /[\s\x00-\x1f\x7f]/.test(trimmed)
+                || isModelGroupSelector(trimmed) || isAutoAssignSelector(trimmed)
+                || trimmed === OPENROUTER_FREE_SELECTOR || trimmed.startsWith("-")) {
+                throw new Error("组内必须是具体模型 ID，不能嵌套分组或使用默认值。");
+            }
+            if (isOpenRouterFreeSelector(trimmed) && provider !== "pi")
+                throw new Error("免费模型仅属于 one 的 Agent。");
+            if (free && !trimmed.startsWith(`${OPENROUTER_FREE_PROVIDER}/`))
+                throw new Error("免费分组只能包含免费池中的模型。");
+            return trimmed;
+        });
+        if (new Set(models).size !== models.length)
+            throw new Error("同一分组中的模型不能重复。");
+        return { id, provider, name, models };
+    });
+}
+/** Names are exact and provider-scoped; stable selectors keep working after a rename. */
+export function findModelGroup(groups, provider, selector, options = {}) {
+    const candidates = (groups ?? []).filter((entry) => entry.provider === provider);
+    const value = modelSelectorWithoutAutoAssign(selector);
+    if (isModelGroupSelector(value) || value === OPENROUTER_FREE_SELECTOR) {
+        return candidates.find((entry) => modelGroupSelector(entry) === value);
+    }
+    if (value && value !== "default") {
+        const named = candidates.find((entry) => entry.name === value);
+        if (named || !options.preferDefault)
+            return named;
+    }
+    const named = DEFAULT_MODEL_GROUP_NAMES.map((name) => candidates.find((entry) => entry.name === name))
+        .find((entry) => entry !== undefined);
+    return named ?? candidates.find((entry) => entry.id !== FREE_MODEL_GROUP_ID) ?? candidates[0];
+}
+/** A configured group wins; do not silently replace a deleted configured group. */
+export function defaultModelGroupSelector(groups, provider, configured) {
+    const value = configured?.trim();
+    // 智能分配是明确选择，必须原样带到会话上，由第一轮提示词结算。
+    if (isModelGroupSelector(value) || value === OPENROUTER_FREE_SELECTOR || isAutoAssignSelector(value))
+        return value;
+    const group = findModelGroup(groups, provider, value, { preferDefault: true });
+    return group ? modelGroupSelector(group) : undefined;
+}
+/** Native default is one executable candidate, not an empty candidate chain. */
+export function resolveModelGroupModels(groups, provider, selector, options = {}) {
+    const value = modelSelectorWithoutAutoAssign(selector);
+    if (value === OPENROUTER_FREE_SELECTOR) {
+        if (provider !== "pi")
+            throw new Error("免费分组仅属于 one 的 Agent。");
+        return [value];
+    }
+    const group = findModelGroup(groups, provider, value, options);
+    if (group?.id === FREE_MODEL_GROUP_ID)
+        return [OPENROUTER_FREE_SELECTOR];
+    if (group) {
+        if (!group.models.length)
+            throw new Error("所选模型分组已删除、为空或不属于当前工具，请重新选择。");
+        return [...group.models];
+    }
+    if (isModelGroupSelector(value))
+        throw new Error("所选模型分组已删除、为空或不属于当前工具，请重新选择。");
+    return [value === "default" ? "" : value];
+}
+export function freeModelOrder(groups) {
+    return groups?.find((entry) => entry.id === FREE_MODEL_GROUP_ID && entry.provider === "pi")?.models ?? [];
+}
+/** Used for free pools: saved priority first; newly verified models append, vanished models are skipped. */
+export function orderModelIds(ids, preferred) {
+    const available = new Set(ids);
+    return [...new Set([...preferred.filter((id) => available.has(id)), ...ids])];
+}

package/dist/models.d.ts

@@ -1,5 +1,6 @@
 import { type PiModelEndpointDiscoveryOptions } from "./pi-model-discovery.js";
 import { ClaudeModelInfo } from "./types.js";
+import { type ModelGroup } from "./model-groups.js";
 /**
  * The complete server-side model catalog. Keep this separate from the Claude
  * verification cache: the former is a client-facing snapshot for every
@@ -41,6 +42,9 @@ export interface ModelRefreshOptions {
     piEndpointDiscovery?: PiModelEndpointDiscoveryOptions & {
         enabled: boolean;
     };
+    managedPiModels?: () => readonly ClaudeModelInfo[];
+    managedPiModelMembers?: () => ClaudeModelInfo[];
+    modelGroups?: () => readonly ModelGroup[];
     now?: () => Date;
 }
 export interface ThinkingEffortLevel {
@@ -79,6 +83,9 @@ export declare const FALLBACK_PROVIDER_THINKING: ProviderThinkingEfforts;
  */
 export declare function withConfiguredDefaultModelLabels<T extends object>(catalog: T, defaults: Readonly<Record<string, string>>): T;
 export interface ModelCatalogSnapshot extends ModelCache {
+    modelGroups?: ModelGroup[];
+    /** Verified concrete free members, used only when editing the pool order. */
+    freeModels?: ClaudeModelInfo[];
     /** SHA-256 of the catalog excluding `refreshedAt`. Changes only with content. */
     revision: string;
 }
@@ -150,12 +157,17 @@ export declare class ModelCatalogService {
     private readonly getOptions;
     private cache;
     private revision;
+    private publishedRevision;
     private hasPersistedSnapshot;
     private refreshPromise;
     private inFlightIncludesVerification;
     private readonly changeListeners;
     constructor(getOptions: () => ModelRefreshOptions);
+    private withManagedPiModels;
+    publishManagedPiModels(): void;
     snapshot(): ModelCatalogSnapshot;
+    /** Preference changes publish immediately without re-running CLI discovery or altering stored history. */
+    publishModelGroups(): void;
     /** 目录内容真正变化时通知。客户端靠它刷新下拉，不用自己再跑一遍 CLI。 */
     onChanged(listener: (result: ModelCatalogRefreshResult) => void): () => void;
     refresh(request?: ModelCatalogRefreshRequest): Promise<ModelCatalogRefreshResult>;

package/dist/models.js

@@ -8,6 +8,8 @@ import Anthropic from "@anthropic-ai/sdk";
 import { resolveChildEnv } from "./env-utils.js";
 import { discoverPiEndpointModels } from "./pi-model-discovery.js";
 import { extractSemver } from "./version-utils.js";
+import { AUTO_ASSIGN_LABEL, AUTO_ASSIGN_SELECTOR, FREE_MODEL_GROUP_ID, isAutoAssignSelector, isModelGroupSelector, modelGroupSelector, orderModelIds } from "./model-groups.js";
+import { OPENROUTER_FREE_GROUP } from "./openrouter-free-selection.js";
 const execFileAsync = promisify(execFile);
 const CLAUDE_VERIFICATION_CACHE_KEY = "claude-model-verifications-v1";
 /**
@@ -59,7 +61,7 @@ const QODER_FALLBACK_MODELS = [
     { id: "ultimate", label: "Ultimate" },
 ];
 const PI_FALLBACK_MODELS = [
-    { id: "default", label: "跟随 Pi 默认", alias: true },
+    { id: "default", label: "跟随 one 的 Agent 默认", alias: true },
 ];
 /**
  * Gemini CLI 没有列模型的子命令，只能给出稳定别名（`packages/core/src/config/models.ts`
@@ -124,10 +126,14 @@ export function withConfiguredDefaultModelLabels(catalog, defaults) {
         if (at < 0)
             continue;
         const entry = list[at];
-        if (String(entry.label ?? "").includes(configured))
+        const selected = list.find((item) => item?.id === configured);
+        const name = configured.startsWith("wand-model-group/") || configured === "wand-openrouter-free/auto"
+            ? selected?.label || "模型分组"
+            : isAutoAssignSelector(configured) ? selected?.label || AUTO_ASSIGN_LABEL : configured;
+        if (String(entry.label ?? "").includes(name))
             continue;
         const updated = [...list];
-        updated[at] = { ...entry, label: `跟随服务端默认（${configured}）` };
+        updated[at] = { ...entry, label: `跟随服务端默认（${name}）` };
         next ??= { ...catalog };
         next[field] = updated;
     }
@@ -168,7 +174,7 @@ function normalizeClaudeModelId(value) {
     if (typeof value !== "string")
         return null;
     const id = value.trim();
-    return MODEL_ID_PATTERN.test(id) ? id : null;
+    return MODEL_ID_PATTERN.test(id) && !isModelGroupSelector(id) ? id : null;
 }
 function formatClaudeModelLabel(id, displayName) {
     const name = displayName?.trim();
@@ -389,6 +395,9 @@ async function probeQoderModels(runner, env) {
     }
 }
 async function probePiModels(runner, env, options) {
+    const agentDir = options.piEndpointDiscovery?.agentDir;
+    if (agentDir)
+        env = { ...env, PI_CODING_AGENT_DIR: agentDir };
     const rpcText = await commandText(runner, "pi", ["--mode", "rpc", "--no-session"], env, 12_000, `${JSON.stringify({ id: "wand-models", type: "get_available_models" })}\n`);
     const fromRpc = parsePiRpcModels(rpcText);
     let configuredModels = fromRpc.length > 1 || (fromRpc.length === 1 && fromRpc[0]?.id !== "default")
@@ -790,7 +799,7 @@ export function parsePiRpcModels(stdout) {
     return [
         {
             id: "default",
-            label: "跟随 Pi 默认",
+            label: "跟随 one 的 Agent 默认",
             alias: true,
             ...(union.length ? { reasoningEfforts: union } : {}),
         },
@@ -823,7 +832,7 @@ export function parsePiModels(stdout) {
     if (!discovered.length)
         return cloneModels(PI_FALLBACK_MODELS);
     return [
-        { id: "default", label: "跟随 Pi 默认", alias: true },
+        { id: "default", label: "跟随 one 的 Agent 默认", alias: true },
         ...discovered,
     ];
 }
@@ -953,6 +962,7 @@ function parsePersistedModelInfo(value) {
         id,
         label,
         ...(typeof value.alias === "boolean" ? { alias: value.alias } : {}),
+        ...(typeof value.group === "string" ? { group: value.group.slice(0, 80) } : {}),
         ...(source ? { source } : {}),
         ...(availability ? { availability } : {}),
         ...(note ? { note } : {}),
@@ -1150,6 +1160,7 @@ export class ModelCatalogService {
     getOptions;
     cache;
     revision;
+    publishedRevision;
     hasPersistedSnapshot;
     refreshPromise = null;
     inFlightIncludesVerification = false;
@@ -1159,11 +1170,92 @@ export class ModelCatalogService {
         const initialOptions = getOptions();
         const persisted = loadPersistedModelCatalog(initialOptions.storage);
         this.cache = persisted ? cloneCache(persisted.catalog) : createInitialCache(initialOptions);
-        this.revision = persisted?.revision ?? catalogRevision(this.cache);
+        this.cache.piModels = this.withManagedPiModels(this.cache.piModels);
+        this.revision = catalogRevision(this.cache);
         this.hasPersistedSnapshot = persisted !== null;
+        this.publishedRevision = this.snapshot().revision;
+    }
+    withManagedPiModels(models) {
+        const managed = this.getOptions().managedPiModels;
+        if (!managed)
+            return models;
+        const entries = managed();
+        const ids = new Set(entries.map((model) => model.id));
+        return [...models.filter((model) => !model.id.startsWith("wand-openrouter-free/") && !ids.has(model.id)), ...entries];
+    }
+    publishManagedPiModels() {
+        const next = { ...this.cache, piModels: this.withManagedPiModels(this.cache.piModels) };
+        const revision = catalogRevision(next);
+        const projectionChanged = this.snapshot().revision !== this.publishedRevision;
+        if (revision === this.revision && !projectionChanged)
+            return;
+        next.refreshedAt = new Date().toISOString();
+        this.cache = next;
+        this.revision = revision;
+        savePersistedModelCatalog(this.getOptions().storage, this.cache, revision);
+        const result = { ...this.snapshot(), changed: true, checkedAt: next.refreshedAt };
+        this.publishedRevision = result.revision;
+        for (const listener of this.changeListeners) {
+            try {
+                listener(result);
+            }
+            catch { /* notification must not prevent publication */ }
+        }
     }
     snapshot() {
-        return { ...cloneCache(this.cache), revision: this.revision };
+        const options = this.getOptions();
+        const configured = options.modelGroups?.() ?? [];
+        const catalog = cloneCache(this.cache);
+        // Virtual group identities are never concrete models or CLI verification targets.
+        for (const field of Object.values(PROVIDER_MODEL_LIST_FIELDS)) {
+            catalog[field] = catalog[field].filter((model) => !isModelGroupSelector(model.id));
+        }
+        const freeModels = options.managedPiModelMembers?.() ?? [];
+        const groups = structuredClone(configured.filter((group) => group.id !== FREE_MODEL_GROUP_ID));
+        if (options.managedPiModelMembers) {
+            const saved = configured.find((group) => group.id === FREE_MODEL_GROUP_ID && group.provider === "pi");
+            groups.push({ id: FREE_MODEL_GROUP_ID, provider: "pi", name: OPENROUTER_FREE_GROUP,
+                models: orderModelIds(freeModels.map((model) => model.id), saved?.models ?? []) });
+        }
+        for (const group of groups) {
+            if (group.id === FREE_MODEL_GROUP_ID)
+                continue; // Already published by OpenRouter as a single pool option.
+            const list = catalog[PROVIDER_MODEL_LIST_FIELDS[group.provider]];
+            const members = group.provider === "pi" ? [...list, ...freeModels] : list;
+            const memberInfo = group.models.map((id) => members.find((model) => model.id === id));
+            const efforts = memberInfo.every((model) => model?.reasoningEfforts?.length)
+                ? memberInfo[0].reasoningEfforts.filter((level) => memberInfo.every((model) => model.reasoningEfforts.some((item) => item.effort === level.effort))) : [];
+            list.push({ id: modelGroupSelector(group), label: group.name, group: "模型分组",
+                ...(efforts.length ? { reasoningEfforts: structuredClone(efforts) } : {}) });
+        }
+        const projection = { ...catalog, ...(groups.length ? { modelGroups: groups } : {}),
+            ...(options.managedPiModelMembers ? { freeModels } : {}) };
+        for (const field of Object.values(PROVIDER_MODEL_LIST_FIELDS)) {
+            const list = projection[field];
+            if (!list.some((model) => model.id === AUTO_ASSIGN_SELECTOR)) {
+                const entry = { id: AUTO_ASSIGN_SELECTOR, label: AUTO_ASSIGN_LABEL, alias: false,
+                    source: "builtin", availability: "default",
+                    note: "按第一条提示词在本工具的模型分组里自动选一个" };
+                // 默认项排在最前；智能分配紧跟其后，其余具体模型与分组保持原顺序。
+                if (list[0]?.id === "default")
+                    list.splice(1, 0, entry);
+                else
+                    list.unshift(entry);
+            }
+        }
+        return { ...projection, revision: groups.length
+                ? createHash("sha256").update(`${this.revision}:${JSON.stringify(groups)}:${JSON.stringify(freeModels)}`).digest("hex") : this.revision };
+    }
+    /** Preference changes publish immediately without re-running CLI discovery or altering stored history. */
+    publishModelGroups() {
+        const result = { ...this.snapshot(), changed: true, checkedAt: new Date().toISOString() };
+        this.publishedRevision = result.revision;
+        for (const listener of this.changeListeners) {
+            try {
+                listener(result);
+            }
+            catch { /* notification must not prevent saving */ }
+        }
     }
     /** 目录内容真正变化时通知。客户端靠它刷新下拉，不用自己再跑一遍 CLI。 */
     onChanged(listener) {
@@ -1197,6 +1289,7 @@ export class ModelCatalogService {
         };
         const checkedAt = (options.now?.() ?? new Date()).toISOString();
         const discovered = await discoverModelCache(options, this.cache);
+        discovered.piModels = this.withManagedPiModels(discovered.piModels);
         const discoveredRevision = catalogRevision(discovered);
         const changed = !this.hasPersistedSnapshot || discoveredRevision !== this.revision;
         if (changed) {
@@ -1208,6 +1301,7 @@ export class ModelCatalogService {
             this.hasPersistedSnapshot = Boolean(options.storage);
         }
         const result = { ...this.snapshot(), changed, checkedAt };
+        this.publishedRevision = result.revision;
         if (changed) {
             for (const listener of this.changeListeners) {
                 try {

package/dist/npm-update-utils.js

@@ -17,6 +17,7 @@ import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readF
 import path from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
+import { buildChildEnv } from "./env-utils.js";
 import { whichSync } from "./path-repair.js";
 import { getErrorMessage } from "./error-utils.js";
 import { compareWandInstallOrder, extractSemver } from "./version-utils.js";
@@ -114,7 +115,7 @@ function getChildEnv() {
         pathEntries.push(entry);
     }
     return {
-        ...process.env,
+        ...buildChildEnv(true),
         PATH: pathEntries.join(path.delimiter),
     };
 }

package/dist/openrouter-free-cli.d.ts

@@ -0,0 +1,25 @@
+import type { Model, Api } from "@earendil-works/pi-ai";
+import { OpenRouterFreeModelsService, type FreeModelRequirements } from "./openrouter-free-models.js";
+import type { WandStorage } from "./storage.js";
+import type { PreparedPiResources } from "./pi-resource-run.js";
+import type { StructuredRunnerContext } from "./structured-runner.js";
+export interface OpenRouterFreeCliPolicy {
+    databasePath: string;
+    model: Model<Api>;
+}
+export interface OpenRouterFreeCliDependencies {
+    storage: WandStorage;
+    service: OpenRouterFreeModelsService;
+}
+/** Only an opaque, revocable capability goes into the child env; never the connector Key. */
+export declare function prepareOpenRouterFreeCli(deps: OpenRouterFreeCliDependencies, context: StructuredRunnerContext): PreparedPiResources;
+/** Read-only projection: no migrations or shared catalog writes from a running Pi child. */
+export declare function openOpenRouterFreeCliAccess(databasePath: string, token: string, fetchImpl?: typeof fetch): {
+    selector: string;
+    requirements: FreeModelRequirements;
+    service: OpenRouterFreeModelsService;
+    assertCurrent: () => void;
+    close: () => void;
+};
+/** The CLI, not its original Server owner, revokes scope on shutdown. */
+export declare function revokeOpenRouterFreeCliAccess(databasePath: string, token: string): void;

package/dist/openrouter-free-cli.js

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { fileURLToPath } from "node:url";
+import { decryptVaultSecret } from "./password-manager.js";
+import { OpenRouterFreeModelsService, OPENROUTER_FREE_SELECTOR } from "./openrouter-free-models.js";
+/** Only an opaque, revocable capability goes into the child env; never the connector Key. */
+export function prepareOpenRouterFreeCli(deps, context) {
+    const selector = context.session.selectedModel;
+    const effort = context.session.thinkingEffort?.split(":").at(-1);
+    const requirements = { preferReasoning: !!effort && effort !== "off",
+        ...(context.modelGroupModels ? { allowedSelectors: context.modelGroupModels } : {}) };
+    const resolved = deps.service.resolve(selector, requirements) ?? deps.service.resolve(OPENROUTER_FREE_SELECTOR, requirements);
+    if (!resolved)
+        throw new Error("免费模型已下架或 OpenRouter Key 未配置，请同步免费分组并重新选择模型。");
+    const dir = mkdtempSync(path.join(os.tmpdir(), "wand-pi-free-"));
+    let token;
+    const close = () => {
+        if (token) {
+            try {
+                deps.storage.revokeOpenRouterFreeAccess(token);
+            }
+            catch { /* The durable CLI owns cleanup after a web restart. */ }
+        }
+        rmSync(dir, { recursive: true, force: true });
+    };
+    try {
+        token = deps.storage.issueOpenRouterFreeAccess(context.session.id, selector, createHash("sha256").update(resolved.apiKey).digest("hex"), requirements);
+        const file = path.join(dir, "model.json");
+        const policy = { databasePath: deps.storage.databasePath(), model: resolved.model };
+        writeFileSync(file, JSON.stringify(policy), { mode: 0o600 });
+        const js = fileURLToPath(new URL("./pi-openrouter-free-bridge.js", import.meta.url));
+        return { args: ["--extension", existsSync(js) ? js : js.replace(/\.js$/, ".ts")],
+            env: { ...context.env, WAND_PI_FREE_POLICY: file, WAND_PI_FREE_TOKEN: token }, close };
+    }
+    catch (error) {
+        close();
+        throw error;
+    }
+}
+/** Read-only projection: no migrations or shared catalog writes from a running Pi child. */
+export function openOpenRouterFreeCliAccess(databasePath, token, fetchImpl = globalThis.fetch) {
+    if (!path.isAbsolute(databasePath) || !/^wf_[A-Za-z0-9_-]{43}$/.test(token)) {
+        throw new Error("免费模型调用授权无效。");
+    }
+    const db = new DatabaseSync(databasePath, { readOnly: true });
+    const hash = createHash("sha256").update(token).digest("hex");
+    const scope = () => {
+        const row = db.prepare(`SELECT a.* FROM openrouter_free_access a JOIN command_sessions s ON s.id = a.session_id
+      WHERE a.token_hash = ? AND a.expires_at > ? AND s.provider = 'pi' AND s.session_kind = 'structured'
+        AND s.status = 'running'`).get(hash, Date.now());
+        if (!row)
+            throw new Error("免费模型调用授权已失效，请重新发送。");
+        return row;
+    };
+    try {
+        const access = scope();
+        const readConfig = (key) => {
+            const value = db.prepare("SELECT value FROM app_config WHERE key = ?").get(key)?.value;
+            return typeof value === "string" ? value : null;
+        };
+        const localCache = new Map();
+        const storage = {
+            getConnectorToken: () => {
+                const current = scope();
+                const encrypted = db.prepare("SELECT token FROM connectors WHERE provider = 'openrouter'").get()?.token;
+                const key = typeof encrypted === "string" ? decryptVaultSecret(encrypted, readConfig("appSecret")) : null;
+                if (!key || createHash("sha256").update(key).digest("hex") !== current.credential_hash) {
+                    throw new Error("OpenRouter Key 已变化，本次免费调用已停止，请重新发送。");
+                }
+                return key;
+            },
+            getConfigValue: (key) => localCache.get(key) ?? readConfig(key),
+            setConfigValue: (key, value) => { scope(); localCache.set(key, value); },
+            getPreference: (key, fallback) => {
+                try {
+                    return JSON.parse(readConfig(key) ?? "null") ?? fallback;
+                }
+                catch {
+                    return fallback;
+                }
+            },
+            saveConnector: () => { throw new Error("CLI 不可修改 OpenRouter Key。"); },
+            deleteConnector: () => { throw new Error("CLI 不可删除 OpenRouter Key。"); },
+        };
+        const service = new OpenRouterFreeModelsService(storage, fetchImpl);
+        return { selector: String(access.selector), requirements: JSON.parse(String(access.requirements_json)),
+            service, assertCurrent: () => { storage.getConnectorToken("openrouter"); },
+            close: () => { service.dispose(); db.close(); } };
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+/** The CLI, not its original Server owner, revokes scope on shutdown. */
+export function revokeOpenRouterFreeCliAccess(databasePath, token) {
+    const db = new DatabaseSync(databasePath);
+    try {
+        db.exec("PRAGMA busy_timeout = 5000");
+        db.prepare("DELETE FROM openrouter_free_access WHERE token_hash = ?")
+            .run(createHash("sha256").update(token).digest("hex"));
+    }
+    finally {
+        db.close();
+    }
+}