@co0ontty/wand 4.63.0 → 4.64.0-beta.g3402a64

package/dist/build-info.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 构建信息共享类型：`dist/build-info.json` 由 scripts/stamp-build-info.js 在打包时写入，
+ * server 组合根、设置路由、更新路由都消费同一份数据，避免各自再定义一遍形状。
+ */
+/** 构建信息中除版本号外的字段。 */
+export interface BuildInfo {
+    commit: string | null;
+    builtAt: string | null;
+    channel: string | null;
+}
+/** 服务端进程持有的完整构建信息。 */
+export interface WandBuildInfo extends BuildInfo {
+    version: string | null;
+}
+/** API 展示用的 build 载荷：统一补 7 位短 commit。 */
+export declare function buildInfoPayload(buildInfo: BuildInfo): BuildInfo & {
+    shortCommit: string | null;
+};

package/dist/build-info.js

@@ -0,0 +1,13 @@
+/**
+ * 构建信息共享类型：`dist/build-info.json` 由 scripts/stamp-build-info.js 在打包时写入，
+ * server 组合根、设置路由、更新路由都消费同一份数据，避免各自再定义一遍形状。
+ */
+/** API 展示用的 build 载荷：统一补 7 位短 commit。 */
+export function buildInfoPayload(buildInfo) {
+    return {
+        commit: buildInfo.commit,
+        shortCommit: buildInfo.commit ? buildInfo.commit.slice(0, 7) : null,
+        builtAt: buildInfo.builtAt,
+        channel: buildInfo.channel,
+    };
+}

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "commit": "680b91217f6bded493eba4b178d5b6236b8065cb",
-  "builtAt": "2026-09-14T15:09:11.803Z",
-  "version": "4.63.0",
-  "channel": "stable"
+  "commit": "3402a645acc2941d21b168b41577424bf7416056",
+  "builtAt": "2026-09-15T11:50:29.917Z",
+  "version": "4.64.0-beta.g3402a64",
+  "channel": "beta"
 }

package/dist/config.js

@@ -6,13 +6,8 @@ import path from "node:path";
 import process from "node:process";
 import { isRunningAsRoot } from "./env-utils.js";
 import { normalizeSystemAiConfig, systemAiProfiles } from "./system-ai.js";
