@co0ontty/wand 4.83.1 → 4.84.0

package/dist/pi-openrouter-free-bridge.js

@@ -0,0 +1,80 @@
+/** Pi CLI provider bridge. No Agent/SDK runner and no changes to the user's Pi auth/models files. */
+import { readFileSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+import { createAssistantMessageEventStream, lazyApi } from "@earendil-works/pi-ai";
+import { OPENROUTER_FREE_PROVIDER, OPENROUTER_FREE_ROUTING } from "./openrouter-free-models.js";
+import { openOpenRouterFreeCliAccess, revokeOpenRouterFreeCliAccess } from "./openrouter-free-cli.js";
+export default function wandOpenRouterFree(pi) {
+    const file = process.env.WAND_PI_FREE_POLICY;
+    const token = process.env.WAND_PI_FREE_TOKEN ?? "";
+    delete process.env.WAND_PI_FREE_POLICY;
+    delete process.env.WAND_PI_FREE_TOKEN;
+    if (!file)
+        throw new Error("免费模型调用缺少本轮策略。");
+    const policy = JSON.parse(readFileSync(file, "utf8"));
+    // Pi applies its HTTP/proxy configuration after factories load; use the current fetch per request.
+    const access = openOpenRouterFreeCliAccess(policy.databasePath, token, (url, init) => globalThis.fetch(url, init));
+    const api = lazyApi(() => import("@earendil-works/pi-ai/api/openai-completions"));
+    let activeModel = policy.model;
+    const streamSimple = (model, transcript, options) => {
+        const stream = createAssistantMessageEventStream();
+        void (async () => {
+            let key = "";
+            try {
+                const checked = await access.service.resolveForCall(`${OPENROUTER_FREE_PROVIDER}/${activeModel.id}`, options?.signal, access.requirements);
+                activeModel = checked.model;
+                key = checked.apiKey;
+                const inner = api.streamSimple(activeModel, transcript, {
+                    ...options, apiKey: key,
+                    maxTokens: Math.min(options?.maxTokens ?? activeModel.maxTokens, activeModel.maxTokens),
+                    reasoning: activeModel.reasoning ? options?.reasoning : undefined,
+                    onPayload: async (payload, dispatchedModel) => {
+                        const customized = await options?.onPayload?.(payload, dispatchedModel) ?? payload;
+                        access.assertCurrent();
+                        return { ...customized, model: activeModel.id, provider: OPENROUTER_FREE_ROUTING };
+                    },
+                });
+                for await (const event of inner) {
+                    if (event.type === "error" && event.error.errorMessage) {
+                        event.error.errorMessage = event.error.errorMessage.replaceAll(key, "[REDACTED]");
+                    }
+                    stream.push(event);
+                }
+            }
+            catch (cause) {
+                const reason = options?.signal?.aborted ? "aborted" : "error";
+                const message = cause instanceof Error ? cause.message : "免费模型调用失败。";
+                stream.push({ type: "error", reason, error: {
+                        role: "assistant", content: [], api: model.api, provider: model.provider, model: activeModel.id,
+                        timestamp: Date.now(), stopReason: reason, errorMessage: key ? message.replaceAll(key, "[REDACTED]") : message,
+                        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+                            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+                    } });
+            }
+            finally {
+                stream.end();
+            }
+        })();
+        return stream;
+    };
+    // Use a distinct API handler: never replace Pi's built-in openai-completions implementation.
+    pi.registerProvider(OPENROUTER_FREE_PROVIDER, {
+        name: "OpenRouter 免费分组", api: "wand-openrouter-free-completions", apiKey: "wand-scoped-free-inference",
+        baseUrl: activeModel.baseUrl,
+        models: [{ ...activeModel, api: "wand-openrouter-free-completions",
+                id: access.selector.slice(OPENROUTER_FREE_PROVIDER.length + 1) }],
+        streamSimple,
+    });
+    let closed = false;
+    pi.on("session_shutdown", () => {
+        if (closed)
+            return;
+        closed = true;
+        access.close();
+        try {
+            revokeOpenRouterFreeCliAccess(policy.databasePath, token);
+        }
+        catch { /* Expiry and the parent are additional cleanup paths. */ }
+        rmSync(dirname(file), { recursive: true, force: true });
+    });
+}

package/dist/pi-resource-bridge.d.ts

@@ -0,0 +1,2 @@
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function wandResourceSelection(pi: ExtensionAPI): Promise<void>;

package/dist/pi-resource-bridge.js

@@ -0,0 +1,73 @@
+/** Explicit CLI extension: replaces built-in MCP discovery without changing the user's agent directory. */
+import { readFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createCodemodeExtension, createMcpExtension, createToolSearchExtension } from "@earendil-works/pi-coding-agent";
+export default async function wandResourceSelection(pi) {
+    const policyFile = process.env.WAND_PI_RESOURCE_POLICY;
+    if (!policyFile)
+        throw new Error("Wand 资源选择缺少本轮策略。");
+    const policy = JSON.parse(readFileSync(policyFile, "utf8"));
+    // Entries were validated by Pi's parser immediately before spawning. Read only this user's file;
+    // do not replace the agent directory or discover trusted-project/extension servers implicitly.
+    const allowed = new Set(policy.mcpServers ?? []);
+    const scoped = new Proxy(pi, { get(target, key) {
+            // Extensions may register servers too. They are not the file-configured entries the user selected.
+            if (key === "getMcpServers")
+                return () => [];
+            const value = Reflect.get(target, key);
+            return typeof value === "function" ? value.bind(target) : value;
+        } });
+    if (policy.mcpServers)
+        createMcpExtension({
+            loadConfig: () => {
+                if (!allowed.size)
+                    return { servers: [], errors: [] };
+                try {
+                    const source = join(policy.agentDir, "mcp.json");
+                    const raw = JSON.parse(readFileSync(source, "utf8"));
+                    const servers = policy.mcpServers.map((name) => {
+                        const config = raw.mcpServers?.[name];
+                        if (!config)
+                            throw new Error("MCP 已移除");
+                        return { name, source, scope: "global", config: { ...config, enabled: true } };
+                    });
+                    return { servers, errors: [], autoEnableCodemode: policy.codemodeOverride !== "off" && raw.autoEnableCodemode !== false };
+                }
+                catch {
+                    return { servers: [], errors: ["所选 MCP 配置无法读取，没有连接其他服务器。"] };
+                }
+            },
+            updateConfig: () => { throw new Error("请通过 Wand 输入框中的 Skills / MCP 设置修改本会话选择。"); },
+        })(scoped);
+    if (policy.codemodeOverride) {
+        // This explicit factory replaces the CLI builtin and can express `only` without modifying
+        // settings.json. Active-tool changes preserve every common tool and selected MCP connection.
+        const codemodeApi = policy.codemodeOverride === "off" ? new Proxy(pi, { get(target, key) {
+                if (key === "registerTool")
+                    return (definition) => target.registerTool({ ...definition, exposure: "hidden" });
+                const value = Reflect.get(target, key);
+                return typeof value === "function" ? value.bind(target) : value;
+            } }) : pi;
+        createCodemodeExtension({ mode: policy.codemodeOverride === "only" ? "only" : "on" })(codemodeApi);
+        // MCP tools with indirect exposure still need an entrance when CodeMode is explicitly off.
+        const searchInstead = policy.codemodeOverride === "off" && !!policy.mcpServers?.length;
+        if (searchInstead)
+            createToolSearchExtension()(pi);
+        const apply = () => {
+            const other = pi.getActiveTools().filter((name) => name !== "codemode");
+            pi.setActiveTools(policy.codemodeOverride === "off"
+                ? searchInstead ? [...other, "tool_search"] : other : [...other, "codemode"]);
+        };
+        pi.on("session_start", apply);
+        pi.on("before_agent_start", apply);
+        pi.on("tool_call", (event) => {
+            if (event.toolName === "codemode" && policy.codemodeOverride === "off") {
+                return { block: true, reason: "本会话已关闭 CodeMode，请在输入框设置中启用。" };
+            }
+        });
+    }
+    pi.on("session_shutdown", () => {
+        // The CLI outlives web restarts: cleanup belongs to the child, not only its original web owner.
+        rmSync(dirname(policyFile), { recursive: true, force: true });
+    });
+}

package/dist/pi-resource-catalog.d.ts

@@ -0,0 +1,18 @@
+import type { PiResourceCatalog, PiResourceSelection } from "./pi-session-settings.js";
+import type { WandConfig } from "./types.js";
+import type { Skill, McpExtensionOptions } from "@earendil-works/pi-coding-agent";
+type McpConfig = ReturnType<NonNullable<McpExtensionOptions["loadConfig"]>>;
+export interface PiResourceInventory {
+    catalog: PiResourceCatalog;
+    skills: Map<string, Skill>;
+    servers: Map<string, McpConfig["servers"][number]>;
+}
+/** Pinned, read-only parser boundary; never connects, runs credential commands or loads extension code. */
+export declare function readUserPiMcpConfig(agentDir: string, cwd: string): Promise<McpConfig>;
+/** Installed USER resources only. No package downloads and no project config mutation/trust elevation. */
+export declare function discoverPiResources(config: Pick<WandConfig, "harness">, cwd: string): Promise<PiResourceInventory>;
+export declare function resolvePiResourceSelection(inventory: PiResourceInventory, selection: PiResourceSelection): {
+    skills: Skill[];
+    servers: McpConfig["servers"];
+};
+export {};

package/dist/pi-resource-catalog.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { coreHarnessAgentDir, loadPiCodingAgent } from "./harness-engine.js";
+function resourceId(kind, identity) {
+    return `${kind}-${createHash("sha256").update(identity).digest("hex").slice(0, 24)}`;
+}
+/** Pinned, read-only parser boundary; never connects, runs credential commands or loads extension code. */
+export async function readUserPiMcpConfig(agentDir, cwd) {
+    const url = new URL("./extensions/mcp/config.js", import.meta.resolve("@earendil-works/pi-coding-agent"));
+    const parser = await import(url.href);
+    return parser.loadMcpConfig({ agentDir, cwd, projectTrusted: false });
+}
+/** Installed USER resources only. No package downloads and no project config mutation/trust elevation. */
+export async function discoverPiResources(config, cwd) {
+    const pi = await loadPiCodingAgent();
+    const agentDir = coreHarnessAgentDir(config.harness);
+    let raw = {};
+    try {
+        const content = await readFile(path.join(agentDir, "settings.json"), "utf8");
+        if (content.length > 1_048_576)
+            throw new Error("配置过大");
+        raw = JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw new Error("Pi 资源配置无法读取，请检查 settings.json。");
+    }
+    const settings = pi.SettingsManager.inMemory({
+        packages: Array.isArray(raw.packages) ? raw.packages : [],
+        skills: Array.isArray(raw.skills) ? raw.skills.filter((item) => typeof item === "string") : [],
+        extensions: Array.isArray(raw.extensions) ? raw.extensions.filter((item) => typeof item === "string") : [],
+    }, { projectTrusted: false });
+    const manager = new pi.DefaultPackageManager({ cwd, agentDir, settingsManager: settings });
+    const resolved = await manager.resolve(async () => "skip");
+    const paths = resolved.skills.filter((item) => item.enabled && item.metadata.scope === "user").map((item) => item.path);
+    const loaded = pi.loadSkills({ cwd, agentDir, skillPaths: paths, includeDefaults: false });
+    const skills = new Map();
+    for (const skill of loaded.skills) {
+        const canonical = await realpath(skill.filePath);
+        const info = await stat(canonical);
+        if (!info.isFile() || info.size > 128 * 1024)
+            continue;
+        const id = resourceId("skill", canonical);
+        if (!skills.has(id))
+            skills.set(id, { ...skill, filePath: canonical });
+        if (skills.size >= 200)
+            break;
+    }
+    const mcp = await readUserPiMcpConfig(agentDir, cwd);
+    const servers = new Map();
+    for (const server of mcp.servers.slice(0, 64))
+        servers.set(resourceId("mcp", server.name), server);
+    const customMcp = resolved.extensions.some((item) => item.enabled && /pi-mcp-adapter/.test(item.metadata.source));
+    return { skills, servers, catalog: {
+            supported: !customMcp,
+            reason: customMcp ? "当前 Pi 使用第三方 MCP 适配器，无法保证只连接选定服务器，请先使用 Pi 内置 MCP。"
+                : mcp.errors.length ? "MCP 配置含无效条目，仅列出已验证的服务器；未选条目不会连接。" : "",
+            skills: [...skills].map(([id, skill]) => ({ id, name: skill.name,
+                description: skill.description.slice(0, 1024), source: "已安装" })),
+            mcpServers: [...servers].map(([id, server]) => ({ id, name: server.name,
+                description: "url" in server.config ? "已配置的 HTTP MCP 服务" : "已配置的本地 MCP 服务",
+                source: server.config.enabled === false ? "全局停用 · 本会话可选" : "用户配置" })),
+        } };
+}
+export function resolvePiResourceSelection(inventory, selection) {
+    if (!inventory.catalog.supported)
+        throw new Error(inventory.catalog.reason);
+    const skills = selection.skills.map((id) => {
+        const found = inventory.skills.get(id);
+        if (!found)
+            throw new Error("所选 Skill 已不存在或已被停用，请重新选择；没有改用其他 Skill。");
+        return found;
+    });
+    const servers = selection.mcpServers.map((id) => {
+        const found = inventory.servers.get(id);
+        if (!found)
+            throw new Error("所选 MCP 已不存在，请重新选择；没有连接其他 MCP。");
+        return found;
+    });
+    return { skills, servers };
+}

package/dist/pi-resource-recommendation.d.ts

@@ -0,0 +1,29 @@
+import { type DecisionResult } from "./decision-types.js";
+import { type PiResourceCatalog, type PiResourceRecommendation, type PiResourceSelection } from "./pi-session-settings.js";
+export declare const PI_RECOMMEND_MAX_CANDIDATES = 24;
+export declare const PI_RECOMMEND_MAX_PROMPT = 1200;
+export type PiResourceEvaluator = (value: unknown, caller: string, signal?: AbortSignal) => Promise<DecisionResult>;
+export declare function parsePiRecommendationRequest(raw: unknown): {
+    prompt: string;
+    candidates: PiResourceSelection;
+};
+export interface PiAutomaticCodemodeChoice {
+    override?: "off" | "on";
+    source: "explicit" | "local" | "uncertain";
+}
+/** CodeMode is a per-round tool entry choice, never authority to execute its tools. */
+export declare function decidePiCodemode(input: {
+    prompt: string;
+    evaluate: PiResourceEvaluator;
+    caller: string;
+    signal?: AbortSignal;
+}): Promise<PiAutomaticCodemodeChoice>;
+/** Read-only matching. Results never modify settings, connect MCP, or authorize an operation. */
+export declare function recommendPiResources(input: {
+    prompt: string;
+    candidates: PiResourceSelection;
+    catalog: PiResourceCatalog;
+    evaluate: PiResourceEvaluator;
+    caller: string;
+    signal?: AbortSignal;
+}): Promise<PiResourceRecommendation>;

package/dist/pi-resource-recommendation.js

@@ -0,0 +1,169 @@
+import { DecisionError } from "./decision-types.js";
+import { isPiSettingsDraft, patchPiResourceSelection } from "./pi-session-settings.js";
+export const PI_RECOMMEND_MAX_CANDIDATES = 24;
+export const PI_RECOMMEND_MAX_PROMPT = 1200;
+export function parsePiRecommendationRequest(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new DecisionError("INVALID_REQUEST", "请提供当前提示词和候选资源。");
+    const body = raw;
+    if (Object.keys(body).some((key) => key !== "prompt" && key !== "candidates")
+        || typeof body.prompt !== "string" || !body.prompt.trim() || isPiSettingsDraft(body.prompt)
+        || body.prompt.length > PI_RECOMMEND_MAX_PROMPT) {
+        throw new DecisionError("INVALID_REQUEST", "请先输入任务提示词（最多1200字符）；设置命令不能用于推荐。");
+    }
+    const candidates = patchPiResourceSelection(body.candidates);
+    if (!candidates.skills.every((id) => id.startsWith("skill-")) || !candidates.mcpServers.every((id) => id.startsWith("mcp-"))
+        || candidates.skills.length + candidates.mcpServers.length > PI_RECOMMEND_MAX_CANDIDATES) {
+        throw new DecisionError("CANDIDATE_LIMIT", "一次最多推荐24项资源，请用搜索缩小候选范围。");
+    }
+    return { prompt: body.prompt.trim(), candidates };
+}
+/** Literal resource names only; conservative exclusions take priority over inclusion. */
+function explicitMention(prompt, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const literal = new RegExp(`(^|[^a-zA-Z0-9_-])${escaped}(?=$|[^a-zA-Z0-9_-])`, "i");
+    let included = false;
+    for (const clause of prompt.split(/[。！？!?；;\n，,]/)) {
+        const match = literal.exec(clause);
+        if (!match)
+            continue;
+        const before = clause.slice(0, match.index + match[1].length);
+        const after = clause.slice(match.index + match[0].length);
+        if (/(?:不要|不用|不使用|不启用|不加载|不连接|排除|禁用|停用|无需|不需要|without|do not|don['’]t|exclude|disable)/i.test(before)
+            || /^\s*(?:也|暂时|这次)?\s*(?:不要|不用|不使用|不启用|不加载|不连接|禁用|停用|不需要|disabled|excluded)/i.test(after))
+            return "excluded";
+        included = true;
+    }
+    return included ? "included" : null;
+}
+/** Strip only standalone resource switches, never business constraints or the submitted prompt itself. */
+function resourceTask(prompt, catalog) {
+    const names = [...catalog.skills, ...catalog.mcpServers].map((item) => item.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    if (!names.length)
+        return prompt;
+    const name = `(?:${names.join("|")})`;
+    const verb = "(?:不要|不用|不使用|不启用|不加载|不连接|排除|禁用|停用|无需|不需要|使用|启用|加载|连接|without|do not use|don't use|exclude|disable|use|enable)";
+    const switchOnly = new RegExp(`^(?:(?:也|这次|暂时)\\s*)?${verb}\\s*${name}$|^${name}\\s*(?:(?:也|这次|暂时)\\s*)?${verb}$`, "i");
+    const clauses = prompt.split(/[。！？!?；;\n，,]/);
+    const task = clauses.filter((clause) => !switchOnly.test(clause.trim()));
+    return task.length === clauses.length ? prompt : task.filter((clause) => clause.trim()).join("，").trim();
+}
+const MATCH_INSTRUCTIONS = "Which skill fits the task?";
+/** Keep the task separate from skill marketing text; the small model overweights long descriptions. */
+function shortlistQuestions(name) {
+    return {
+        forward: { type: "choice", instructions: MATCH_INSTRUCTIONS, criteria: { match: name, none: "None" } },
+        reverse: { type: "choice", instructions: MATCH_INSTRUCTIONS, criteria: { none: "None", match: name } },
+    };
+}
+function matchProbability(result, id) {
+    const answer = result.answers[id];
+    const probabilities = answer?.probabilities;
+    const match = probabilities?.match;
+    const none = probabilities?.none;
+    if (answer?.type !== "choice" || !["match", "none"].includes(String(answer.choice))
+        || typeof match !== "number" || typeof none !== "number" || !Number.isFinite(match) || !Number.isFinite(none)
+        || match < 0 || match > 1 || none < 0 || none > 1 || Math.abs(match + none - 1) > 0.002
+        || (answer.choice === "match" ? match < none : none < match)) {
+        throw new DecisionError("INVALID_RESULT", "本地模型返回无效判断，原选择未改变。", 502);
+    }
+    return match;
+}
+/** CodeMode is a per-round tool entry choice, never authority to execute its tools. */
+export async function decidePiCodemode(input) {
+    if (input.signal?.aborted)
+        throw new DecisionError("CANCELLED", "CodeMode 自动判断已取消。", 499);
+    const mention = explicitMention(input.prompt, "codemode") ?? explicitMention(input.prompt, "code mode");
+    if (mention === "excluded")
+        return { override: "off", source: "explicit" };
+    if (mention === "included" && (/(?:使用|启用|开启|打开|通过|用|enable|use)\s*code\s?mode/i.test(input.prompt)
+        || /code\s?mode\s*(?:开启|启用|打开|on\b)/i.test(input.prompt)))
+        return { override: "on", source: "explicit" };
+    let result;
+    try {
+        result = await input.evaluate({
+            state: input.prompt,
+            questions: {
+                forward: { type: "choice", instructions: "How to run the tools?",
+                    criteria: { match: "Batch tool calls", none: "Ordinary tool calls" } },
+                reverse: { type: "choice", instructions: "How to run the tools?",
+                    criteria: { none: "Ordinary tool calls", match: "Batch tool calls" } },
+            },
+        }, input.caller, input.signal);
+    }
+    catch (error) {
+        if (error instanceof DecisionError && ["CONTEXT_LIMIT", "QUESTION_LIMIT", "OPTIONS_COLLAPSED"].includes(error.code)) {
+            return { source: "uncertain" };
+        }
+        throw error;
+    }
+    const forward = matchProbability(result, "forward");
+    const reverse = matchProbability(result, "reverse");
+    if (forward >= 0.8 && reverse >= 0.8)
+        return { override: "on", source: "local" };
+    if (forward <= 0.2 && reverse <= 0.2)
+        return { override: "off", source: "local" };
+    return { source: "uncertain" };
+}
+/** Read-only matching. Results never modify settings, connect MCP, or authorize an operation. */
+export async function recommendPiResources(input) {
+    const resources = [];
+    const task = resourceTask(input.prompt, input.catalog);
+    let calls = 0;
+    for (const kind of ["skills", "mcpServers"]) {
+        for (const id of input.candidates[kind]) {
+            if (input.signal?.aborted)
+                throw new DecisionError("CANCELLED", "推荐已取消。", 499);
+            const item = input.catalog[kind].find((resource) => resource.id === id);
+            if (!item)
+                throw new DecisionError("RESOURCE_MISSING", "候选资源已移除，请重新打开设置面板。");
+            const mention = explicitMention(input.prompt, item.name);
+            if (mention) {
+                resources.push({ id, kind, status: mention === "included" ? "recommended" : "unmatched", source: "explicit" });
+                continue;
+            }
+            // Transport type is not a description of a server's capabilities. Never connect for discovery.
+            if (!task || kind === "mcpServers" || item.description.length > 1000) {
+                resources.push({ id, kind, status: "unassessed", source: "local" });
+                continue;
+            }
+            let result;
+            try {
+                calls++;
+                const shortlist = await input.evaluate({ state: task, questions: shortlistQuestions(item.name) }, input.caller, input.signal);
+                const forward = matchProbability(shortlist, "forward");
+                const reverse = matchProbability(shortlist, "reverse");
+                if (forward < 0.8 || reverse < 0.8) {
+                    resources.push({ id, kind, status: forward <= 0.2 && reverse <= 0.2 ? "unmatched" : "uncertain", source: "local" });
+                    continue;
+                }
+                if (input.signal?.aborted)
+                    throw new DecisionError("CANCELLED", "推荐已取消。", 499);
+                // A name match alone cannot load a skill. Confirm against its complete description.
+                calls++;
+                result = await input.evaluate({
+                    state: { task, resource: { name: item.name, description: item.description } },
+                    questions: { relevant: { type: "noul", instructions: "Does this skill match the task?" } },
+                }, input.caller, input.signal);
+            }
+            catch (error) {
+                if (error instanceof DecisionError && ["CONTEXT_LIMIT", "QUESTION_LIMIT", "OPTIONS_COLLAPSED"].includes(error.code)) {
+                    resources.push({ id, kind, status: "unassessed", source: "local" });
+                    continue;
+                }
+                throw error;
+            }
+            const relevant = result.answers.relevant?.noul;
+            if (typeof relevant !== "number" || !Number.isFinite(relevant) || relevant < 0 || relevant > 1) {
+                throw new DecisionError("INVALID_RESULT", "本地模型返回无效判断，原选择未改变。", 502);
+            }
+            const status = relevant >= 0.8 ? "recommended" : relevant <= 0.2 ? "unmatched" : "uncertain";
+            resources.push({ id, kind, status, source: "local" });
+        }
+    }
+    const selection = { skills: [], mcpServers: [] };
+    for (const resource of resources)
+        if (resource.status === "recommended")
+            selection[resource.kind].push(resource.id);
+    return { selection, resources, calls, experimental: true };
+}

package/dist/pi-resource-run.d.ts

@@ -0,0 +1,8 @@
+import type { PiResourceSelection } from "./pi-session-settings.js";
+export interface PreparedPiResources {
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    close(): void;
+}
+/** Re-resolve at execution time: removed resources fail, never silently enable defaults. */
+export declare function preparePiResources(agentDir: string, cwd: string, selection: PiResourceSelection | undefined, baseEnv: NodeJS.ProcessEnv, codemodeOverride?: "off" | "on" | "only"): Promise<PreparedPiResources>;

package/dist/pi-resource-run.js

@@ -0,0 +1,28 @@
+import { existsSync, mkdtempSync, chmodSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { discoverPiResources, resolvePiResourceSelection } from "./pi-resource-catalog.js";
+/** Re-resolve at execution time: removed resources fail, never silently enable defaults. */
+export async function preparePiResources(agentDir, cwd, selection, baseEnv, codemodeOverride) {
+    const selected = selection ? resolvePiResourceSelection(await discoverPiResources({ harness: { engine: "cli", agentDir } }, cwd), selection) : undefined;
+    const privateDir = mkdtempSync(path.join(os.tmpdir(), "wand-pi-resources-"));
+    chmodSync(privateDir, 0o700);
+    try {
+        const file = path.join(privateDir, "selection.json");
+        writeFileSync(file, JSON.stringify({ agentDir, codemodeOverride,
+            ...(selected ? { mcpServers: selected.servers.map((server) => server.name) } : {}) }), { mode: 0o600 });
+        const js = fileURLToPath(new URL("./pi-resource-bridge.js", import.meta.url));
+        const bridge = existsSync(js) ? js : js.replace(/\.js$/, ".ts");
+        return {
+            args: [...(selected ? ["--no-skills", ...selected.skills.flatMap((skill) => ["--skill", skill.filePath])] : []),
+                "--extension", bridge],
+            env: { ...baseEnv, WAND_PI_RESOURCE_POLICY: file },
+            close: () => rmSync(privateDir, { recursive: true, force: true }),
+        };
+    }
+    catch (error) {
+        rmSync(privateDir, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/pi-session-settings.d.ts

@@ -0,0 +1,157 @@
+/** Shared, data-only contract for per-session Pi settings. */
+export declare const PI_BUILTIN_TOOLS: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
+export type PiBuiltinTool = typeof PI_BUILTIN_TOOLS[number];
+/**
+ * pi-goal 注册的工具名。Pi 的 `--tools` 是白名单（会替换默认集合），所以 CLI 会话要开启目标模式
+ * 必须逐个点名；名字与 `core-extension-host.ts` 的排除列表保持同一份。
+ */
+export declare const PI_GOAL_TOOLS: readonly ["create_goal", "get_goal", "update_goal"];
+export interface PiSessionSettings {
+    codemode: "off" | "on" | "only";
+    /** Optional per-session CLI override; omitted means Pi's own CodeMode setting. */
+    codemodeOverride?: "off" | "on" | "only";
+    globalTools: boolean;
+    goalMode: boolean;
+    tools: PiBuiltinTool[];
+    localDecision: boolean;
+    autoCompaction: boolean;
+    /** Omitted on legacy sessions = existing Pi discovery; present = exact, opt-in resources. */
+    resources?: PiResourceSelection;
+    /** Skill IDs whose current on/off state automatic selection must preserve. Manual edits remain allowed. */
+    lockedSkills?: string[];
+    /** Explicit opt-in: select unlocked skills per prompt; preserve skill locks and manual MCP selections. */
+    autoResources?: boolean;
+}
+export type PiSessionSettingsPatch = Omit<Partial<PiSessionSettings>, "codemodeOverride"> & {
+    codemodeOverride?: "off" | "on" | "only" | null;
+};
+export interface PiResourceSelection {
+    skills: string[];
+    mcpServers: string[];
+}
+export type PiSkillMode = "off" | "on" | "locked";
+export declare function piSkillMode(settings: PiSessionSettings, id: string): PiSkillMode;
+/** A single manual gesture changes selection and lock atomically, never mutating its snapshot. */
+export declare function piSkillModePatch(settings: PiSessionSettings, id: string, mode: PiSkillMode): PiSessionSettingsPatch;
+export interface PiResourceSelectionNotice {
+    status: "selecting" | "selected" | "fallback" | "cancelled";
+    label: string;
+    skills: string[];
+    mcpServers: string[];
+    codemode?: {
+        mode: "off" | "on" | "only" | "follow";
+        source: "manual" | "automatic" | "uncertain" | "fallback";
+    };
+}
+export interface PiResourceItem {
+    id: string;
+    name: string;
+    description: string;
+    source: string;
+}
+export interface PiResourceRecommendation {
+    selection: PiResourceSelection;
+    resources: Array<{
+        id: string;
+        kind: "skills" | "mcpServers";
+        status: "recommended" | "unmatched" | "uncertain" | "unassessed";
+        source: "explicit" | "local";
+    }>;
+    calls: number;
+    experimental: true;
+}
+export interface PiResourceCatalog {
+    skills: PiResourceItem[];
+    mcpServers: PiResourceItem[];
+    /** Listing does not connect to any server or evaluate credentials. */
+    supported: boolean;
+    reason: string;
+}
+export declare function patchPiResourceSelection(raw: unknown): PiResourceSelection;
+export declare function defaultPiSessionSettings(autoCompaction?: boolean): PiSessionSettings;
+/**
+ * CLI 会话的出厂默认：完全跟随 Pi 自身配置（默认工具 + 已安装的全局扩展 + codemode），
+ * 与直接在终端里跑 `pi` 一致——用户已经装好的子代理、待办、CodeMode 不该因为从 Wand 启动就消失。
+ * 想逐项挑选工具时再关掉「全局扩展工具」，会话就切到 Wand 托管的 `--tools` 白名单。
+ * 进程内 SDK 会话仍用 `defaultPiSessionSettings`：员工会话不静默继承用户的全局扩展。
+ */
+export declare function defaultPiCliSessionSettings(autoCompaction?: boolean): PiSessionSettings;
+/** Strict partial updates: an invalid/unknown field never silently enables a capability. */
+export declare function patchPiSessionSettings(current: PiSessionSettings, raw: unknown): PiSessionSettings;
+/**
+ * CLI 会话的工具选择策略。
+ *
+ * Pi CLI 的 `--tools` 是**白名单**：一旦给出，未列出的工具（含扩展工具、codemode、目标工具）
+ * 都不在注册表里；不给出时才用 Pi 自身的 `defaultTools` + 全部扩展工具。因此只有两条真实可表达的路径：
+ *
+ * - `allowlist`：Wand 逐项接管——只启用勾选的基础工具，CodeMode / 目标模式按开关把工具名追加进白名单。
+ * - `config`：`globalTools` 打开时完全跟随 Pi 自身配置（默认工具 + 已安装的全局扩展），
+ *   逐项开关在该模式下不参与启动参数，UI 会如实说明而不是伪造生效。
+ */
+export interface PiToolSelection {
+    mode: "allowlist" | "config";
+    names: string[];
+}
+/**
+ * `codemode: "only"`（连声明都藏起来、只从脚本调用）由 Pi 的 `codemode.mode` 设置决定，
+ * 没有对应的 CLI 开关：CLI 会话一律按「启用」处理，读取时也归一到 `on`，不谎报模式。
+ */
+export declare function cliCodemode(codemode: PiSessionSettings["codemode"]): "off" | "on";
+/** 会话设置在该引擎下真正生效的形态（目前只有 CLI 的 CodeMode 需要归一）。 */
+export declare function effectivePiSessionSettings(settings: PiSessionSettings, engine: "core" | "cli"): PiSessionSettings;
+export declare function piToolSelection(settings: PiSessionSettings): PiToolSelection;
+export interface PiSettingsResponse {
+    settings: PiSessionSettings;
+    available: boolean;
+    reason: string;
+    engine: "core" | "cli";
+    /** CLI Pi 支持的基础工具 allowlist；core/SDK 专属开关仍由 available 表示。 */
+    toolsAvailable: boolean;
+    goalAvailable: boolean;
+    globalExtensions: string[];
+    localDecisionAvailable: boolean;
+    /**
+     * 逐项可用性由服务端裁决；客户端只按这里禁用，不再自己推断引擎。
+     * 早期服务端不带这个字段，客户端必须用 `piSettingsControls()` 退回它当时的真实能力，
+     * 不能假装开关可用（写了也不会生效）。
+     */
+    controls?: PiSettingsControls;
+    /** Absent on older servers. Never contains file paths, URLs, commands, env or credentials. */
+    resourceCatalog?: PiResourceCatalog;
+    /** Read-only recommendation; applying remains a separate, explicit settings update. */
+    recommendationAvailable?: boolean;
+    recommendationReason?: string;
+    autoResourcesAvailable?: boolean;
+    autoResourcesReason?: string;
+    /** Older automatic-resource servers do not infer CodeMode. */
+    autoCodemodeAvailable?: boolean;
+    /** Absent on older servers; clients must not pretend skill locks are supported. */
+    skillLocksAvailable?: boolean;
+}
+export interface PiSettingsControls {
+    tools: boolean;
+    codemode: boolean;
+    /** 是否提供「仅 CodeMode」（只有进程内 SDK 会话能表达）。 */
+    codemodeOnly: boolean;
+    /** Per-turn bridge supports exact off/on/only, independent of globalTools. */
+    codemodeOverride?: boolean;
+    globalTools: boolean;
+    goalMode: boolean;
+    localDecision: boolean;
+    autoCompaction: boolean;
+}
+export declare const NO_PI_SETTINGS_CONTROLS: PiSettingsControls;
+/**
+ * 面板逐项可用性。新服务端直接给 `controls`；没有这个字段的旧服务端按它当时的语义退回：
+ * SDK 原生开关看 `available`，CLI 只开放基础工具列表，其余一律不可改。
+ */
+export declare function piSettingsControls(response: Partial<PiSettingsResponse> | null | undefined): PiSettingsControls;
+/** CLI 会话能表达的设置字段；其余字段只对进程内 SDK 会话有意义。 */
+export declare const PI_CLI_SETTING_KEYS: readonly ["tools", "codemode", "globalTools", "goalMode", "localDecision", "resources", "lockedSkills", "codemodeOverride", "autoResources"];
+/**
+ * CLI 会话的写入裁决：无法表达的字段/取值直接拒绝，不能存下一条永远不会生效的设置。
+ * 返回拒绝原因，允许时返回 null。
+ */
+export declare function cliPiSettingsRejection(raw: unknown, next: PiSessionSettings): string | null;
+/** Only settings commands, never paths, extension commands, or ordinary slash-prefixed text. */
+export declare function isPiSettingsDraft(text: string): boolean;