@co0ontty/wand 4.83.1 → 4.84.0

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

@@ -0,0 +1,85 @@
+import type { Model, Api } from "@earendil-works/pi-ai";
+import type { WandStorage } from "./storage.js";
+import type { ClaudeModelInfo } from "./types.js";
+export { OPENROUTER_FREE_PROVIDER, OPENROUTER_FREE_GROUP, OPENROUTER_FREE_SELECTOR, isOpenRouterFreeSelector } from "./openrouter-free-selection.js";
+export declare const OPENROUTER_REFRESH_MS: number;
+/** Same zero-price routing constraint for validation and actual core calls. */
+export declare const OPENROUTER_FREE_ROUTING: {
+    require_parameters: boolean;
+    max_price: {
+        prompt: number;
+        completion: number;
+        request: number;
+        image: number;
+    };
+};
+export interface OpenRouterStatus {
+    configured: boolean;
+    group: string;
+    modelCount: number;
+    lastCheckedAt: string | null;
+    lastSyncedAt: string | null;
+    lastError: string | null;
+    refreshIntervalHours: number;
+    candidateCount: number;
+    rejectedCount: number;
+}
+/** Only zero-priced language models with text input/output and tool support can serve the agent. */
+export declare function parseOpenRouterFreeModels(body: unknown): Model<Api>[];
+export interface FreeModelRequirements {
+    preferReasoning?: boolean;
+    /** A custom group must never substitute a free model from outside its membership. */
+    allowedSelectors?: readonly string[];
+}
+export type OpenRouterFreeStorage = Pick<WandStorage, "getConnectorToken" | "getConfigValue" | "setConfigValue" | "getPreference" | "saveConnector" | "deleteConnector">;
+/** Server-owned credentials and last successful catalog; never writes Pi's auth/models files. */
+export declare class OpenRouterFreeModelsService {
+    private readonly storage;
+    private readonly fetchImpl;
+    private readonly now;
+    private models;
+    private lastCheckedAt;
+    private lastSyncedAt;
+    private error;
+    private candidateCount;
+    private rejectedCount;
+    private revision;
+    private catalogSequence;
+    private committedSequence;
+    private credentialController;
+    private pending;
+    private controller;
+    private timer;
+    private disposed;
+    private listeners;
+    constructor(storage: OpenRouterFreeStorage, fetchImpl?: typeof fetch, now?: () => Date);
+    private key;
+    status(): OpenRouterStatus;
+    catalog(): ClaudeModelInfo[];
+    /** Concrete verified members for the group editor; no key or provider payload is exposed. */
+    members(): ClaudeModelInfo[];
+    private orderedModels;
+    resolve(selector: string | null | undefined, requirements?: FreeModelRequirements): {
+        model: Model<Api>;
+        apiKey: string;
+    } | null;
+    onChanged(listener: () => void): () => void;
+    private notify;
+    saveKey(value: unknown): Promise<OpenRouterStatus>;
+    clearKey(): OpenRouterStatus;
+    refresh(): Promise<OpenRouterStatus>;
+    private performRefresh;
+    private fetchCandidates;
+    private publish;
+    /** Fresh pricing is mandatory for each inference, including tool-loop continuations. */
+    resolveForCall(selector: string, signal?: AbortSignal, requirements?: FreeModelRequirements): Promise<{
+        model: Model<Api>;
+        apiKey: string;
+    }>;
+    /** Every discovered model must answer a real message before it becomes selectable. */
+    private validateModels;
+    private probeModel;
+    private closedStatus;
+    start(): void;
+    dispose(): void;
+}

package/dist/openrouter-free-models.js

