@co0ontty/wand 4.82.0 → 4.83.1

package/dist/decision-client.js

@@ -0,0 +1,91 @@
+import { readFileSync } from "node:fs";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { DECISION_MAX_BYTES, DecisionError, parseDecisionRequest, parseDecisionResult } from "./decision-types.js";
+/** No admin/password lookup, redirects, or implicit remote fallback. Credentials stay in headers. */
+export async function callDecisionService(request, env = process.env) {
+    const endpoint = env.WAND_DECISION_URL;
+    const token = env.WAND_DECISION_TOKEN;
+    if (!endpoint || !token || !/^wd_[A-Za-z0-9_-]{43}$/.test(token)) {
+        throw new DecisionError("UNBOUND", "请在启用了本地决策的 Wand 结构化会话中调用；不会自动读取管理员凭据。");
+    }
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new DecisionError("UNBOUND", "无效决策服务地址。");
+    }
+    const loopback = ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+    if (url.username || url.password || url.search || url.hash || url.pathname !== "/"
+        || (url.protocol !== "https:" && !(url.protocol === "http:" && loopback))) {
+        throw new DecisionError("UNBOUND", "远程决策服务必须使用HTTPS，地址只能包含origin。");
+    }
+    url.pathname = request ? "/api/decisions/evaluate" : "/api/decisions/status";
+    const data = request ? JSON.stringify(request) : "";
+    return new Promise((resolve, reject) => {
+        const send = url.protocol === "https:" ? httpsRequest : httpRequest;
+        const req = send(url, {
+            method: request ? "POST" : "GET",
+            ...(url.protocol === "https:" && env.WAND_DECISION_CA ? { ca: readFileSync(env.WAND_DECISION_CA) } : {}),
+            headers: { Authorization: `Bearer ${token}`, Accept: "application/json",
+                ...(data ? { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(data) } : {}) },
+        }, (res) => {
+            const chunks = [];
+            let bytes = 0;
+            res.on("data", (chunk) => {
+                bytes += chunk.length;
+                if (bytes > 128 * 1024)
+                    req.destroy(new Error("oversize"));
+                else
+                    chunks.push(chunk);
+            });
+            res.on("error", () => reject(new DecisionError("CONNECTION_FAILED", "决策服务响应中断。", 502)));
+            res.on("end", () => {
+                try {
+                    const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                    if ((res.statusCode ?? 500) < 200 || (res.statusCode ?? 500) >= 300) {
+                        // Only bounded machine codes, never echo a remote response containing secrets.
+                        const code = typeof value?.code === "string" && /^[A-Z_]{1,40}$/.test(value.code) ? value.code : "HTTP_ERROR";
+                        reject(new DecisionError(code, `决策调用失败 (${code}, HTTP ${res.statusCode})。`, res.statusCode));
+                    }
+                    else
+                        resolve(request ? parseDecisionResult(value, request) : value);
+                }
+                catch {
+                    reject(new DecisionError("INVALID_RESULT", "决策服务返回了无效结果。", 502));
+                }
+            });
+        });
+        const deadline = setTimeout(() => req.destroy(new Error("deadline")), 50_000);
+        req.once("close", () => clearTimeout(deadline));
+        req.once("error", () => reject(new DecisionError("CONNECTION_FAILED", "连接决策服务失败或超时。", 502)));
+        req.end(data);
+    });
+}
+export async function runDecisionCli(args) {
+    if (args.length !== 1 || !["--stdin", "--status"].includes(args[0])) {
+        throw new DecisionError("USAGE", "用法：wand decide --stdin（JSON标准输入）或 --status。");
+    }
+    let request = null;
+    if (args[0] === "--stdin") {
+        const chunks = [];
+        let bytes = 0;
+        for await (const chunk of process.stdin) {
+            const buffer = Buffer.from(chunk);
+            bytes += buffer.length;
+            if (bytes > DECISION_MAX_BYTES)
+                throw new DecisionError("REQUEST_TOO_LARGE", "请求超过32KiB。", 413);
+            chunks.push(buffer);
+        }
+        let value;
+        try {
+            value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        }
+        catch {
+            throw new DecisionError("INVALID_REQUEST", "标准输入必须是有效JSON。");
+        }
+        request = parseDecisionRequest(value);
+    }
+    process.stdout.write(`${JSON.stringify(await callDecisionService(request))}\n`);
+}