-function isThinkingEffort(value) {
-    return value === "off"
-        || value === "standard"
-        || value === "deep"
-        || value === "max"
-        || (typeof value === "string" && /^codex:[a-z0-9][a-z0-9_-]{0,31}$/.test(value));
-}
+import { isSessionProvider } from "./session-provider.js";
+import { isThinkingEffort } from "./structured-provider-common.js";
 const DEFAULT_CONFIG_DIR = ".wand";
 const DEFAULT_CONFIG_FILE = "config.json";
 /**
@@ -313,7 +308,7 @@ export function applyStoragePreferences(config, storage) {
     const defaults = defaultConfig();
     if (storage.hasPreference(preferenceStorageKey("defaultProvider"))) {
         const v = storage.getPreference(preferenceStorageKey("defaultProvider"), defaults.defaultProvider ?? "claude");
-        if (v === "claude" || v === "codex" || v === "opencode" || v === "grok" || v === "qoder" || v === "pi")
+        if (isSessionProvider(v))
             config.defaultProvider = v;
     }
     if (storage.hasPreference(preferenceStorageKey("defaultSessionKind"))) {
@@ -416,8 +411,8 @@ export function writePreferenceToStorage(config, storage, key, value, options =
     const dbKey = preferenceStorageKey(key);
     switch (key) {
         case "defaultProvider": {
-            if (value !== "claude" && value !== "codex" && value !== "opencode" && value !== "grok" && value !== "qoder" && value !== "pi")
-                throw new Error(`无效 Provider: ${value}`);
+            if (!isSessionProvider(value))
+                throw new Error(`无效 Provider: ${String(value)}`);
             storage.setPreference(dbKey, value);
             config.defaultProvider = value;
             break;
@@ -743,7 +738,7 @@ function mergeWithDefaults(input) {
         macos: normalizeMacosDmgConfig(input.macos) ?? defaults.macos,
         ios: normalizeIosIpaConfig(input.ios) ?? defaults.ios,
         cardDefaults: normalizeCardDefaults(input.cardDefaults),
-        defaultProvider: input.defaultProvider === "codex" || input.defaultProvider === "opencode" || input.defaultProvider === "grok" || input.defaultProvider === "qoder" || input.defaultProvider === "pi" ? input.defaultProvider : "claude",
+        defaultProvider: isSessionProvider(input.defaultProvider) ? input.defaultProvider : "claude",
         defaultSessionKind: input.defaultSessionKind === "pty" ? "pty" : "structured",
         defaultTaskWorktree: typeof input.defaultTaskWorktree === "boolean" ? input.defaultTaskWorktree : defaults.defaultTaskWorktree,
         defaultModel: typeof input.defaultModel === "string" ? input.defaultModel.trim() : defaults.defaultModel,

package/dist/env-utils.d.ts

@@ -1,3 +1,8 @@
+/** 子进程 env：显式传入 env 优先，否则按 inheritEnv 生成白名单环境。 */
+export declare function resolveChildEnv(options: {
+    env?: NodeJS.ProcessEnv;
+    inheritEnv?: boolean;
+}): NodeJS.ProcessEnv;
 /** 是否以 root 身份运行（uid 或 euid 为 0）。供 PTY runner 与 structured runner 共用。 */
 export declare function isRunningAsRoot(): boolean;
 /**

package/dist/env-utils.js

@@ -19,6 +19,10 @@ const MINIMAL_ENV_KEYS = [
     "TEMP",
     "PWD",
 ];
+/** 子进程 env：显式传入 env 优先，否则按 inheritEnv 生成白名单环境。 */
+export function resolveChildEnv(options) {
+    return options.env ?? buildChildEnv(options.inheritEnv !== false);
+}
 /** 是否以 root 身份运行（uid 或 euid 为 0）。供 PTY runner 与 structured runner 共用。 */
 export function isRunningAsRoot() {
     return process.getuid?.() === 0 || process.geteuid?.() === 0;

package/dist/git-quick-commit.js

@@ -3,8 +3,13 @@ import { spawn } from "node:child_process";
 import { ClaudeRunError, runClaudePrint } from "./claude-sdk-runner.js";
 import { callSystemAiTextWithFallback } from "./system-ai.js";
 import { buildChildEnv } from "./env-utils.js";
+import { isSessionProvider } from "./session-provider.js";
 import { runGitAsync as runGitAsyncBase, runGitRawAsync as runGitRawAsyncBase, getGitErrorMessage, } from "./git-utils.js";
 import { thinkingEffortToClaudeCliEffort, thinkingEffortToCodexReasoningEffort, thinkingEffortToGrokEffort, thinkingEffortToOpenCodeVariant, thinkingEffortToQoderEffort, thinkingEffortToPiLevel, } from "./structured-provider-common.js";
+/** provider 缺省值：无法识别时回落到 Claude。 */
+function defaultProvider(provider) {
+    return isSessionProvider(provider) ? provider : "claude";
+}
 const GIT_TIMEOUT_MS = 1500;
 const GIT_PUSH_TIMEOUT_MS = 30_000;
 const MAX_FILE_ENTRIES = 200;
@@ -301,15 +306,6 @@ async function callClaudeText(prompt, cwd, language, opts) {
         throw error;
     }
 }
-function normalizeProvider(provider) {
-    return provider === "codex"
-        || provider === "opencode"
-        || provider === "grok"
-        || provider === "qoder"
-        || provider === "pi"
-        ? provider
-        : "claude";
-}
 function stripFences(raw) {
     return raw.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
 }