@@ -0,0 +1,458 @@
+import { freeModelOrder, normalizeModelGroups, orderModelIds } from "./model-groups.js";
+import { OPENROUTER_FREE_PROVIDER, OPENROUTER_FREE_GROUP, OPENROUTER_FREE_SELECTOR, isOpenRouterFreeSelector } from "./openrouter-free-selection.js";
+export { OPENROUTER_FREE_PROVIDER, OPENROUTER_FREE_GROUP, OPENROUTER_FREE_SELECTOR, isOpenRouterFreeSelector } from "./openrouter-free-selection.js";
+export const OPENROUTER_REFRESH_MS = 6 * 60 * 60 * 1000;
+const CACHE_KEY = "openrouter-free-models-v1";
+const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,100}$/;
+const MAX_BYTES = 4 * 1024 * 1024;
+const PROBE_TIMEOUT_MS = 20000;
+const PROBE_CONCURRENCY = 2;
+const PROBE_VERSION = 2;
+/** Same zero-price routing constraint for validation and actual core calls. */
+export const OPENROUTER_FREE_ROUTING = {
+    require_parameters: true,
+    max_price: { prompt: 0, completion: 0, request: 0, image: 0 },
+};
+async function readJsonResponse(response, maxBytes) {
+    if (Number(response.headers.get("content-length")) > maxBytes) {
+        throw new OpenRouterSyncError("OpenRouter 返回内容过大。");
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new OpenRouterSyncError("OpenRouter 返回了空内容。");
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > maxBytes)
+                throw new OpenRouterSyncError("OpenRouter 返回内容过大。");
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+class OpenRouterSyncError extends Error {
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+/** Only zero-priced language models with text input/output and tool support can serve the agent. */
+export function parseOpenRouterFreeModels(body) {
+    const rows = record(body).data;
+    if (!Array.isArray(rows))
+        throw new OpenRouterSyncError("OpenRouter 返回的模型目录格式无效。");
+    const models = new Map();
+    for (const entry of rows.slice(0, 4000)) {
+        const row = record(entry);
+        const pricing = record(row.pricing);
+        const zero = (value) => (typeof value === "number" || (typeof value === "string" && value.trim() !== ""))
+            && Number.isFinite(Number(value)) && Number(value) === 0;
+        if (!zero(pricing.prompt) || !zero(pricing.completion)
+            || !Object.values(pricing).every(zero))
+            continue;
+        const architecture = record(row.architecture);
+        const inputs = architecture.input_modalities;
+        const outputs = architecture.output_modalities;
+        // Understanding images is allowed; generating images, video, audio, or unknown outputs is not.
+        if (!Array.isArray(inputs) || !inputs.includes("text")
+            || !Array.isArray(outputs) || outputs.length === 0
+            || !outputs.every((modality) => modality === "text"))
+            continue;
+        if (!Array.isArray(row.supported_parameters) || !row.supported_parameters.includes("tools"))
+            continue;
+        const id = typeof row.id === "string" ? row.id.trim() : "";
+        if (!MODEL_PATTERN.test(id))
+            continue;
+        const contextWindow = Number(row.context_length);
+        if (!Number.isSafeInteger(contextWindow) || contextWindow < 1024)
+            continue;
+        const reportedMax = Number(record(row.top_provider).max_completion_tokens);
+        const maxTokens = Number.isSafeInteger(reportedMax) && reportedMax > 0
+            ? Math.min(reportedMax, contextWindow) : Math.min(8192, contextWindow);
+        models.set(id, {
+            id,
+            name: typeof row.name === "string" ? row.name.slice(0, 160) : id,
+            provider: OPENROUTER_FREE_PROVIDER,
+            api: "openai-completions",
+            baseUrl: "https://openrouter.ai/api/v1",
+            reasoning: row.supported_parameters.includes("reasoning"),
+            compat: { thinkingFormat: "openrouter" },
+            input: Array.isArray(architecture.input_modalities) && architecture.input_modalities.includes("image")
+                ? ["text", "image"] : ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow,
+            maxTokens,
+        });
+    }
+    return [...models.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Prefer requested reasoning support, then a larger context/output budget for coding tasks. */
+function automaticModelOrder(models, requirements) {
+    return [...models].sort((a, b) => (requirements.preferReasoning ? Number(b.reasoning) - Number(a.reasoning) : 0)
+        || b.contextWindow - a.contextWindow
+        || b.maxTokens - a.maxTokens
+        || a.id.localeCompare(b.id));
+}
+/** Server-owned credentials and last successful catalog; never writes Pi's auth/models files. */
+export class OpenRouterFreeModelsService {
+    storage;
+    fetchImpl;
+    now;
+    models = [];
+    lastCheckedAt = null;
+    lastSyncedAt = null;
+    error = null;
+    candidateCount = 0;
+    rejectedCount = 0;
+    revision = 0;
+    catalogSequence = 0;
+    committedSequence = 0;
+    credentialController = new AbortController();
+    pending = null;
+    controller = null;
+    timer = null;
+    disposed = false;
+    listeners = new Set();
+    constructor(storage, fetchImpl = globalThis.fetch, now = () => new Date()) {
+        this.storage = storage;
+        this.fetchImpl = fetchImpl;
+        this.now = now;
+        try {
+            const cached = record(JSON.parse(storage.getConfigValue(CACHE_KEY) ?? "{}"));
+            // Restore through the same validator rather than trusting stored runtime model fields.
+            if (this.key() && cached.body && cached.probeVersion === PROBE_VERSION) {
+                this.models = parseOpenRouterFreeModels(cached.body);
+                this.candidateCount = Math.max(this.models.length, Number(cached.candidateCount) || 0);
+                this.rejectedCount = this.candidateCount - this.models.length;
+            }
+            if (cached.probeVersion === PROBE_VERSION && typeof cached.lastSyncedAt === "string" && Number.isFinite(Date.parse(cached.lastSyncedAt))) {
+                this.lastSyncedAt = cached.lastSyncedAt;
+            }
+        }
+        catch { /* A malformed cache can be rediscovered. */ }
+    }
+    key() { return this.storage.getConnectorToken("openrouter") ?? ""; }
+    status() {
+        return {
+            configured: !!this.key(), group: OPENROUTER_FREE_GROUP, modelCount: this.models.length,
+            lastCheckedAt: this.lastCheckedAt, lastSyncedAt: this.lastSyncedAt, lastError: this.error,
+            refreshIntervalHours: OPENROUTER_REFRESH_MS / 3600000,
+            candidateCount: this.candidateCount, rejectedCount: this.rejectedCount,
+        };
+    }
+    catalog() {
+        if (this.disposed || !this.models.length || !this.key())
+            return [];
+        // One selectable pool, not a category that still requires choosing a concrete model.
+        const efforts = this.models.some((model) => model.reasoning)
+            ? ["off", "minimal", "low", "medium", "high"] : ["off"];
+        return [{
+                id: OPENROUTER_FREE_SELECTOR,
+                label: OPENROUTER_FREE_GROUP,
+                reasoningEfforts: efforts.map((effort) => ({ effort })),
+            }];
+    }
+    /** Concrete verified members for the group editor; no key or provider payload is exposed. */
+    members() {
+        if (this.disposed || !this.key())
+            return [];
+        return this.orderedModels(this.models, {}).map((model) => ({
+            id: `${OPENROUTER_FREE_PROVIDER}/${model.id}`, label: `${model.name} · ${model.id}`,
+            reasoningEfforts: (model.reasoning ? ["off", "minimal", "low", "medium", "high"] : ["off"])
+                .map((effort) => ({ effort })),
+        }));
+    }
+    orderedModels(models, requirements) {
+        const groups = normalizeModelGroups(this.storage.getPreference("pref:modelGroups", []));
+        const automatic = automaticModelOrder(models, requirements).filter((model) => !requirements.allowedSelectors
+            || requirements.allowedSelectors.includes(`${OPENROUTER_FREE_PROVIDER}/${model.id}`));
+        const order = orderModelIds(automatic.map((model) => `${OPENROUTER_FREE_PROVIDER}/${model.id}`), requirements.allowedSelectors ?? freeModelOrder(groups));
+        const byId = new Map(automatic.map((model) => [`${OPENROUTER_FREE_PROVIDER}/${model.id}`, model]));
+        return order.map((id) => byId.get(id));
+    }
+    resolve(selector, requirements = {}) {
+        if (this.disposed || !isOpenRouterFreeSelector(selector))
+            return null;
+        const id = selector.slice(OPENROUTER_FREE_PROVIDER.length + 1);
+        const model = selector === OPENROUTER_FREE_SELECTOR
+            ? this.orderedModels(this.models, requirements)[0] : this.models.find((entry) => entry.id === id);
+        const apiKey = this.key();
+        return model && apiKey ? { model: structuredClone(model), apiKey } : null;
+    }
+    onChanged(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    notify() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch { /* An observer must not invalidate a successful sync. */ }
+        }
+    }
+    async saveKey(value) {
+        if (typeof value !== "string" || !value.trim() || value.length > 512 || /\s/.test(value.trim())) {
+            throw new TypeError("请填写有效的 OpenRouter Key。");
+        }
+        const key = value.trim();
+        this.revision++;
+        this.credentialController.abort();
+        this.credentialController = new AbortController();
+        this.controller?.abort();
+        const changedKey = key !== this.key();
+        this.storage.saveConnector("openrouter", { token: key, apiUrl: "https://openrouter.ai/api/v1" });
+        if (changedKey) {
+            // Validation belongs to the credential used for the probe.
+            this.models = [];
+            this.candidateCount = 0;
+            this.rejectedCount = 0;
+            this.lastSyncedAt = null;
+            this.storage.setConfigValue(CACHE_KEY, "{}");
+            this.notify();
+        }
+        this.error = null;
+        return this.refresh();
+    }
+    clearKey() {
+        this.revision++;
+        this.credentialController.abort();
+        this.credentialController = new AbortController();
+        this.controller?.abort();
+        this.storage.deleteConnector("openrouter");
+        this.storage.setConfigValue(CACHE_KEY, "{}");
+        this.models = [];
+        this.candidateCount = 0;
+        this.rejectedCount = 0;
+        this.lastCheckedAt = null;
+        this.lastSyncedAt = null;
+        this.error = null;
+        this.notify();
+        return this.status();
+    }
+    refresh() {
+        if (this.disposed)
+            return Promise.resolve(this.closedStatus());
+        if (!this.key())
+            return Promise.resolve(this.status());
+        if (this.pending?.revision === this.revision)
+            return this.pending.promise;
+        const revision = this.revision;
+        const promise = this.performRefresh(revision);
+        this.pending = { revision, promise };
+        return promise.finally(() => { if (this.pending?.promise === promise)
+            this.pending = null; });
+    }
+    async performRefresh(revision) {
+        const controller = new AbortController();
+        this.controller = controller;
+        const sequence = ++this.catalogSequence;
+        const current = () => !this.disposed && this.revision === revision && sequence >= this.committedSequence;
+        try {
+            const candidates = await this.fetchCandidates(this.key(), controller.signal);
+            if (!current())
+                return this.disposed ? this.closedStatus() : this.status();
+            // A continuous free price and an earlier successful probe allow reuse.
+            const verified = new Set(this.models.map((model) => model.id));
+            const newModels = await this.validateModels(candidates.filter((model) => !verified.has(model.id)), this.key(), controller.signal);
+            if (!current())
+                return this.disposed ? this.closedStatus() : this.status();
+            const passed = new Set([...verified, ...newModels.map((model) => model.id)]);
+            this.publish(candidates, candidates.filter((model) => passed.has(model.id)), sequence);
+        }
+        catch (cause) {
+            if (current()) {
+                this.lastCheckedAt = this.now().toISOString();
+                // Network/provider errors may echo credentials: only emit our own bounded messages.
+                this.error = cause instanceof OpenRouterSyncError
+                    ? cause.message : "OpenRouter 同步失败，请检查网络后重试。";
+            }
+        }
+        finally {
+            if (this.controller === controller)
+                this.controller = null;
+        }
+        return this.disposed ? this.closedStatus() : this.status();
+    }
+    async fetchCandidates(apiKey, signal) {
+        const response = await this.fetchImpl("https://openrouter.ai/api/v1/models/user", {
+            headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
+            redirect: "error",
+            signal: AbortSignal.any([signal, AbortSignal.timeout(15000)]),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new OpenRouterSyncError(response.status === 401 || response.status === 403
+                ? "OpenRouter Key 无效或没有访问权限。"
+                : `OpenRouter 价格检查失败（HTTP ${response.status}）。`);
+        }
+        return parseOpenRouterFreeModels(await readJsonResponse(response, MAX_BYTES));
+    }
+    publish(candidates, models, sequence) {
+        const checkedAt = this.now().toISOString();
+        const body = { data: models.map((model) => ({
+                id: model.id, name: model.name, context_length: model.contextWindow,
+                top_provider: { max_completion_tokens: model.maxTokens },
+                pricing: { prompt: "0", completion: "0" },
+                supported_parameters: model.reasoning ? ["tools", "reasoning"] : ["tools"],
+                architecture: { input_modalities: model.input, output_modalities: ["text"] },
+            })) };
+        this.storage.setConfigValue(CACHE_KEY, JSON.stringify({ body, lastSyncedAt: checkedAt,
+            probeVersion: PROBE_VERSION, candidateCount: candidates.length }));
+        this.models = models;
+        this.candidateCount = candidates.length;
+        this.rejectedCount = candidates.length - models.length;
+        this.lastCheckedAt = checkedAt;
+        this.lastSyncedAt = checkedAt;
+        this.error = null;
+        this.committedSequence = sequence;
+        this.notify();
+    }
+    /** Fresh pricing is mandatory for each inference, including tool-loop continuations. */
+    async resolveForCall(selector, signal, requirements = {}) {
+        if (this.disposed || !isOpenRouterFreeSelector(selector))
+            throw new Error("免费模型服务不可用。");
+        const apiKey = this.key();
+        if (!apiKey)
+            throw new Error("OpenRouter Key 未配置，请先保存 Key。");
+        const revision = this.revision;
+        const sequence = ++this.catalogSequence;
+        const callSignal = signal
+            ? AbortSignal.any([signal, this.credentialController.signal]) : this.credentialController.signal;
+        const assertCurrent = () => {
+            if (this.disposed || this.revision !== revision || apiKey !== this.key()
+                || callSignal.aborted || sequence < this.committedSequence) {
+                throw new Error("免费模型配置或目录已变化，本次调用已停止，请重试。");
+            }
+        };
+        let candidates;
+        try {
+            candidates = await this.fetchCandidates(apiKey, callSignal);
+        }
+        catch (cause) {
+            // Never proceed with stale prices when a fresh lookup fails.
+            const message = cause instanceof OpenRouterSyncError
+                ? cause.message : "OpenRouter 价格检查失败，本次调用已停止，请重试。";
+            if (!this.disposed && this.revision === revision && sequence >= this.committedSequence) {
+                this.lastCheckedAt = this.now().toISOString();
+                this.error = message;
+            }
+            throw new Error(message);
+        }
+        assertCurrent();
+        const verifiedIds = new Set(this.models.map((model) => model.id));
+        const verified = candidates.filter((model) => verifiedIds.has(model.id));
+        // Removing a paid/missing entry also invalidates its earlier usability proof.
+        this.publish(candidates, verified, sequence);
+        const id = selector.slice(OPENROUTER_FREE_PROVIDER.length + 1);
+        const automatic = selector === OPENROUTER_FREE_SELECTOR;
+        const permitted = (model) => !requirements.allowedSelectors
+            || requirements.allowedSelectors.includes(`${OPENROUTER_FREE_PROVIDER}/${model.id}`);
+        let chosen = (automatic ? undefined : verified.find((model) => model.id === id && permitted(model)))
+            ?? this.orderedModels(verified, requirements)[0];
+        if (!chosen) {
+            const preferred = automatic ? undefined : candidates.find((model) => model.id === id && permitted(model));
+            const alternatives = this.orderedModels(candidates, requirements);
+            const ordered = preferred ? [preferred, ...alternatives.filter((model) => model.id !== id)] : alternatives;
+            for (const candidate of ordered) {
+                const usable = await this.probeModel(candidate, apiKey, callSignal);
+                assertCurrent();
+                if (usable) {
+                    chosen = candidate;
+                    break;
+                }
+            }
+            if (chosen)
+                this.publish(candidates, [chosen], sequence);
+        }
+        if (!chosen)
+            throw new Error("当前没有已验证且免费的模型，本次调用已停止，请稍后同步免费分组。");
+        assertCurrent();
+        return { model: structuredClone(chosen), apiKey };
+    }
+    /** Every discovered model must answer a real message before it becomes selectable. */
+    async validateModels(candidates, apiKey, signal) {
+        const passed = new Set();
+        let next = 0;
+        await Promise.all(Array.from({ length: Math.min(PROBE_CONCURRENCY, candidates.length) }, async () => {
+            while (!signal.aborted) {
+                const model = candidates[next++];
+                if (!model)
+                    break;
+                if (await this.probeModel(model, apiKey, signal))
+                    passed.add(model.id);
+            }
+        }));
+        return candidates.filter((model) => passed.has(model.id));
+    }
+    async probeModel(model, apiKey, signal) {
+        try {
+            const response = await this.fetchImpl("https://openrouter.ai/api/v1/chat/completions", {
+                method: "POST",
+                headers: { Accept: "application/json", "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+                redirect: "error",
+                signal: AbortSignal.any([signal, AbortSignal.timeout(PROBE_TIMEOUT_MS)]),
+                body: JSON.stringify({
+                    model: model.id,
+                    stream: false,
+                    max_tokens: Math.min(512, model.maxTokens),
+                    messages: [
+                        { role: "system", content: "你是标题助手。只返回简短标题，不要解释，不要使用工具。" },
+                        { role: "user", content: "请为这段对话拟一个简短标题：用户正在设置免费AI模型，并验证模型是否可以正常回复。" },
+                    ],
+                    // Exercise a tool-capable request without granting executable tools.
+                    tools: [{ type: "function", function: {
+                                name: "connectivity_check", description: "连接测试占位工具，请勿调用。",
+                                parameters: { type: "object", properties: {} },
+                            } }],
+                    provider: OPENROUTER_FREE_ROUTING,
+                    ...(model.reasoning ? { reasoning: { effort: "none" } } : {}),
+                }),
+            });
+            if (!response.ok) {
+                await response.body?.cancel();
+                return false;
+            }
+            const body = record(await readJsonResponse(response, 64 * 1024));
+            if (body.error || !Array.isArray(body.choices) || body.choices.length === 0)
+                return false;
+            const choice = record(body.choices[0]);
+            const message = record(choice.message);
+            return choice.finish_reason === "stop" && typeof message.content === "string"
+                && message.content.trim().length > 0 && !message.refusal
+                && (!Array.isArray(message.tool_calls) || message.tool_calls.length === 0);
+        }
+        catch {
+            // Provider/network failures can echo secrets. Retain only the pass/fail result.
+            return false;
+        }
+    }
+    closedStatus() {
+        return { configured: false, group: OPENROUTER_FREE_GROUP, modelCount: 0, lastCheckedAt: null,
+            lastSyncedAt: null, lastError: null, refreshIntervalHours: 6, candidateCount: 0, rejectedCount: 0 };
+    }
+    start() {
+        if (this.timer || this.disposed)
+            return;
+        void this.refresh();
+        this.timer = setInterval(() => { void this.refresh(); }, OPENROUTER_REFRESH_MS);
+        this.timer.unref();
+    }
+    dispose() {
+        this.disposed = true;
+        this.revision++;
+        this.credentialController.abort();
+        this.controller?.abort();
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        this.listeners.clear();
+    }
+}

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

@@ -0,0 +1,5 @@
+/** Public model selection identity shared by the server and browser; contains no credentials. */
+export declare const OPENROUTER_FREE_PROVIDER = "wand-openrouter-free";
+export declare const OPENROUTER_FREE_GROUP = "\u514D\u8D39\u5206\u7EC4";
+export declare const OPENROUTER_FREE_SELECTOR = "wand-openrouter-free/auto";
+export declare function isOpenRouterFreeSelector(selector: string | null | undefined): boolean;

package/dist/openrouter-free-selection.js

@@ -0,0 +1,7 @@
+/** Public model selection identity shared by the server and browser; contains no credentials. */
+export const OPENROUTER_FREE_PROVIDER = "wand-openrouter-free";
+export const OPENROUTER_FREE_GROUP = "免费分组";
+export const OPENROUTER_FREE_SELECTOR = `${OPENROUTER_FREE_PROVIDER}/auto`;
+export function isOpenRouterFreeSelector(selector) {
+    return selector?.startsWith(`${OPENROUTER_FREE_PROVIDER}/`) === true;
+}

package/dist/path-repair.d.ts

@@ -21,6 +21,12 @@
  *      "前插"到 process.env.PATH 前面。这
  *      是真正能修好"unit 里 PATH 太旧、用户 shell 里却好好的"这种场景的关键。
  *
+ * 同一次探测还回收登录 shell 的**完整环境**（rc 里 export 的变量），交给
+ * src/env-utils.ts 作为所有 CLI 子进程的底座：服务进程 env 与 shell env 冲突时
+ * 保留进程值（本轮显式启动的参数最大），shell 只填补进程里没有的变量。PATH 顺序
+ * 由上面第 2 层单独重排，所以两条链路的 CLI 版本一致。
+ * WAND_SHELL_ENV_DISABLE=1 只关掉环境回收，不影响 PATH 修复。
+ *
  * 设计决策：
  *   - 同步那层只追加不前插：尊重用户已有顺序；异步那层愿意前插，因为它拿到的是
  *     用户实际"会用的"PATH，比 unit 里的更可信。
@@ -42,6 +48,10 @@ export interface PathRepairResult {
     finalPath: string;
     /** login shell 探测阶段的状态：success / disabled / failed / skipped。 */
     deepProbe: "success" | "disabled" | "failed" | "skipped";
+    /** login shell 探测实际使用的 shell；用于确认服务环境与用户默认 shell 对齐。 */
+    shell?: string;
+    /** 登录 shell 里进程环境没有、因此新回收给子进程的变量数。 */
+    shellEnvVars?: number;
     /** 异步阶段产生的告警信息（login shell 超时、解析失败等）。 */
     warnings: string[];
 }