package/dist/decision-runner.d.ts

@@ -0,0 +1,9 @@
+import type { WandStorage } from "./storage.js";
+import type { StructuredRunnerAdapter } from "./structured-runner.js";
+export interface DecisionRuntimeAccess {
+    url: string;
+    caPath?: string;
+}
+export declare const DECISION_ENV_KEYS: readonly ["WAND_DECISION_URL", "WAND_DECISION_TOKEN", "WAND_DECISION_CA", "WAND_DECISION_NODE", "WAND_DECISION_CLI"];
+/** Adds only a revocable inference capability. Never edits base prompts, DTOs, or tool permissions. */
+export declare function withDecisionAccess(runner: StructuredRunnerAdapter, storage: WandStorage, runtime: () => DecisionRuntimeAccess | null): StructuredRunnerAdapter;

package/dist/decision-runner.js

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+export const DECISION_ENV_KEYS = ["WAND_DECISION_URL", "WAND_DECISION_TOKEN", "WAND_DECISION_CA", "WAND_DECISION_NODE", "WAND_DECISION_CLI"];
+/** Adds only a revocable inference capability. Never edits base prompts, DTOs, or tool permissions. */
+export function withDecisionAccess(runner, storage, runtime) {
+    return { start(context, observer) {
+            const env = { ...context.env };
+            for (const key of DECISION_ENV_KEYS)
+                delete env[key];
+            const access = runtime();
+            if (!access)
+                return runner.start({ ...context, env }, observer);
+            const token = storage.issueDecisionAccess(context.session.id);
+            const cleanup = () => { try {
+                storage.revokeDecisionAccess(token);
+            }
+            catch { /* storage may be closing */ } };
+            const js = fileURLToPath(new URL("./cli.js", import.meta.url));
+            // Source-mode tests/development can still call the CLI via Node's tsx loader in the skill client.
+            const cli = existsSync(js) ? js : js.replace(/\.js$/, ".ts");
+            try {
+                const execution = runner.start({ ...context, env: { ...env,
+                        WAND_DECISION_URL: access.url, WAND_DECISION_TOKEN: token,
+                        WAND_DECISION_NODE: process.execPath, WAND_DECISION_CLI: cli,
+                        ...(access.caPath ? { WAND_DECISION_CA: access.caPath } : {}),
+                    }, session: { ...context.session, runtimeSystemPrompt: [context.session.runtimeSystemPrompt,
+                            "可选本地判断工具：wand-decision skill。适用于有界选择、评分、是非判断，不替代主模型或操作授权。仅在需要且有命令权限时使用；不要打印或转存调用环境中的凭据。",
+                        ].filter(Boolean).join("\n\n") } }, observer);
+                return { ...execution, completion: execution.completion.finally(cleanup), interrupt: () => { cleanup(); execution.interrupt(); } };
+            }
+            catch (error) {
+                cleanup();
+                throw error;
+            }
+        } };
+}

package/dist/decision-service.d.ts

@@ -0,0 +1,46 @@
+import { type DecisionResult, type LocalDecisionConfig } from "./decision-types.js";
+interface DecisionServiceOptions {
+    workerPath?: string;
+    timeoutMs?: number;
+    idleMs?: number;
+    supported?: () => boolean;
+}
+/** One bounded worker per server. It owns no sessions, permissions, tasks, or model downloads. */
+export declare class DecisionService {
+    private readonly config;
+    private readonly options;
+    private child;
+    private stopping;
+    private ready;
+    private stdout;
+    private queue;
+    private active;
+    private sequence;
+    private disposed;
+    private idleTimer;
+    private cooldownUntil;
+    private readonly rates;
+    private completed;
+    private failed;
+    constructor(config: LocalDecisionConfig | undefined, options?: DecisionServiceOptions);
+    status(): {
+        enabled: boolean;
+        supported: boolean;
+        configured: boolean;
+        state: string;
+        queued: number;
+        completed: number;
+        failed: number;
+        experimental: true;
+    };
+    evaluate(value: unknown, caller: string, signal?: AbortSignal): Promise<DecisionResult>;
+    dispose(): void;
+    private finish;
+    private clearIdle;
+    private stopWorker;
+    private failWorker;
+    private pump;
+    private startWorker;
+    private receive;
+}
+export {};

package/dist/decision-service.js

