@co0ontty/wand 4.85.1 → 4.87.0

package/dist/web-ui/index.js

@@ -16,7 +16,9 @@ export function renderApp(configPath, page = "console", settingsAuth = "browser"
 <html lang="zh-CN"${page === "settings" ? ` data-wand-page="settings" data-wand-settings-auth="${settingsAuth}"` : ""}>
 <head>
   <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover, interactive-widget=resizes-content" />
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
+  <meta name="wand-xterm-script" content="${xtermSrc}" />
+  <meta name="wand-qrcode-script" content="${qrcodeSrc}" />
   <title>${page === "settings" ? "Wand 设置" : "Wand Console"}</title>
   <link rel="icon" type="image/svg+xml" href="${WAND_FAVICON_URL}" />
   <meta name="description" content="Local CLI Console for Vibe Coding - Manage terminal sessions from your browser" />
@@ -30,8 +32,6 @@ export function renderApp(configPath, page = "console", settingsAuth = "browser"
 <body>
   <div id="app"></div>
   <div id="overlay-root" data-wand-ui-root></div>
-<script src="${xtermSrc}"></script>
-<script src="${qrcodeSrc}"></script>
 <script src="${scriptSrc}"></script>
 </body>
 </html>`;

package/dist/web-ui/provider-identity.d.ts

@@ -1,9 +1,36 @@
 import { SESSION_PROVIDERS as PROVIDER_IDS, inferProviderFromCommand, normalizeProviderId, type SessionProvider } from "../provider-catalog.js";
-export { inferProviderFromCommand, providerCliCommand, providerDisplayName, isNativeThinkingEffort, NATIVE_THINKING_EFFORT_PATTERN, PROVIDER_LABELS, } from "../provider-catalog.js";
+export { inferProviderFromCommand, providerCliCommand, providerDisplayName, isNativeThinkingEffort, NATIVE_THINKING_EFFORT_PATTERN, PROVIDER_LABELS, WAND_AGENT_LABEL, } from "../provider-catalog.js";
 export { PROVIDER_IDS, normalizeProviderId };
 export type ProviderId = SessionProvider;
 /** 兼容旧名：浏览器层的调用点叫 inferProviderIdFromCommand。 */
 export declare const inferProviderIdFromCommand: typeof inferProviderFromCommand;
+/** 同一 provider 的不同执行路径：CLI 起外部进程，SDK 在 Wand 进程内跑（目前只有 pi 两种都有）。 */
+export type AgentToolEngine = "cli" | "sdk";
+/**
+ * 一条可选的执行工具。
+ *
+ * `pi` 与 `wand-agent` 共享同一个 provider（都是 pi），但执行方式不同：
+ * 前者起 Pi CLI 进程（结构化 JSON / PTY），后者用进程内 SDK harness。
+ * 所以 UI 上的「工具」比 provider 多一个维度，不能只拿 provider 当选项值。
+ */
+export interface AgentToolOption {
+    id: string;
+    provider: ProviderId;
+    engine?: AgentToolEngine;
+    label: string;
+    description: string;
+}
+/** Wand Agent（进程内 SDK）的选项 id；不是 provider 名，只是一个 UI 侧的稳定标识。 */
+export declare const WAND_AGENT_TOOL_ID = "wand-agent";
+/** 执行工具清单：顺序即 UI 顺序，与 provider-catalog 的 SESSION_PROVIDERS 保持一致。 */
+export declare const AGENT_TOOL_OPTIONS: readonly AgentToolOption[];
+/** 按选项 id 取执行工具；认不出来时返回 null（调用方自己决定回退）。 */
+export declare function agentToolOption(id: string | null | undefined): AgentToolOption | null;
+/**
+ * 由 provider + 引擎反推选项 id。
+ * 缺省引擎视为 CLI：历史上只有 pi 有两条路，其他 provider 只有 CLI。
+ */
+export declare function agentToolIdFor(provider: ProviderId, engine?: AgentToolEngine | null): string;
 /** 严格判断：只接受 7 个 provider 字面量，不做别名 / 大小写归一。 */
 export declare function isProviderId(value: unknown): value is ProviderId;
 export declare const CLAUDE_BRAND_COLOR = "#D97757";

package/dist/web-ui/provider-identity.js

@@ -1,10 +1,39 @@
 // Provider 的列表 / 别名 / 展示名 / 推断规则统一在 src/provider-catalog.ts（服务端共用）。
 // 这里只补充浏览器层特有的品牌 logo 与 HTML 渲染。
-import { SESSION_PROVIDERS as PROVIDER_IDS, inferProviderFromCommand, normalizeProviderId, } from "../provider-catalog.js";
-export { inferProviderFromCommand, providerCliCommand, providerDisplayName, isNativeThinkingEffort, NATIVE_THINKING_EFFORT_PATTERN, PROVIDER_LABELS, } from "../provider-catalog.js";
+import { SESSION_PROVIDERS as PROVIDER_IDS, PROVIDER_LABELS, WAND_AGENT_LABEL, inferProviderFromCommand, normalizeProviderId, } from "../provider-catalog.js";
+export { inferProviderFromCommand, providerCliCommand, providerDisplayName, isNativeThinkingEffort, NATIVE_THINKING_EFFORT_PATTERN, PROVIDER_LABELS, WAND_AGENT_LABEL, } from "../provider-catalog.js";
 export { PROVIDER_IDS, normalizeProviderId };
 /** 兼容旧名：浏览器层的调用点叫 inferProviderIdFromCommand。 */
 export const inferProviderIdFromCommand = inferProviderFromCommand;
+/** Wand Agent（进程内 SDK）的选项 id；不是 provider 名，只是一个 UI 侧的稳定标识。 */
+export const WAND_AGENT_TOOL_ID = "wand-agent";
+/** 执行工具清单：顺序即 UI 顺序，与 provider-catalog 的 SESSION_PROVIDERS 保持一致。 */
+export const AGENT_TOOL_OPTIONS = [
+    { id: "claude", provider: "claude", label: PROVIDER_LABELS.claude, description: "Claude Code" },
+    { id: "codex", provider: "codex", label: PROVIDER_LABELS.codex, description: "OpenAI Codex CLI" },
+    { id: "opencode", provider: "opencode", label: PROVIDER_LABELS.opencode, description: "OpenCode CLI" },
+    { id: "grok", provider: "grok", label: PROVIDER_LABELS.grok, description: "Grok Build CLI" },
+    { id: "qoder", provider: "qoder", label: PROVIDER_LABELS.qoder, description: "Qoder CLI" },
+    { id: "pi", provider: "pi", engine: "cli", label: PROVIDER_LABELS.pi, description: "Pi CLI：结构化 JSON 或 PTY 终端" },
+    { id: WAND_AGENT_TOOL_ID, provider: "pi", engine: "sdk", label: WAND_AGENT_LABEL,
+        description: "Wand 自带 Agent：进程内 SDK 执行，只支持结构化会话" },
+    { id: "gemini", provider: "gemini", label: PROVIDER_LABELS.gemini, description: "Gemini CLI" },
+];
+/** 按选项 id 取执行工具；认不出来时返回 null（调用方自己决定回退）。 */
+export function agentToolOption(id) {
+    if (!id)
+        return null;
+    return AGENT_TOOL_OPTIONS.find((option) => option.id === id) ?? null;
+}
+/**
+ * 由 provider + 引擎反推选项 id。
+ * 缺省引擎视为 CLI：历史上只有 pi 有两条路，其他 provider 只有 CLI。
+ */
+export function agentToolIdFor(provider, engine) {
+    if (provider === "pi" && engine === "sdk")
+        return WAND_AGENT_TOOL_ID;
+    return provider;
+}
 const PROVIDER_ID_SET = new Set(PROVIDER_IDS);
 /** 严格判断：只接受 7 个 provider 字面量，不做别名 / 大小写归一。 */
 export function isProviderId(value) {

package/dist/web-ui/session-activity.d.ts

@@ -5,6 +5,7 @@ export interface SessionActivitySource {
     readonly status?: string;
     readonly provider?: string;
     readonly ptyBusy?: boolean;
+    readonly ptyCommandRunning?: boolean;
     readonly providerCliActive?: boolean;
     readonly archived?: boolean;
     readonly permissionBlocked?: boolean;

package/dist/web-ui/session-activity.js

@@ -5,7 +5,9 @@ function isStructured(session) {
 export function ptyTurnActive(session) {
     if (!session || session.status !== "running" || isStructured(session))
         return false;
-    return session.provider && PROVIDER_CLI_IDS.has(session.provider) ? session.ptyBusy === true : true;
+    return session.provider && PROVIDER_CLI_IDS.has(session.provider)
+        ? session.ptyBusy === true
+        : session.ptyCommandRunning === true;
 }
 export function computeRunningSignal(session) {
     if (!session || session.archived) {
@@ -13,7 +15,8 @@ export function computeRunningSignal(session) {
     }
     const permissionBlocked = Boolean(session.permissionBlocked);
     const inFlight = isStructured(session) && Boolean(session.structuredState?.inFlight);
-    const ptyRunning = ptyTurnActive(session) && session.providerCliActive !== false;
+    // The launch marker describes the original provider CLI, not manual commands in a blank shell.
+    const ptyRunning = ptyTurnActive(session) && (!session.provider || session.providerCliActive !== false);
     return { active: inFlight || ptyRunning || permissionBlocked, inFlight, ptyRunning, permissionBlocked };
 }
 export function formatElapsedShort(ms) {

package/dist/web-ui/speech-audio.d.ts

@@ -0,0 +1,2 @@
+/** Encode and downsample locally so hosts need no ffmpeg/codec dependencies. */
+export declare function encodeSpeechWav(channels: readonly Float32Array[], sourceRate: number): ArrayBuffer;

package/dist/web-ui/speech-audio.js

@@ -0,0 +1,41 @@
+import { SPEECH_MAX_SECONDS, SPEECH_SAMPLE_RATE } from "../speech-types.js";
+/** Encode and downsample locally so hosts need no ffmpeg/codec dependencies. */
+export function encodeSpeechWav(channels, sourceRate) {
+    if (!channels.length || !Number.isFinite(sourceRate) || sourceRate < SPEECH_SAMPLE_RATE
+        || !channels[0]?.length || channels.some((channel) => channel.length !== channels[0].length))
+        throw new Error("麦克风音频格式无效。");
+    const frames = channels[0].length;
+    if (frames / sourceRate > SPEECH_MAX_SECONDS + 0.05)
+        throw new Error("语音最长 60 秒，请分段录音。");
+    const count = Math.min(SPEECH_SAMPLE_RATE * SPEECH_MAX_SECONDS, Math.floor(frames * SPEECH_SAMPLE_RATE / sourceRate));
+    if (count < 1600)
+        throw new Error("录音太短，请按住麦克风说话。");
+    const bytes = new ArrayBuffer(44 + count * 2);
+    const view = new DataView(bytes);
+    const ascii = (offset, value) => { for (let index = 0; index < value.length; index += 1)
+        view.setUint8(offset + index, value.charCodeAt(index)); };
+    ascii(0, "RIFF");
+    view.setUint32(4, bytes.byteLength - 8, true);
+    ascii(8, "WAVEfmt ");
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true);
+    view.setUint16(22, 1, true);
+    view.setUint32(24, SPEECH_SAMPLE_RATE, true);
+    view.setUint32(28, SPEECH_SAMPLE_RATE * 2, true);
+    view.setUint16(32, 2, true);
+    view.setUint16(34, 16, true);
+    ascii(36, "data");
+    view.setUint32(40, count * 2, true);
+    const ratio = sourceRate / SPEECH_SAMPLE_RATE;
+    for (let index = 0; index < count; index += 1) {
+        const start = Math.floor(index * ratio);
+        const end = Math.max(start + 1, Math.floor((index + 1) * ratio));
+        let sample = 0;
+        for (const channel of channels)
+            for (let source = start; source < end; source += 1)
+                sample += channel[source] ?? 0;
+        sample = Math.max(-1, Math.min(1, sample / ((end - start) * channels.length)));
+        view.setInt16(44 + index * 2, Math.round(sample < 0 ? sample * 32768 : sample * 32767), true);
+    }
+    return bytes;
+}

package/dist/web-ui/vendor-loader.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureQrCodeLibrary(): Promise<any>;
+export declare function ensureTerminalLibrary(): Promise<void>;

package/dist/web-ui/vendor-loader.js

@@ -0,0 +1,50 @@
+/** Optional browser libraries keep their versioned URLs in the server-rendered shell. */
+const pending = new Map();
+function loadVendor(name, ready) {
+    if (ready())
+        return Promise.resolve();
+    const existing = pending.get(name);
+    if (existing)
+        return existing;
+    const src = document.querySelector(`meta[name="wand-${name}-script"]`)?.content;
+    if (!src)
+        return Promise.reject(new Error("组件地址不可用，请刷新页面后重试。"));
+    const promise = new Promise((resolve, reject) => {
+        const script = document.createElement("script");
+        script.src = src;
+        script.async = true;
+        let finished = false;
+        const finish = (error) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            script.onload = null;
+            script.onerror = null;
+            if (error) {
+                script.remove();
+                reject(error);
+            }
+            else
+                resolve();
+        };
+        const timer = setTimeout(() => finish(new Error("组件加载超时，请重试。")), 20_000);
+        script.onload = () => finish(ready() ? undefined : new Error("组件加载未完成，请重试。"));
+        script.onerror = () => finish(new Error("组件加载失败，请重试。"));
+        document.head.appendChild(script);
+    }).finally(() => { if (pending.get(name) === promise)
+        pending.delete(name); });
+    pending.set(name, promise);
+    return promise;
+}
+export async function ensureQrCodeLibrary() {
+    const globals = globalThis;
+    await loadVendor("qrcode", () => typeof globals.QRCodeLib?.toCanvas === "function");
+    return globals.QRCodeLib;
+}
+export async function ensureTerminalLibrary() {
+    await loadVendor("xterm", () => {
+        const library = globalThis.XTermLib;
+        return typeof library?.Terminal === "function" && typeof library.FitAddon === "function";
+    });
+}

package/dist/ws-broadcast.js

@@ -4,7 +4,7 @@
  */
 import { WebSocket } from "ws";
 import { readSessionCookie } from "./auth.js";
-import { blockWindowMessagesForTransport, compactToolMessagesForTransport, windowMessagesForTransport } from "./message-truncator.js";
+import { blockWindowMessagesForTransport, compactToolMessagesForTransport, messageWindowByteBudget, windowMessagesForTransport } from "./message-truncator.js";
 import { boundSessionEventData, toSessionDetailDTO } from "./session-transport.js";
 import { enrichStructuredMessages } from "./structured-client-protocol.js";
 // ── Constants ──
@@ -154,6 +154,10 @@ export class WsBroadcastManager {
                         if (Number.isSafeInteger(msg.blockBudget) && msg.blockBudget > 0) {
                             client.blockBudget = Math.min(msg.blockBudget, MAX_BLOCK_BUDGET);
                         }
+                        if (Number.isSafeInteger(msg.byteBudget) && msg.byteBudget > 0) {
+                            client.byteBudget = messageWindowByteBudget(msg.byteBudget);
+                        }
+                        client.omitStructuredOutput = client.omitStructuredOutput || msg.omitStructuredOutput === true;
                         // 默认仍是历史的“切换当前会话”；分屏池显式用 mode:add 叠加订阅。
                         if (msg.mode !== "add") {
                             client.ptySubscriptions.clear();
@@ -398,7 +402,7 @@ export class WsBroadcastManager {
             ...(resync ? { resync: true } : {}),
             data: {
                 ...toSessionDetailDTO(snapshot, {
-                    output: snapshot.output,
+                    output: client.omitStructuredOutput && snapshot.sessionKind === "structured" ? "" : snapshot.output,
                     outputLimit: terminalState ? 16_000 : undefined,
                     ...windowed,
                 }),
@@ -420,7 +424,7 @@ export class WsBroadcastManager {
             messages = compactToolMessagesForTransport(messages);
         }
         if (client.blockBudget && client.blockBudget > 0) {
-            const w = blockWindowMessagesForTransport(messages, this.getCardDefaults(), client.blockBudget);
+            const w = blockWindowMessagesForTransport(messages, this.getCardDefaults(), client.blockBudget, client.byteBudget, client.byteBudget !== undefined);
             return {
                 messages: w.messages,
                 messageOffset: w.messageOffset,
@@ -484,7 +488,9 @@ export class WsBroadcastManager {
             if (client.compactTools || (client.blockBudget && client.blockBudget > 0)) {
                 return {
                     ...boundedEvent,
-                    data: { ...data, ...this.windowForClient(client, event.sessionId, rawMessages) },
+                    data: { ...data, ...this.windowForClient(client, event.sessionId, rawMessages),
+                        ...(client.omitStructuredOutput && (data?.sessionKind === "structured" || data?.structuredState)
+                            ? { output: "" } : {}) },
                 };
             }
             if (!turnWindowedEvent) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@co0ontty/wand",
-  "version": "4.85.1",
+  "version": "4.87.0",
   "description": "A web console for Claude Code, Codex, OpenCode, and other local CLI tools.",
   "type": "module",
   "bin": {
@@ -16,7 +16,9 @@
     "skills/wand-decision",
     "browser-extension",
     "scripts/install-render-binary.js",
-    "scripts/stage-render-binaries.js"
+    "scripts/stage-render-binaries.js",
+    "scripts/install-speech-runtime.js",
+    "scripts/install-laya-runtime.js"
   ],
   "preferGlobal": true,
   "scripts": {
@@ -24,6 +26,8 @@
     "build": "node scripts/check-node-version.js && rm -rf dist && node scripts/bundle-tailwind.js && node scripts/bundle-xterm.js && node scripts/bundle-qrcode.js && node scripts/bundle-browser.js && npm run generate:web-assets && tsc -p tsconfig.json && npm run build:copy-content && node scripts/check-bundle-budget.js && (npm run build:render-bin || echo '[wand] WARNING: build:render-bin failed; dist/native/ has no wand-render (run: npm run build:render-bin)' >&2) && node scripts/stamp-build-info.js && node scripts/fix-dist-permissions.js",
     "build:copy-content": "cp -r src/web-ui/content dist/web-ui/ && cp src/decision-worker.py dist/decision-worker.py && node scripts/minify-dist-content.js",
     "build:render-bin": "node scripts/stage-render-binaries.js --all",
+    "speech:install": "node scripts/install-speech-runtime.js",
+    "laya:install": "node scripts/install-laya-runtime.js",
     "build:render-native": "cargo build --release --manifest-path render/Cargo.toml -p wand-renderd",
     "build:structured-render-native": "cargo build --release --manifest-path render/Cargo.toml -p wand-structured-renderd",
     "dev": "node scripts/check-node-version.js && node scripts/bundle-tailwind.js && node scripts/bundle-xterm.js && node scripts/bundle-qrcode.js && node scripts/bundle-browser.js --development && npm run generate:web-assets && tsx src/cli.ts web",
@@ -45,7 +49,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=26.10.0"
+    "node": ">=24.21.0"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.81.0",

package/scripts/install-laya-runtime.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Explicit, isolated Apple Silicon runtime. Never installs into the user's/system Python.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { buildChildEnv, systemEnvValue } from "../dist/env-utils.js";
+
+const args = process.argv.slice(2);
+let root = path.join(os.homedir(), ".wand", "local-models", "laya"), environment, events = false;
+for (let index = 0; index < args.length; index += 1) {
+  const option = args[index];
+  if (option === "--events") events = true;
+  else if (option === "--dir" || option === "--environment") {
+    const value = args[++index];
+    if (!value || value.startsWith("--")) throw Error(`${option} requires a directory`);
+    if (option === "--dir") root = path.resolve(value); else environment = path.resolve(value);
+  } else if (option === "--help") {
+    console.log("node scripts/install-laya-runtime.js [--dir <managed model root>] [--environment <fresh venv directory>] [--events]"); process.exit(0);
+  } else throw Error(`Unknown option: ${option}`);
+}
+if (process.platform !== "darwin" || process.arch !== "arm64") throw Error("LAYA-MLX requires Apple Silicon macOS with Metal");
+environment ??= path.join(root, "environments", `laya-0.3.0-mlx-0.32.2-${process.pid}`);
+if (existsSync(environment)) throw Error("A fresh environment is required; existing Python environments are never overwritten");
+const env = buildChildEnv(false, {
+  HTTPS_PROXY: systemEnvValue("HTTPS_PROXY"), HTTP_PROXY: systemEnvValue("HTTP_PROXY"), NO_PROXY: systemEnvValue("NO_PROXY"),
+  PIP_DISABLE_PIP_VERSION_CHECK: "1", PIP_NO_INPUT: "1", HF_HUB_DISABLE_TELEMETRY: "1", HF_HUB_DISABLE_IMPLICIT_TOKEN: "1",
+});
+function progress(phase, message) {
+  if (events) console.log("[wand-model] " + JSON.stringify({ phase, message })); else console.log(message);
+}
+function run(executable, arguments_, quiet = false) {
+  const result = spawnSync(executable, arguments_, { env, shell: false, stdio: quiet || events ? "pipe" : "inherit", encoding: "utf8", windowsHide: true, maxBuffer: 4 * 1024 * 1024 });
+  if (result.error || result.status !== 0) throw Error("LAYA runtime setup failed; check Python >=3.11, network access to PyPI, free disk space and Metal support");
+  return result.stdout?.trim();
+}
+let completed = false;
+try {
+  progress("runtime", "检查 Python 3.11+ 与 Apple Silicon 环境");
+  const explicit = systemEnvValue("WAND_LAYA_PYTHON_BIN");
+  if (explicit && !path.isAbsolute(explicit)) throw Error("WAND_LAYA_PYTHON_BIN must be an absolute trusted path");
+  const candidates = explicit ? [explicit] : ["python3.13", "python3.12", "python3.11", "python3"];
+  const python = candidates.find(candidate => {
+    const probe = spawnSync(candidate, ["--version"], { env, shell: false, encoding: "utf8", timeout: 10000 });
+    const version = /Python (\d+)\.(\d+)/.exec(probe.stdout || "");
+    return probe.status === 0 && version && Number(version[1]) === 3 && Number(version[2]) >= 11;
+  });
+  if (!python) throw Error("Python 3.11+ is required; install it or set trusted WAND_LAYA_PYTHON_BIN");
+  await mkdir(path.dirname(environment), { recursive: true, mode: 0o700 });
+  run(python, ["-m", "venv", environment]);
+  const executable = path.join(environment, "bin", "python");
+  progress("runtime", "在独立环境安装固定 LAYA 0.3.0 / MLX 0.32.2 依赖");
+  run(executable, ["-m", "pip", "--isolated", "install", "--index-url", "https://pypi.org/simple", "--only-binary=:all:",
+    "laya-mlx==0.3.0", "mlx==0.32.2", "huggingface-hub==1.33.0"]);
+  progress("verifying", "校验运行时与 Metal 能力");
+  run(executable, ["-c", "import importlib.metadata as m; import mlx.core as mx; import laya_mlx; assert m.version('laya-mlx') == '0.3.0'; assert m.version('mlx') == '0.32.2'; assert mx.metal.is_available()"], true);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const receipt = path.join(root, "runtime.json"), partial = receipt + `.${process.pid}.part`;
+  const { rename } = await import("node:fs/promises");
+  await writeFile(partial, JSON.stringify({ pythonPath: executable, layaVersion: "0.3.0", mlxVersion: "0.32.2", platform: process.platform, arch: process.arch }) + "\n", { mode: 0o600 });
+  await rename(partial, receipt);
+  completed = true;
+  progress("completed", "LAYA 独立运行时已安装，未修改系统 Python、模型启用状态或技能授权");
+} finally {
+  if (!completed) await rm(environment, { recursive: true, force: true }).catch(() => {});
+}

package/scripts/install-speech-runtime.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Explicit host-side installation; admin model setup may launch this fixed script, never arbitrary HTTP commands.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { cp, mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { buildChildEnv } from "../dist/env-utils.js";
+
+const SOURCE_COMMIT = "2eeeba56e9edd762b4b38467bab96c2517163158"; // whisper.cpp v1.8.3
+const args = process.argv.slice(2);
+let backend = "auto";
+let root = path.join(os.homedir(), ".wand", "speech");
+let workDirectory;
+let events = false;
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === "--backend") backend = args[++i];
+  else if (args[i] === "--events") events = true;
+  else if (args[i] === "--work-dir") {
+    const directory = args[++i];
+    if (!directory || directory.startsWith("--")) throw new Error("--work-dir requires a directory");
+    workDirectory = path.resolve(directory);
+  }
+  else if (args[i] === "--dir") {
+    const directory = args[++i];
+    if (!directory || directory.startsWith("--")) throw new Error("--dir requires an installation directory");
+    root = path.resolve(directory);
+  }
+  else if (args[i] === "--help") {
+    console.log("node scripts/install-speech-runtime.js [--backend auto|cpu|metal|cuda] [--dir ~/.wand/speech]");
+    process.exit(0);
+  } else throw new Error(`Unknown option: ${args[i]}`);
+}
+if (!["auto", "cpu", "metal", "cuda"].includes(backend)) throw new Error("Invalid backend");
+if (!["darwin", "linux", "win32"].includes(process.platform)) throw new Error("Supported hosts: macOS, Linux, Windows");
+if (backend === "auto") backend = process.platform === "darwin" ? "metal" : "cpu";
+if (backend === "metal" && process.platform !== "darwin") throw new Error("Metal requires macOS");
+
+function progress(phase, message) {
+  if (events) console.log("[wand-model] " + JSON.stringify({ phase, message })); else console.log(message);
+}
+function run(command, arguments_, cwd, quiet = false) {
+  const result = spawnSync(command, arguments_, { cwd, env: buildChildEnv(true), shell: false, stdio: quiet || events ? "pipe" : "inherit", encoding: "utf8", windowsHide: true });
+  if (result.error || result.status !== 0) throw new Error(`${command} failed: install Git, CMake and a C++ toolchain first (CUDA also needs its toolkit)`);
+  return result.stdout?.trim();
+}
+const work = workDirectory ?? await mkdtemp(path.join(os.tmpdir(), "wand-whisper-build-"));
+if (workDirectory) await mkdir(workDirectory, { recursive: true, mode: 0o700 });
+const staging = path.join(root, `bin-staging-${process.pid}`);
+const bin = path.join(root, "bin");
+const backup = path.join(root, `bin-previous-${process.pid}`);
+try {
+  progress("runtime", "准备固定 whisper.cpp v1.8.3 源码");
+  run("git", ["init", work], work);
+  run("git", ["remote", "add", "origin", "https://github.com/ggml-org/whisper.cpp.git"], work);
+  run("git", ["fetch", "--depth", "1", "origin", SOURCE_COMMIT], work);
+  run("git", ["checkout", "--detach", "FETCH_HEAD"], work);
+  if (run("git", ["rev-parse", "HEAD"], work, true) !== SOURCE_COMMIT) throw new Error("Source revision mismatch");
+  progress("runtime", `配置 ${backend.toUpperCase()} 运行时与编译工具链`);
+  run("cmake", ["-S", work, "-B", path.join(work, "build"), "-DCMAKE_BUILD_TYPE=Release",
+    "-DBUILD_SHARED_LIBS=OFF", "-DWHISPER_BUILD_TESTS=OFF", "-DWHISPER_CURL=OFF", "-DGGML_NATIVE=OFF",
+    `-DGGML_METAL=${backend === "metal" ? "ON" : "OFF"}`, "-DGGML_METAL_EMBED_LIBRARY=ON",
+    `-DGGML_CUDA=${backend === "cuda" ? "ON" : "OFF"}`], work);
+  progress("runtime", "编译 whisper.cpp，仅安装可选语音组件");
+  run("cmake", ["--build", path.join(work, "build"), "--config", "Release", "--target", "whisper-cli", "-j", String(Math.min(8, os.availableParallelism()))], work);
+  const name = process.platform === "win32" ? "whisper-cli.exe" : "whisper-cli";
+  const candidates = [path.join(work, "build", "bin", "Release"), path.join(work, "build", "bin")];
+  const built = candidates.find((directory) => existsSync(path.join(directory, name)));
+  if (!built) throw new Error("whisper-cli was not produced");
+  progress("verifying", "校验语音运行时可执行文件");
+  run(path.join(built, name), ["--help"], work, true);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await cp(built, staging, { recursive: true });
+  if (existsSync(bin)) await rename(bin, backup);
+  try { await rename(staging, bin); } catch (error) { if (existsSync(backup)) await rename(backup, bin); throw error; }
+  await writeFile(path.join(root, "runtime.json"), JSON.stringify({ version: "1.8.3", sourceCommit: SOURCE_COMMIT, backend, platform: process.platform, arch: process.arch }, null, 2) + "\n", { mode: 0o600 });
+  await rm(backup, { recursive: true, force: true });
+  progress("completed", `whisper.cpp v1.8.3 (${backend}) 已安装；未改变模型启用状态`);
+} finally {
+  await rm(work, { recursive: true, force: true });
+  await rm(staging, { recursive: true, force: true });
+}