@@ -570,7 +566,7 @@ async function callPiText(prompt, cwd, opts) {
     return text;
 }
 async function callCliAiText(prompt, cwd, language, opts) {
-    const provider = normalizeProvider(opts.provider);
+    const provider = defaultProvider(opts.provider);
     if (provider === "codex") {
         return callCodexText(prompt, cwd, opts);
     }
@@ -1190,7 +1186,7 @@ async function runQuickCommitFallbackCli(opts, priorError) {
     await assertGitWorkTreeAsync(opts.cwd);
     const beforeHead = await getHead(opts.cwd);
     const prompt = buildFallbackPrompt(opts, priorError);
-    const provider = normalizeProvider(opts.provider);
+    const provider = defaultProvider(opts.provider);
     if (provider === "codex") {
         const args = ["exec", "--ephemeral", "--json", "--color", "never", "--skip-git-repo-check", "--dangerously-bypass-approvals-and-sandbox"];
         const model = opts.model?.trim();

package/dist/ios-ota.js

@@ -1,17 +1,18 @@
 import { open } from "node:fs/promises";
 import { inflateRawSync } from "node:zlib";
+import { firstHeaderListValue, forwardedParam, normalizeProtocol } from "./server-request.js";
 const DEFAULT_BUNDLE_ID = "com.wand.app";
 const DEFAULT_TITLE = "Wand";
 export function publicOriginFromRequest(req) {
-    const forwardedProto = firstHeader(req.headers["x-forwarded-proto"])
-        ?? forwardedParam(firstHeader(req.headers.forwarded), "proto");
+    const forwardedProto = firstHeaderListValue(req.headers["x-forwarded-proto"])
+        ?? forwardedParam(firstHeaderListValue(req.headers.forwarded), "proto");
     const proto = normalizeProtocol(forwardedProto)
-        ?? (firstHeader(req.headers["x-forwarded-ssl"])?.toLowerCase() === "on" ? "https" : undefined)
-        ?? (firstHeader(req.headers["x-forwarded-scheme"])?.toLowerCase() === "https" ? "https" : undefined)
+        ?? (firstHeaderListValue(req.headers["x-forwarded-ssl"])?.toLowerCase() === "on" ? "https" : undefined)
+        ?? (firstHeaderListValue(req.headers["x-forwarded-scheme"])?.toLowerCase() === "https" ? "https" : undefined)
         ?? normalizeProtocol(req.protocol);
-    const host = firstHeader(req.headers["x-forwarded-host"])
-        ?? forwardedParam(firstHeader(req.headers.forwarded), "host")
-        ?? firstHeader(req.headers.host);
+    const host = firstHeaderListValue(req.headers["x-forwarded-host"])
+        ?? forwardedParam(firstHeaderListValue(req.headers.forwarded), "host")
+        ?? firstHeaderListValue(req.headers.host);
     if (!proto || !host)
         return null;
     return `${proto}://${host}`;
@@ -381,28 +382,6 @@ function dictEntries(entries) {
         `</dict>`,
     ].join("\n");
 }
-function firstHeader(value) {
-    const raw = Array.isArray(value) ? value[0] : value;
-    return raw?.split(",")[0]?.trim();
-}
-function forwardedParam(header, key) {
-    if (!header)
-        return undefined;
-    const target = `${key}=`;
-    for (const part of header.split(";")) {
-        const trimmed = part.trim();
-        if (!trimmed.toLowerCase().startsWith(target))
-            continue;
-        return trimmed.slice(target.length).replace(/^"|"$/g, "");
-    }
-    return undefined;
-}
-function normalizeProtocol(value) {
-    const proto = value?.trim().toLowerCase();
-    if (proto === "http" || proto === "https")
-        return proto;
-    return undefined;
-}
 function stringValue(value) {
     if (typeof value === "string" && value.trim())
         return value.trim();

package/dist/layout-tree.d.ts

@@ -0,0 +1,6 @@
+import type { LayoutNode } from "./types.js";
+/**
+ * 取布局树中最左上角可用的 tab id：pane 优先用它记住的 active，
+ * 否则取第一个 tab；split 递归左侧再右侧。
+ */
+export declare function firstLayoutTabId(node: LayoutNode): string | undefined;

package/dist/layout-tree.js

@@ -0,0 +1,9 @@
+/**
+ * 取布局树中最左上角可用的 tab id：pane 优先用它记住的 active，
+ * 否则取第一个 tab；split 递归左侧再右侧。
+ */
+export function firstLayoutTabId(node) {
+    if (node.type === "pane")
+        return node.tabs[node.active]?.id ?? node.tabs[0]?.id;
+    return firstLayoutTabId(node.children[0]) ?? firstLayoutTabId(node.children[1]);
+}

package/dist/missions.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync, statSync } from "node:fs";
 import path from "node:path";
 import { buildMissionDiff } from "./mission-diff.js";
-const PROVIDERS = new Set(["claude", "codex", "opencode", "grok", "qoder", "pi"]);
+import { isSessionProvider } from "./session-provider.js";
 const MAX_ATTEMPTS = 6;
 function nowIso() {
     return new Date().toISOString();
@@ -143,7 +143,7 @@ export class Missions {
         if (!existsSync(cwd) || !statSync(cwd).isDirectory())
             throw new Error("任务工作目录不存在。");
         const providers = [...new Set(input.providers ?? [])];
-        if (providers.length === 0 || providers.length > MAX_ATTEMPTS || providers.some((provider) => !PROVIDERS.has(provider))) {
+        if (providers.length === 0 || providers.length > MAX_ATTEMPTS || providers.some((provider) => !isSessionProvider(provider))) {
             throw new Error(`请选择 1-${MAX_ATTEMPTS} 个有效 provider。`);
         }
         const createdAt = nowIso();

package/dist/models.js

@@ -2,7 +2,7 @@ import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { promisify } from "node:util";
 import Anthropic from "@anthropic-ai/sdk";
-import { buildChildEnv } from "./env-utils.js";
+import { resolveChildEnv } from "./env-utils.js";
 import { extractSemver } from "./version-utils.js";
 const execFileAsync = promisify(execFile);
 const CLAUDE_VERIFICATION_CACHE_KEY = "claude-model-verifications-v1";
@@ -85,9 +85,6 @@ function defaultCommandRunner(file, args, options) {
         maxBuffer: 1024 * 1024,
     }).then(({ stdout, stderr }) => ({ stdout: String(stdout), stderr: String(stderr) }));
 }
-function resolveProbeEnv(options) {
-    return options.env ?? buildChildEnv(options.inheritEnv !== false);
-}
 function normalizeClaudeModelId(value) {
     if (typeof value !== "string")
         return null;
@@ -704,7 +701,7 @@ function savePersistedModelCatalog(storage, cache, revision) {
 }
 async function discoverModelCache(options, previous) {
     const now = options.now?.() ?? new Date();
-    const env = resolveProbeEnv(options);
+    const env = resolveChildEnv(options);
     const runner = options.commandRunner ?? defaultCommandRunner;
     const [claudeVersionProbe, codexProbe, opencodeProbe, grokProbe, qoderProbe, piProbe, apiProbe] = await Promise.all([
         probeClaudeVersion(runner, env),

package/dist/path-repair.js

@@ -1,12 +1,13 @@
 import { existsSync, readdirSync } from "node:fs";
 import { compareSemver } from "./version-utils.js";
 import { getErrorMessage } from "./error-utils.js";
+import { providerCliCommand, SESSION_PROVIDERS } from "./session-provider.js";
 import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { spawn, spawnSync } from "node:child_process";
 /** 关键的 CLI 工具，会被诊断输出。 */
-const PROBE_COMMANDS = ["claude", "codex", "opencode", "grok", "qodercli", "pi"];
+const PROBE_COMMANDS = SESSION_PROVIDERS.map(providerCliCommand);
 const DEEP_PROBE_TIMEOUT_MS = 4000;
 /**
  * 构造候选 bin 目录列表（按优先级，前面的更可信）。

package/dist/process-manager.js

@@ -19,23 +19,11 @@ import { getErrorMessage } from "./error-utils.js";
 import { describePtySpawnFailure } from "./ensure-node-pty-helper.js";
 import { resolveSystemAiContext } from "./session-ai-context.js";
 import { resolveSessionCwd } from "./session-cwd.js";
+import { inferProviderFromCommand } from "./session-provider.js";
 import { PtyTerminalState } from "./pty-terminal-state.js";
 import { buildPtyShellLaunchPlan, PtyCliExitMarker } from "./pty-shell-launch.js";
 import { InProcessTerminalHost, } from "./terminal-host.js";
 import { ProviderHistoryScanner, } from "./provider-history-scanner.js";
-function resolveProviderFromCommand(command) {
-    if (/^(?:claude|npx\s+claude|[^\s]+\/claude)(?:\s|$)/.test(command.trim()))
-        return "claude";
-    if (/^codex\b/.test(command.trim()))
-        return "codex";
-    if (/^opencode\b/.test(command.trim()))
-        return "opencode";
-    if (/^grok\b/.test(command.trim()))
-        return "grok";
-    if (/^pi\b/.test(command.trim()))
-        return "pi";
-    return /^qodercli\b/.test(command.trim()) ? "qoder" : undefined;
-}
 /**
  * Tokenize the restricted shell-command subset accepted by the command
  * allowlist. Commands still run through a login shell, so accepting raw string
@@ -567,7 +555,7 @@ export class ProcessManager extends EventEmitter {
                 continue;
             }
             this.lastPersistedMessageState.set(snapshot.id, getPersistedMessageState(snapshot.messages ?? []));
-            const provider = snapshot.provider ?? resolveProviderFromCommand(snapshot.command);
+            const provider = snapshot.provider ?? inferProviderFromCommand(snapshot.command);
             const isClaudeCmd = provider === "claude";
             const isCodexCmd = provider === "codex";
             const isOpenCodeCmd = provider === "opencode";
@@ -1004,7 +992,7 @@ export class ProcessManager extends EventEmitter {
         const resolvedCwd = worktreeSetup?.cwd ?? baseCwd;
         const provider = opts?.interactiveShell
             ? undefined
-            : opts?.provider ?? resolveProviderFromCommand(command);
+            : opts?.provider ?? inferProviderFromCommand(command);
         const effectiveMode = provider === "codex" ? "full-access" : mode;
         const isClaudeProvider = provider === "claude";
         const selectedModel = opts?.model?.trim() || undefined;
@@ -2429,11 +2417,13 @@ export class ProcessManager extends EventEmitter {
             if (trimmedModel && trimmedModel !== "default" && !/--model(?:\s|=)/.test(result)) {
                 result += ` --model '${trimmedModel.replace(/'/g, "'\\''")}'`;
             }
-            if ((mode === "managed" || mode === "full-access") && !/--(?:yolo|dangerously-skip-permissions|permission-mode)(?:\s|=|$)/.test(result)) {
-                result += " --permission-mode bypass_permissions";
-            }
-            else if (mode === "auto-edit" && !/--permission-mode(?:\s|=)/.test(result)) {
-                result += " --permission-mode accept_edits";
+            // Qoder 默认以 yolo（bypass_permissions）启动：PTY 与结构化 runner 都没有运行时
+            // 权限桥，保持 Qoder 自身确认会让会话卡在 TUI 弹窗或直接拒绝工具调用。只有显式
+            // 选择 auto-edit 时降级为 accept_edits；命令行已带权限参数时保持原样。
+            if (!/--(?:yolo|dangerously-skip-permissions|permission-mode)(?:\s|=|$)/.test(result)) {
+                result += mode === "auto-edit"
+                    ? " --permission-mode accept_edits"
+                    : " --permission-mode bypass_permissions";
             }
             return result;
         }

package/dist/provider-cli-updater.js

@@ -2,7 +2,7 @@ import { execFile } from "node:child_process";
 import { realpathSync } from "node:fs";
 import process from "node:process";
 import { promisify } from "node:util";
-import { buildChildEnv } from "./env-utils.js";
+import { resolveChildEnv } from "./env-utils.js";
 import { getErrorMessage } from "./error-utils.js";
 import { whichSync } from "./path-repair.js";
 import { compareSemver, extractSemver } from "./version-utils.js";
@@ -53,13 +53,10 @@ const PROVIDER_CLI_SPECS = [
         updateArgs: ["update", "self"],
     },
 ];
-function childEnv(options) {
-    return options.env ?? buildChildEnv(options.inheritEnv !== false);
-}
 async function runCommand(command, args, timeout, options) {
     const { stdout, stderr } = await execFileAsync(command, args, {
         timeout,
-        env: childEnv(options),
+        env: resolveChildEnv(options),
         maxBuffer: MAX_BUFFER,
     });
     return { stdout: String(stdout ?? ""), stderr: String(stderr ?? "") };
@@ -95,7 +92,7 @@ export function providerCliUpdateAvailable(currentVersion, latestVersion) {
     return compareSemver(latestVersion, currentVersion) > 0;
 }
 async function readInstalledVersion(spec, options) {
-    const env = childEnv(options);
+    const env = resolveChildEnv(options);
     const executable = whichSync(spec.command, { env, timeoutMs: options.versionTimeoutMs ?? VERSION_TIMEOUT_MS });
     if (!executable)
         return { executable: null, version: null };

package/dist/pty-shell-launch.js

@@ -1,12 +1,10 @@
 import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
+import { shellQuote } from "./shell-quote.js";
 const CLI_EXIT_MARKER_START = "\x1eWAND_CLI_EXIT:";
 const CLI_EXIT_MARKER_END = "\x1f";
 const POSIX_SHELLS = new Set(["ash", "bash", "dash", "ksh", "ksh93", "mksh", "sh", "zsh"]);
-function quotePosixShell(value) {
-    return `'${value.replace(/'/g, `'\\''`)}'`;
-}
 function isKnownPosixShell(shell) {
     return POSIX_SHELLS.has(path.basename(shell).toLowerCase());
 }
@@ -20,7 +18,7 @@ function isKnownPosixShell(shell) {
  * persisted `print -s`, avoiding duplicate entries.
  */
 function buildShellHistoryRegistration(command, shell) {
-    const quotedCommand = quotePosixShell(command);
+    const quotedCommand = shellQuote(command);
     switch (path.basename(shell).toLowerCase()) {
         case "zsh":
             return [
@@ -114,7 +112,7 @@ function buildPosixProviderShellCommand(command, shell, marker) {
         buildTerminalRestoreCommand(),
         // -i forces an interactive prompt even if tty detection is confused after a
         // TUI teardown; -l matches Terminal.app / iTerm login-shell startup files.
-        `exec ${quotePosixShell(shell)} -il`,
+        `exec ${shellQuote(shell)} -il`,
     ].join("; ");
 }
 /**

package/dist/server-app-connect.js

@@ -11,7 +11,7 @@ import os from "node:os";
 import path from "node:path";
 import { resolveConfigDir } from "./config.js";
 import { normalizePublicOrigin } from "./ios-ota.js";
-import { firstQueryStringValue, firstHeaderValue, firstHeaderListValue } from "./server-request.js";
+import { firstHeaderListValue, firstHeaderValue, firstQueryStringValue, forwardedParam, normalizeProtocol, } from "./server-request.js";
 // ── App 连接码 ──
 //
 // 连接码里的 token 是密码派生的（HMAC(password, appSecret)），兼容既有连接码；
@@ -27,45 +27,16 @@ export function encodeConnectCode(url, token) {
     return Buffer.from(`${url}#${token}`).toString("base64");
 }
 // ── 转发头解析 ──
-function unquoteHeaderValue(value) {
-    const trimmed = value.trim();
-    if (trimmed.length >= 2 && trimmed.startsWith("\"") && trimmed.endsWith("\"")) {
-        return trimmed.slice(1, -1);
-    }
-    return trimmed;
-}
-function getForwardedParam(req, key) {
-    const forwarded = firstHeaderListValue(req.headers.forwarded);
-    if (!forwarded)
-        return undefined;
-    const targetKey = key.toLowerCase();
-    for (const part of forwarded.split(";")) {
-        const eqIdx = part.indexOf("=");
-        if (eqIdx < 1)
-            continue;
-        const partKey = part.slice(0, eqIdx).trim().toLowerCase();
-        if (partKey !== targetKey)
-            continue;
-        return unquoteHeaderValue(part.slice(eqIdx + 1));
-    }
-    return undefined;
-}
-function normalizePublicProtocol(value) {
-    const proto = value?.trim().toLowerCase();
-    if (proto === "http" || proto === "https")
-        return proto;
-    return undefined;
-}
 function getPublicRequestProtocol(req, fallback) {
-    return (normalizePublicProtocol(firstHeaderListValue(req.headers["x-forwarded-proto"]))
-        ?? normalizePublicProtocol(getForwardedParam(req, "proto"))
+    return (normalizeProtocol(firstHeaderListValue(req.headers["x-forwarded-proto"]))
+        ?? normalizeProtocol(forwardedParam(firstHeaderListValue(req.headers.forwarded), "proto"))
         ?? (firstHeaderListValue(req.headers["x-forwarded-ssl"])?.toLowerCase() === "on" ? "https" : undefined)
         ?? (firstHeaderListValue(req.headers["x-forwarded-scheme"])?.toLowerCase() === "https" ? "https" : undefined)
         ?? fallback);
 }
 function getPublicRequestHost(req, config) {
     return (firstHeaderListValue(req.headers["x-forwarded-host"])
-        ?? getForwardedParam(req, "host")
+        ?? forwardedParam(firstHeaderListValue(req.headers.forwarded), "host")
         ?? req.headers.host
         ?? `${config.host}:${config.port}`);
 }
@@ -163,26 +134,20 @@ export function appTokenLoginPayload(req, config, useHttps, password) {
 function isExternalAvatarSource(value) {
     return /^(https?:|data:)/i.test(value);
 }
-function normalizePersonaName(value) {
-    if (typeof value !== "string")
-        return undefined;
-    const trimmed = value.trim();
-    return trimmed || undefined;
-}
-function normalizePersonaAvatar(value) {
+/** persona 的 name / avatar 都是「可选非空字符串」：空白与非法类型都当未设置。 */
+function normalizeOptionalText(value) {
     if (typeof value !== "string")
         return undefined;
-    const trimmed = value.trim();
-    return trimmed || undefined;
+    return value.trim() || undefined;
 }
 export function resolveStructuredChatPersona(config) {
     const persona = config.structuredChatPersona;
     if (!persona)
         return undefined;
-    const userName = normalizePersonaName(persona.user?.name);
-    const userAvatar = normalizePersonaAvatar(persona.user?.avatar);
-    const assistantName = normalizePersonaName(persona.assistant?.name);
-    const assistantAvatar = normalizePersonaAvatar(persona.assistant?.avatar);
+    const userName = normalizeOptionalText(persona.user?.name);
+    const userAvatar = normalizeOptionalText(persona.user?.avatar);
+    const assistantName = normalizeOptionalText(persona.assistant?.name);
+    const assistantAvatar = normalizeOptionalText(persona.assistant?.avatar);
     if (!userName && !userAvatar && !assistantName && !assistantAvatar) {
         return undefined;
     }

package/dist/server-github-routes.js

@@ -1,14 +1,15 @@
 import { asyncRoute } from "./express-async.js";
 import { connectGithub, getGithubConnectorStatus, githubRequest, } from "./github-connector.js";
-import { bodyObject, integerQuery, requiredString, sendRouteError, stringQuery } from "./server-request.js";
+import { bodyObject, integerQuery, requiredString, sendRouteError, text } from "./server-request.js";
 function githubListQuery(reqQuery, defaults = {}) {
     const query = new URLSearchParams();
     if (defaults.state)
-        query.set("state", stringQuery(reqQuery.state, defaults.state));
-    if (stringQuery(reqQuery.labels))
-        query.set("labels", stringQuery(reqQuery.labels));
-    const sort = stringQuery(reqQuery.sort, defaults.sort ?? "");
-    const direction = stringQuery(reqQuery.direction, defaults.direction ?? "");
+        query.set("state", text(reqQuery.state, defaults.state));
+    const labels = text(reqQuery.labels);
+    if (labels)
+        query.set("labels", labels);
+    const sort = text(reqQuery.sort, defaults.sort ?? "");
+    const direction = text(reqQuery.direction, defaults.direction ?? "");
     if (sort)
         query.set("sort", sort);
     if (direction)
@@ -111,17 +112,17 @@ export function registerGithubRoutes(app, deps) {
     app.get("/api/github/repos", requireAdmin, asyncRoute(async (req, res) => {
         try {
             const query = new URLSearchParams();
-            const visibility = stringQuery(req.query.visibility);
-            const affiliation = stringQuery(req.query.affiliation);
-            const type = stringQuery(req.query.type);
+            const visibility = text(req.query.visibility);
+            const affiliation = text(req.query.affiliation);
+            const type = text(req.query.type);
             if (visibility)
                 query.set("visibility", visibility);
             if (affiliation)
                 query.set("affiliation", affiliation);
             if (type)
                 query.set("type", type);
-            query.set("sort", stringQuery(req.query.sort, "updated"));
-            query.set("direction", stringQuery(req.query.direction, "desc"));
+            query.set("sort", text(req.query.sort, "updated"));
+            query.set("direction", text(req.query.direction, "desc"));
             query.set("per_page", String(integerQuery(req.query.per_page, 30, 1, 100)));
             query.set("page", String(integerQuery(req.query.page, 1, 1, 10_000)));
             const suffix = query.toString();

package/dist/server-local-preview-routes.js

@@ -3,6 +3,11 @@ import { getErrorMessage } from "./error-utils.js";
 import { asyncRoute } from "./express-async.js";
 const MAX_PORT = 65535;
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+/** URL 里可能写 `localhost` / `[::1]`，建立连接前规范成裸主机名。 */
+const NORMALIZED_LOOPBACK_HOSTNAMES = {
+    localhost: "127.0.0.1",
+    "[::1]": "::1",
+};
 /** Headers that identify the original Wand request and must not leak downstream. */
 const FILTERED_REQUEST_HEADERS = new Set([
     "authorization",
@@ -40,7 +45,7 @@ export function parseLocalPreviewTarget(rawHost, rawPort, rawPath) {
         return null;
     const suffix = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
     return {
-        hostname: hostname === "localhost" ? "127.0.0.1" : hostname === "[::1]" ? "::1" : hostname,
+        hostname: NORMALIZED_LOOPBACK_HOSTNAMES[hostname] ?? hostname,
         port,
         path: suffix,
     };

package/dist/server-request.d.ts

@@ -13,8 +13,10 @@ export declare function firstQueryStringValue(value: unknown): string | undefine
 export declare function firstHeaderValue(value: string | string[] | undefined): string | undefined;
 /** 逗号分隔的请求头（如 Forwarded / X-Forwarded-*）取第一段。 */
 export declare function firstHeaderListValue(value: string | string[] | undefined): string | undefined;
-/** 查询参数版 `text()`：显式传 fallback 时返回 fallback 而不是空串。 */
-export declare function stringQuery(value: unknown, fallback?: string): string;
+/** 从 Forwarded 头（`proto=https;host=example.com`）里取指定参数；缺失返回 undefined。 */
+export declare function forwardedParam(header: string | undefined, key: string): string | undefined;
+/** 把 header / URL 里的协议名收敛成 http | https；其余情况返回 undefined。 */
+export declare function normalizeProtocol(value: string | undefined): "http" | "https" | undefined;
 /** 解析范围内整数，越界或非整数回落到 fallback。 */
 export declare function integerQuery(value: unknown, fallback: number, min: number, max: number): number;
 /** 要求请求体是普通对象；数组和 null 都拒绝。 */

package/dist/server-request.js

@@ -28,13 +28,34 @@ export function firstHeaderValue(value) {
 export function firstHeaderListValue(value) {
     return firstHeaderValue(value)?.split(",")[0]?.trim();
 }
-/** 查询参数版 `text()`：显式传 fallback 时返回 fallback 而不是空串。 */
-export function stringQuery(value, fallback = "") {
-    return typeof value === "string" ? value.trim() : fallback;
+/** 从 Forwarded 头（`proto=https;host=example.com`）里取指定参数；缺失返回 undefined。 */
+export function forwardedParam(header, key) {
+    if (!header)
+        return undefined;
+    const targetKey = key.toLowerCase();
+    for (const part of header.split(";")) {
+        const eqIndex = part.indexOf("=");
+        if (eqIndex < 1)
+            continue;
+        if (part.slice(0, eqIndex).trim().toLowerCase() !== targetKey)
+            continue;
+        const value = part.slice(eqIndex + 1).trim();
+        return value.length >= 2 && value.startsWith("\"") && value.endsWith("\"")
+            ? value.slice(1, -1)
+            : value;
+    }
+    return undefined;
+}
+/** 把 header / URL 里的协议名收敛成 http | https；其余情况返回 undefined。 */
+export function normalizeProtocol(value) {
+    const proto = value?.trim().toLowerCase();
+    if (proto === "http" || proto === "https")
+        return proto;
+    return undefined;
 }
 /** 解析范围内整数，越界或非整数回落到 fallback。 */
 export function integerQuery(value, fallback, min, max) {
-    const parsed = Number(stringQuery(value));
+    const parsed = Number(text(value));
     return Number.isInteger(parsed) && parsed >= min && parsed <= max ? parsed : fallback;
 }
 /** 要求请求体是普通对象；数组和 null 都拒绝。 */