@@ -0,0 +1,230 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildChildEnv } from "./env-utils.js";
+import { DecisionError, parseDecisionRequest, parseDecisionResult } from "./decision-types.js";
+/** One bounded worker per server. It owns no sessions, permissions, tasks, or model downloads. */
+export class DecisionService {
+    config;
+    options;
+    child = null;
+    stopping = null;
+    ready = false;
+    stdout = "";
+    queue = [];
+    active = null;
+    sequence = 0;
+    disposed = false;
+    idleTimer = null;
+    cooldownUntil = 0;
+    rates = new Map();
+    completed = 0;
+    failed = 0;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.options = options;
+    }
+    status() {
+        const supported = (this.options.supported ?? (() => process.platform === "darwin" && process.arch === "arm64"))();
+        const configured = !!this.config && isAbsolute(this.config.pythonPath) && isAbsolute(this.config.modelPath)
+            && existsSync(this.config.pythonPath) && existsSync(this.config.modelPath);
+        return { enabled: this.config?.enabled === true, supported, configured,
+            state: this.disposed ? "closed" : this.stopping ? "stopping" : this.child ? this.ready ? "ready" : "loading" : "stopped",
+            queued: this.queue.length + Number(!!this.active), completed: this.completed, failed: this.failed, experimental: true };
+    }
+    evaluate(value, caller, signal) {
+        const request = parseDecisionRequest(value);
+        const status = this.status();
+        if (this.disposed || !status.enabled || !status.supported || !status.configured) {
+            throw new DecisionError("UNAVAILABLE", "本地决策未启用、平台不支持或运行环境未安装。", 503);
+        }
+        if (signal?.aborted)
+            throw new DecisionError("CANCELLED", "决策请求已取消。", 499);
+        if (Date.now() < this.cooldownUntil)
+            throw new DecisionError("COOLDOWN", "决策引擎暂不可用，请稍后重试。", 503);
+        if (this.queue.length + Number(!!this.active) >= 8)
+            throw new DecisionError("BUSY", "决策队列已满。", 503);
+        const now = Date.now();
+        for (const [key, rate] of this.rates)
+            if (now - rate.start >= 60_000)
+                this.rates.delete(key);
+        const rate = this.rates.get(caller) ?? { start: now, count: 0 };
+        if (rate.count >= 60 || (!this.rates.has(caller) && this.rates.size >= 4096)) {
+            throw new DecisionError("RATE_LIMIT", "决策调用过于频繁。", 429);
+        }
+        rate.count++;
+        this.rates.set(caller, rate);
+        this.clearIdle();
+        return new Promise((resolve, reject) => {
+            const id = ++this.sequence;
+            const cancel = (error) => {
+                const queued = this.queue.find((job) => job.id === id);
+                if (queued) {
+                    this.queue = this.queue.filter((job) => job.id !== id);
+                    this.finish(queued, error);
+                    // The first request can time out while Python is still loading, before active is set.
+                    if (!this.active && !this.queue.length)
+                        this.stopWorker();
+                }
+                else if (this.active?.id === id)
+                    this.failWorker(error);
+            };
+            const abort = () => cancel(new DecisionError("CANCELLED", "决策请求已取消。", 499));
+            const timer = setTimeout(() => cancel(new DecisionError("TIMEOUT", "决策请求超时。", 504)), this.options.timeoutMs ?? 45_000);
+            const job = { id, request, resolve, reject, timer, removeAbort: () => signal?.removeEventListener("abort", abort) };
+            this.queue.push(job);
+            signal?.addEventListener("abort", abort, { once: true });
+            if (signal?.aborted) {
+                abort();
+                return;
+            }
+            this.pump();
+        });
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.failWorker(new DecisionError("UNAVAILABLE", "决策服务已关闭。", 503));
+        this.rates.clear();
+    }
+    finish(job, error, value) {
+        clearTimeout(job.timer);
+        job.removeAbort();
+        if (error) {
+            this.failed++;
+            job.reject(error);
+        }
+        else {
+            this.completed++;
+            job.resolve(value);
+        }
+    }
+    clearIdle() {
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = null;
+    }
+    stopWorker() {
+        this.clearIdle();
+        const child = this.child;
+        this.child = null;
+        this.ready = false;
+        this.stdout = "";
+        if (child) {
+            this.stopping = child;
+            child.stdin.destroy();
+            child.kill("SIGTERM");
+            const timer = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+                child.kill("SIGKILL"); }, 1000);
+            timer.unref();
+            child.once("close", () => {
+                clearTimeout(timer);
+                if (this.stopping === child)
+                    this.stopping = null;
+                this.pump();
+            });
+        }
+    }
+    failWorker(error) {
+        const jobs = [...(this.active ? [this.active] : []), ...this.queue];
+        this.active = null;
+        this.queue = [];
+        this.stopWorker();
+        this.cooldownUntil = Date.now() + 1000;
+        for (const job of jobs)
+            this.finish(job, error);
+    }
+    pump() {
+        if (this.disposed || this.active || this.stopping)
+            return;
+        if (!this.queue.length) {
+            if (this.child && !this.idleTimer) {
+                this.idleTimer = setTimeout(() => this.stopWorker(), this.options.idleMs ?? 5 * 60_000);
+                this.idleTimer.unref();
+            }
+            return;
+        }
+        if (!this.child) {
+            this.startWorker();
+            return;
+        }
+        if (!this.ready)
+            return;
+        const job = this.queue.shift();
+        this.active = job;
+        this.child.stdin.write(`${JSON.stringify({ id: job.id, request: job.request })}\n`, (error) => {
+            if (error && this.active === job)
+                this.failWorker(new DecisionError("WORKER_FAILED", "决策引擎通信失败。", 502));
+        });
+    }
+    startWorker() {
+        const child = spawn(this.config.pythonPath, [this.options.workerPath ?? fileURLToPath(new URL("./decision-worker.py", import.meta.url)), this.config.modelPath], {
+            env: buildChildEnv(false, { HF_HUB_OFFLINE: "1", HF_HUB_DISABLE_TELEMETRY: "1", HF_HUB_DISABLE_IMPLICIT_TOKEN: "1", PYTHONUNBUFFERED: "1", PYTHONDONTWRITEBYTECODE: "1" }),
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child = child;
+        // Never reflect stderr (it can include a local path or untrusted input) into HTTP or logs.
+        child.stderr.resume();
+        child.stdin.on("error", () => { if (this.child === child)
+            this.failWorker(new DecisionError("WORKER_FAILED", "决策引擎通信失败。", 502)); });
+        child.on("error", () => { if (this.child === child)
+            this.failWorker(new DecisionError("WORKER_FAILED", "无法启动决策引擎。", 503)); });
+        child.on("exit", () => { if (this.child === child)
+            this.failWorker(new DecisionError("WORKER_FAILED", "决策引擎已退出。", 502)); });
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            if (this.child !== child)
+                return;
+            this.stdout += chunk;
+            if (Buffer.byteLength(this.stdout) > 128 * 1024) {
+                this.failWorker(new DecisionError("INVALID_RESULT", "决策引擎输出过大。", 502));
+                return;
+            }
+            while (this.stdout.includes("\n") && this.child === child) {
+                const end = this.stdout.indexOf("\n");
+                const line = this.stdout.slice(0, end);
+                this.stdout = this.stdout.slice(end + 1);
+                try {
+                    this.receive(JSON.parse(line));
+                }
+                catch {
+                    this.failWorker(new DecisionError("INVALID_RESULT", "决策引擎协议错误。", 502));
+                }
+            }
+        });
+    }
+    receive(message) {
+        if (!this.ready) {
+            if (message.type !== "ready" || message.protocol !== 1)
+                throw new Error("Unexpected ready");
+            this.ready = true;
+            this.pump();
+            return;
+        }
+        const job = this.active;
+        if (!job || message.id !== job.id)
+            throw new Error("Unexpected result");
+        const errors = {
+            CONTEXT_LIMIT: "超过模型1024 token上下文，请缩短输入；未返回截断后的判断。",
+            OPTIONS_COLLAPSED: "选项超出token预算、无法区分，请减少或缩短选项。",
+            QUESTION_LIMIT: "问题指令或选项超过模型前缀token预算，请缩短；不会静默截断。",
+            INVALID_REQUEST: "决策引擎无法处理该问题格式。",
+        };
+        if (typeof message.error === "string") {
+            if (!Object.hasOwn(errors, message.error)) {
+                this.failWorker(new DecisionError("INFERENCE_FAILED", "本地推理失败。", 502));
+                return;
+            }
+            this.active = null;
+            this.finish(job, new DecisionError(message.error, errors[message.error], 422));
+        }
+        else {
+            const result = parseDecisionResult(message.result, job.request);
+            this.active = null;
+            this.finish(job, undefined, result);
+        }
+        this.pump();
+    }
+}

package/dist/decision-skill.d.ts

@@ -0,0 +1,6 @@
+import { type SessionProvider } from "./provider-catalog.js";
+/** One managed source, three discovery locations; never edits a provider's settings or permissions. */
+export declare function installDecisionSkill(configDir: string, providers?: readonly SessionProvider[], home?: string): Promise<{
+    installed: string[];
+    providers: readonly SessionProvider[];
+}>;

package/dist/decision-skill.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { readFile, mkdir, lstat, readlink, writeFile, symlink, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { SESSION_PROVIDERS } from "./provider-catalog.js";
+const FILES = ["SKILL.md", "scripts/decide.mjs"];
+const sha = (data) => createHash("sha256").update(data).digest("hex");
+/** One managed source, three discovery locations; never edits a provider's settings or permissions. */
+export async function installDecisionSkill(configDir, providers = SESSION_PROVIDERS, home = homedir()) {
+    if (!providers.length || providers.some((provider) => !SESSION_PROVIDERS.includes(provider)))
+        throw new Error("未知CLI技能目标。");
+    const canonical = path.join(configDir, "skills", "wand-decision");
+    const source = fileURLToPath(new URL("../skills/wand-decision/", import.meta.url));
+    const targets = new Set();
+    for (const provider of providers) {
+        const directory = provider === "claude" ? ".claude" : provider === "qoder" ? ".qoder" : ".agents";
+        targets.add(path.join(home, directory, "skills", "wand-decision"));
+    }
+    // Preflight every target before touching anything; existing user content is never replaced.
+    for (const target of targets) {
+        try {
+            const info = await lstat(target);
+            if (!info.isSymbolicLink() || path.resolve(path.dirname(target), await readlink(target)) !== path.resolve(canonical)) {
+                throw new Error(`已有同名技能，保留原内容，请先手动处理：${target}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    let previous = {};
+    try {
+        previous = JSON.parse(await readFile(path.join(canonical, ".wand-managed.json"), "utf8"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const contents = await Promise.all(FILES.map(async (file) => ({ file, content: await readFile(path.join(source, file), "utf8") })));
+    for (const { file, content } of contents) {
+        try {
+            const old = await readFile(path.join(canonical, file), "utf8");
+            if (old !== content && sha(old) !== previous[file])
+                throw new Error(`技能已有用户修改，拒绝覆盖：${file}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    await mkdir(path.join(canonical, "scripts"), { recursive: true });
+    for (const { file, content } of contents)
+        await writeFile(path.join(canonical, file), content, { mode: 0o644 });
+    await writeFile(path.join(canonical, ".wand-managed.json"), JSON.stringify(Object.fromEntries(contents.map(({ file, content }) => [file, sha(content)]))), { mode: 0o600 });
+    for (const target of targets) {
+        await mkdir(path.dirname(target), { recursive: true });
+        try {
+            await symlink(canonical, target, "dir");
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        if (await realpath(target) !== await realpath(canonical))
+            throw new Error("技能链接目标校验失败。");
+    }
+    return { installed: [...targets], providers };
+}

package/dist/decision-tool.d.ts

@@ -0,0 +1,21 @@
+import type { DecisionCardSummary } from "./types.js";
+/** Presentation-only recognition of actual local-decision invocations, never an execution policy. */
+interface DecisionToolLike {
+    type?: string;
+    name?: string;
+    input?: Record<string, unknown>;
+    semantic?: {
+        kind?: string;
+    };
+}
+export declare function isDecisionToolCall(block: DecisionToolLike): boolean;
+/**
+ * 卡头副标题：结论优先（窄屏先被省略的是被判定内容，不是答案），再题数、再要点的有界拼接；
+ * 两边都缺数据时退化为模式提示，客户端因此不需要自带一套决策文案。
+ * 状态词（运行中/完成/失败）不在这里，由客户端按自己的状态源渲染。
+ */
+export declare function decisionCardSummary(input: Record<string, unknown> | undefined, result: {
+    content?: unknown;
+    is_error?: boolean;
+} | null | undefined): DecisionCardSummary;
+export {};