patchwarden 1.5.0 → 1.6.1

package/dist/control/routes/process.js

@@ -0,0 +1,487 @@
+/**
+ * Control Center routes — process lifecycle proxy (/api/start-all,
+ * /api/stop-all, /api/restart-all, /api/core/*, /api/direct/*).
+ *
+ * Proxies start/stop/restart actions to scripts/control/manage-patchwarden.ps1
+ * and exposes open-logs-folder. Start/restart actions run a preflight that
+ * verifies the tunnel-client executable and launcher files exist before
+ * launching, so the non-interactive web UI never deadlocks on a missing
+ * dependency. All endpoints are POST routes gated by the control token.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { delimiter, extname, join } from "node:path";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+import { buildChildEnvironment, redactProcessOutput, resolveTrustedExecutable, sanitizeTrustedPath, } from "../../runner/processSecurity.js";
+import { recordEvent } from "../runtime.js";
+import { launchFileManager } from "../fileManager.js";
+import { config, CORE_BASE_URL, DIRECT_BASE_URL, errorMessage, getRuntimeRoot, manageScriptPath, projectRoot, sendJson, } from "../shared.js";
+const MAX_MANAGE_OUTPUT_CHARS = 128 * 1024;
+const MANAGE_ALLOWED_ENVIRONMENT = [
+    "PATCHWARDEN_CONFIG",
+    "PATCHWARDEN_TUNNEL_ID",
+    "PATCHWARDEN_CREDENTIAL_PATH",
+    "PATCHWARDEN_TUNNEL_CLIENT_EXE",
+    "TUNNEL_CLIENT_EXE",
+    "OPENCODE_BIN_DIR",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "NO_PROXY",
+];
+function runManageAction(action, mode) {
+    return new Promise((resolveP, rejectP) => {
+        let child;
+        let exactValues = [];
+        try {
+            const env = buildManageEnvironment();
+            exactValues = manageSensitiveValues(env);
+            const command = resolveTrustedExecutable("powershell.exe", projectRoot, { pathValue: env.PATH });
+            child = spawn(command, ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", manageScriptPath, action, mode, "-Background"], { cwd: projectRoot, windowsHide: true, env });
+        }
+        catch (err) {
+            rejectP(err);
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                child.kill();
+            }
+            catch { /* ignore */ }
+            rejectP(new Error(`manage-patchwarden.ps1 timed out after 60s (action=${action}, mode=${mode})`));
+        }, 60_000);
+        child.stdout.on("data", (d) => {
+            stdout = appendBoundedManageOutput(stdout, d.toString("utf-8"));
+        });
+        child.stderr.on("data", (d) => {
+            stderr = appendBoundedManageOutput(stderr, d.toString("utf-8"));
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            rejectP(err);
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolveP({
+                exitCode: code ?? -1,
+                stdout: redactProcessOutput(stdout, exactValues),
+                stderr: redactProcessOutput(stderr, exactValues),
+            });
+        });
+    });
+}
+export function resolveManageProfiles(mode, action, directEnabled) {
+    if (mode === "core" || mode === "direct")
+        return { selected: [mode], skipped: [] };
+    if ((action === "start" || action === "restart") && !directEnabled)
+        return { selected: ["core"], skipped: ["direct"] };
+    return { selected: ["core", "direct"], skipped: [] };
+}
+function selectedControlModes(mode, action = "status") {
+    return resolveManageProfiles(mode, action, config.enableDirectProfile === true).selected;
+}
+function skippedControlModes(mode, action) {
+    return resolveManageProfiles(mode, action, config.enableDirectProfile === true).skipped;
+}
+function effectiveManageMode(modes) {
+    return modes.length === 1 ? modes[0] : "all";
+}
+function launcherPathForMode(mode) {
+    const launcherName = mode === "direct" ? "Start-PatchWarden-Direct-Tunnel.cmd" : "Start-PatchWarden-Tunnel.cmd";
+    return join(projectRoot, "scripts", "launchers", launcherName);
+}
+function findExecutableOnPath(fileName) {
+    const pathValue = sanitizeTrustedPath(process.env.PATH || "", projectRoot);
+    const extensions = process.platform === "win32"
+        ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)
+        : [""];
+    for (const entry of pathValue.split(delimiter)) {
+        if (!entry)
+            continue;
+        const direct = join(entry, fileName);
+        if (isRegularFile(direct))
+            return direct;
+        if (process.platform === "win32" && !extname(fileName)) {
+            for (const ext of extensions) {
+                const candidate = join(entry, fileName + ext.toLowerCase());
+                if (isRegularFile(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return null;
+}
+function findTunnelClientExecutable() {
+    if (process.env.PATCHWARDEN_CONTROL_FORCE_MISSING_TUNNEL_CLIENT === "1")
+        return null;
+    const configured = config.tunnelClientPath;
+    if (configured && isRegularFile(configured))
+        return configured;
+    const explicit = process.env.PATCHWARDEN_TUNNEL_CLIENT_EXE || process.env.TUNNEL_CLIENT_EXE;
+    if (explicit && isRegularFile(explicit))
+        return explicit;
+    const fromPath = findExecutableOnPath("tunnel-client.exe") ?? findExecutableOnPath("tunnel-client");
+    if (fromPath)
+        return fromPath;
+    const candidates = [
+        process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "PatchWarden", "tunnel-client.exe") : null,
+        process.env.APPDATA ? join(process.env.APPDATA, "tunnel-client", "tunnel-client.exe") : null,
+        join(homedir(), "tunnel-client", "tunnel-client.exe"),
+    ].filter((v) => typeof v === "string" && v.length > 0);
+    for (const candidate of candidates) {
+        if (isRegularFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function buildManageEnvironment() {
+    const agentEnvironmentNames = [...new Set(Object.values(config.agents)
+            .flatMap((agent) => agent.envAllowlist ?? []))];
+    const env = buildChildEnvironment({
+        cwd: projectRoot,
+        allowedNames: [...MANAGE_ALLOWED_ENVIRONMENT, ...agentEnvironmentNames],
+        blockedNames: [config.http?.ownerTokenEnv || "PATCHWARDEN_OWNER_TOKEN"],
+    });
+    const lifecycleNames = new Set(MANAGE_ALLOWED_ENVIRONMENT.map((name) => name.toUpperCase()));
+    const providerOnlyNames = agentEnvironmentNames.filter((name) => !lifecycleNames.has(name.toUpperCase()));
+    env.PATCHWARDEN_AGENT_ENV_ALLOWLIST = providerOnlyNames.join(";");
+    const tunnelClient = findTunnelClientExecutable();
+    if (tunnelClient) {
+        env.PATCHWARDEN_TUNNEL_CLIENT_EXE = tunnelClient;
+        env.TUNNEL_CLIENT_EXE = tunnelClient;
+    }
+    const proxy = config.tunnelProxy;
+    const core = proxy?.core || { mode: "environment" };
+    const direct = proxy?.scope === "separate" ? proxy.direct : core;
+    env.PATCHWARDEN_TUNNEL_PROXY_MODE = core.mode;
+    env.PATCHWARDEN_TUNNEL_PROXY_URL = core.mode === "manual" ? core.url || "" : "";
+    env.PATCHWARDEN_DIRECT_PROXY_MODE = direct.mode;
+    env.PATCHWARDEN_DIRECT_PROXY_URL = direct.mode === "manual" ? direct.url || "" : "";
+    return env;
+}
+// Re-exported so the status route can surface tunnel-client availability in
+// /api/status without duplicating the discovery logic.
+export { findTunnelClientExecutable };
+function profilePathForMode(mode) {
+    if (!process.env.APPDATA)
+        return null;
+    return join(process.env.APPDATA, "tunnel-client", mode === "direct" ? "patchwarden-direct.yaml" : "patchwarden.yaml");
+}
+function credentialPath() {
+    return process.env.APPDATA ? join(process.env.APPDATA, "patchwarden", "control-plane-api-key.dpapi") : null;
+}
+function preflightManageAction(action, mode) {
+    if (action !== "start" && action !== "restart")
+        return null;
+    const selectedModes = selectedControlModes(mode, action);
+    const missingLaunchers = selectedModes
+        .map((m) => ({ mode: m, path: launcherPathForMode(m) }))
+        .filter((entry) => !existsSync(entry.path));
+    const tunnelClient = findTunnelClientExecutable();
+    const missingProfiles = selectedModes
+        .map((m) => ({ mode: m, path: profilePathForMode(m) }))
+        .filter((entry) => !entry.path || !existsSync(entry.path));
+    const savedCredential = credentialPath();
+    const missing = [];
+    if (!tunnelClient)
+        missing.push("tunnel-client.exe");
+    for (const entry of missingLaunchers)
+        missing.push(`${entry.mode} launcher`);
+    for (const entry of missingProfiles)
+        missing.push(`${entry.mode} profile`);
+    if (!savedCredential || !existsSync(savedCredential))
+        missing.push("tunnel runtime credential");
+    if (missing.length === 0)
+        return null;
+    const reasonCode = !tunnelClient
+        ? "tunnel_client_missing"
+        : missingLaunchers.length > 0
+            ? "launcher_missing"
+            : missingProfiles.length > 0
+                ? "tunnel_profile_missing"
+                : "tunnel_credential_missing";
+    return {
+        status: 409,
+        body: {
+            ok: false,
+            action,
+            mode,
+            reason_code: reasonCode,
+            error: "Control Center preflight failed. Start/restart from the Web UI is non-interactive, so required runtime dependencies must be available before launching.",
+            missing,
+            next_steps: [
+                "在桌面设置中自动检测或选择 tunnel-client.exe，也可设置 PATCHWARDEN_TUNNEL_CLIENT_EXE。",
+                "在桌面设置中配置 Tunnel ID 和专用 runtime API key，并完成 doctor 验证。",
+                "确认 scripts/launchers 下的启动器存在，然后重试。",
+            ],
+        },
+    };
+}
+function preflightDirectProfile(action, mode) {
+    if ((action !== "start" && action !== "restart") || mode !== "direct")
+        return null;
+    if (config.enableDirectProfile === true)
+        return null;
+    return {
+        status: 409,
+        body: {
+            ok: false,
+            action,
+            mode,
+            reason_code: "direct_profile_disabled",
+            error: "Direct profile 尚未启用。请先在桌面设置中启用 Direct，再启动对应隧道。",
+            next_steps: ["打开 设置 -> MCP 与隧道", "启用 Direct profile 并保存", "重新启动 Direct"],
+        },
+    };
+}
+function readRuntimeState(mode, fileName) {
+    try {
+        return JSON.parse(readFileSync(join(getRuntimeRoot(mode === "direct"), fileName), "utf8").replace(/^\uFEFF/, ""));
+    }
+    catch {
+        return null;
+    }
+}
+function readRuntimeLog(mode, fileName) {
+    try {
+        const value = readFileSync(join(getRuntimeRoot(mode === "direct"), fileName), "utf8");
+        return value.length > 64_000 ? value.slice(-64_000) : value;
+    }
+    catch {
+        return "";
+    }
+}
+export function classifySupervisorFailure(diagnosticText) {
+    if (/unsupported_country_region_territory|unsupported.{0,30}(country|region|territory)/i.test(diagnosticText))
+        return "unsupported_region";
+    if (/\b(401|403)\b|unauthori[sz]ed|invalid.{0,30}(api.?key|credential)|api.?key.{0,30}(invalid|missing)/i.test(diagnosticText))
+        return "auth_failed";
+    if (/proxy|ECONNREFUSED|ENETUNREACH|ETIMEDOUT|could not resolve|name resolution|connection (failed|refused)/i.test(diagnosticText))
+        return "proxy_unreachable";
+    if (/tool manifest preflight|tool_manifest_(check_failed|invalid)|mcp-manifest-check/i.test(diagnosticText))
+        return "tool_manifest_check_failed";
+    if (/spawn EPERM|access (is )?denied|permission denied/i.test(diagnosticText))
+        return "supervisor_permission_denied";
+    if (/watcher.{0,40}(failed|unhealthy|missing|exited)/i.test(diagnosticText))
+        return "watcher_unhealthy";
+    if (/profile.{0,30}(missing|invalid)|config.{0,30}(missing|invalid)|launcher.{0,30}(missing|not found)/i.test(diagnosticText))
+        return "config_error";
+    return "supervisor_exited";
+}
+function processIsAlive(pid) {
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function inspectSupervisor(mode, startedAt) {
+    const state = readRuntimeState(mode, "supervisor-status.json");
+    const checkedAt = typeof state?.checked_at === "string" ? Date.parse(state.checked_at) : 0;
+    const fresh = Number.isFinite(checkedAt) && checkedAt >= startedAt - 2000;
+    if (!fresh)
+        return { terminal: false, reasonCode: null };
+    const explicitlyFailed = state?.status === "failed";
+    if (!explicitlyFailed && processIsAlive(state?.pid))
+        return { terminal: false, reasonCode: null };
+    const diagnostics = `${readRuntimeLog(mode, "supervisor.stderr.log")}\n${readRuntimeLog(mode, "supervisor.stdout.log")}`;
+    const recordedReason = typeof state?.reason_code === "string" ? state.reason_code : null;
+    return { terminal: true, reasonCode: recordedReason || classifySupervisorFailure(diagnostics) };
+}
+async function probeReady(baseUrl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1500);
+    try {
+        const response = await fetch(`${baseUrl}/readyz`, { signal: controller.signal, cache: "no-store" });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function inspectStartup(mode, startedAt) {
+    const tunnel = readRuntimeState(mode, "tunnel-status.json");
+    const checkedAt = typeof tunnel?.checked_at === "string" ? Date.parse(tunnel.checked_at) : 0;
+    const fresh = Number.isFinite(checkedAt) && checkedAt >= startedAt - 2000;
+    const endpointReady = await probeReady(mode === "direct" ? DIRECT_BASE_URL : CORE_BASE_URL);
+    const watcher = mode === "core" ? readRuntimeState(mode, "watcher-status.json") : null;
+    const watcherReady = mode === "direct" || watcher?.status === "healthy";
+    const ready = endpointReady && tunnel?.ready !== false && watcherReady;
+    const terminalStatuses = new Set(["failed", "error", "stopped", "restart_limit_reached"]);
+    const tunnelTerminal = fresh && terminalStatuses.has(String(tunnel?.status || "")) && tunnel?.reason_code !== "stopped_by_manager";
+    const supervisor = inspectSupervisor(mode, startedAt);
+    const terminal = tunnelTerminal || supervisor.terminal;
+    const reasonCode = tunnelTerminal
+        ? (typeof tunnel?.reason_code === "string" ? tunnel.reason_code : "startup_failed")
+        : supervisor.reasonCode;
+    return {
+        mode,
+        ready,
+        endpoint_ready: endpointReady,
+        watcher_ready: watcherReady,
+        status: tunnel?.status || "starting",
+        reason_code: reasonCode,
+        error: tunnel?.last_error || null,
+        terminal,
+    };
+}
+async function waitForStartup(modes, startedAt) {
+    const configured = Number(process.env.PATCHWARDEN_CONTROL_START_TIMEOUT_MS || "30000");
+    const timeoutMs = Number.isFinite(configured) ? Math.min(Math.max(configured, 1000), 120000) : 30000;
+    const deadline = Date.now() + timeoutMs;
+    let profiles = [];
+    while (Date.now() < deadline) {
+        profiles = await Promise.all(modes.map((mode) => inspectStartup(mode, startedAt)));
+        if (profiles.every((profile) => profile.ready === true))
+            return { ok: true, profiles };
+        const failed = profiles.find((profile) => profile.terminal === true);
+        if (failed) {
+            const reasonCode = typeof failed.reason_code === "string" ? failed.reason_code : "supervisor_exited";
+            return { ok: false, profiles, reasonCode };
+        }
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 500));
+    }
+    profiles = await Promise.all(modes.map((mode) => inspectStartup(mode, startedAt)));
+    return { ok: false, profiles, reasonCode: "startup_timeout" };
+}
+export async function handleManageAction(res, action, mode) {
+    try {
+        const directPreflight = preflightDirectProfile(action, mode);
+        if (directPreflight) {
+            recordEvent("manage." + mode + "." + action + ".profile_disabled", { reason_code: "direct_profile_disabled" });
+            sendJson(res, directPreflight.status, directPreflight.body);
+            return;
+        }
+        const selectedModes = selectedControlModes(mode, action);
+        const skippedModes = skippedControlModes(mode, action);
+        const managedMode = effectiveManageMode(selectedModes);
+        const preflight = preflightManageAction(action, mode);
+        if (preflight) {
+            recordEvent("manage." + mode + "." + action + ".preflight_failed", {
+                missing: preflight.body.missing,
+            });
+            sendJson(res, preflight.status, {
+                ...preflight.body,
+                started_profiles: [],
+                skipped_profiles: skippedModes,
+            });
+            return;
+        }
+        const startedAt = Date.now();
+        const result = await runManageAction(action, managedMode);
+        if (result.exitCode !== 0) {
+            recordEvent("manage." + mode + "." + action, { exit_code: result.exitCode, ok: false });
+            sendJson(res, 500, {
+                ok: false,
+                action,
+                mode,
+                started_profiles: [],
+                skipped_profiles: skippedModes,
+                reason_code: "manager_failed",
+                error: result.stderr.trim() || result.stdout.trim() || `manage-patchwarden.ps1 exited with code ${result.exitCode}`,
+            });
+            return;
+        }
+        if (action === "start" || action === "restart") {
+            const startup = await waitForStartup(selectedModes, startedAt);
+            if (!startup.ok) {
+                const timeout = startup.reasonCode === "startup_timeout";
+                recordEvent("manage." + mode + "." + action + ".not_ready", { reason_code: startup.reasonCode, profiles: startup.profiles });
+                sendJson(res, timeout ? 504 : 502, {
+                    ok: false,
+                    action,
+                    mode,
+                    started_profiles: selectedModes,
+                    skipped_profiles: skippedModes,
+                    reason_code: startup.reasonCode,
+                    error: timeout
+                        ? "启动命令已执行，但服务未在等待时间内通过就绪检查。"
+                        : "隧道 supervisor 在服务就绪前退出。",
+                    profiles: startup.profiles,
+                    next_steps: ["检查设置中的 tunnel-client 与代理", "运行健康检查", "查看本次 Core / Direct 日志"],
+                });
+                return;
+            }
+        }
+        recordEvent("manage." + mode + "." + action, {
+            exit_code: result.exitCode,
+            ok: result.exitCode === 0,
+        });
+        sendJson(res, 200, {
+            ok: result.exitCode === 0,
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            verified: action === "start" || action === "restart",
+            started_profiles: action === "start" || action === "restart" ? selectedModes : [],
+            skipped_profiles: skippedModes,
+            reason_code: skippedModes.length > 0 ? "direct_profile_disabled" : null,
+        });
+    }
+    catch (err) {
+        recordEvent("manage." + mode + "." + action + ".failed", { error: errorMessage(err) });
+        sendJson(res, 500, { error: errorMessage(err) });
+    }
+}
+export function handleOpenLogsFolder(res) {
+    try {
+        const target = getRuntimeRoot(false);
+        launchFileManager(target, projectRoot);
+        sendJson(res, 200, { ok: true, path: target });
+    }
+    catch (err) {
+        sendJson(res, 500, { error: errorMessage(err) });
+    }
+}
+function appendBoundedManageOutput(current, next) {
+    if (current.length >= MAX_MANAGE_OUTPUT_CHARS)
+        return current;
+    return current + next.slice(0, MAX_MANAGE_OUTPUT_CHARS - current.length);
+}
+function manageSensitiveValues(env) {
+    const agentEnvironmentValues = Object.values(config.agents)
+        .flatMap((agent) => agent.envAllowlist ?? [])
+        .map((name) => findEnvironmentValue(env, name));
+    const values = [
+        env.HTTP_PROXY,
+        env.HTTPS_PROXY,
+        env.ALL_PROXY,
+        env.PATCHWARDEN_TUNNEL_PROXY_URL,
+        env.PATCHWARDEN_DIRECT_PROXY_URL,
+        ...agentEnvironmentValues,
+    ].filter((value) => typeof value === "string" && Buffer.byteLength(value, "utf-8") >= 8);
+    return [...new Set(values)].sort((left, right) => right.length - left.length);
+}
+function findEnvironmentValue(env, name) {
+    if (process.platform !== "win32")
+        return env[name];
+    const match = Object.keys(env).find((key) => key.toUpperCase() === name.toUpperCase());
+    return match ? env[match] : undefined;
+}
+function isRegularFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/control/routes/sessions.d.ts

@@ -0,0 +1,30 @@
+import { type ServerResponse } from "node:http";
+export interface DirectSessionFilters {
+    state?: "active" | "archive" | "finalized" | "audited" | "expired";
+    repo_path?: string;
+    date_from?: string;
+    date_to?: string;
+    limit?: number;
+    cursor?: string;
+}
+export declare function handleDirectSessions(res: ServerResponse, filters?: DirectSessionFilters): void;
+export declare function handleDirectSessionDetail(res: ServerResponse, sessionId: string): void;
+export declare function handleDirectSessionSafeSummary(res: ServerResponse, sessionId: string): void;
+/**
+ * Finalize a direct session via safeFinalizeDirectSession. Returns the safe
+ * summary on success, or { error } on failure with HTTP 200 (fault tolerance:
+ * the UI always gets a JSON body it can render).
+ */
+export declare function handleDirectSessionFinalize(res: ServerResponse, sessionId: string): Promise<void>;
+/**
+ * Audit a direct session via safeAuditDirectSession. Returns the safe audit
+ * result on success, or { error } on failure (HTTP 200 for fault tolerance).
+ */
+export declare function handleDirectSessionAudit(res: ServerResponse, sessionId: string): void;
+/**
+ * Hide a direct session from the dashboard list. The session itself is NOT
+ * deleted or modified — only the control-center's local
+ * hidden-direct-session-ids.json state file is updated. Requires control token
+ * (enforced by the POST router).
+ */
+export declare function handleDirectSessionHide(res: ServerResponse, sessionId: string): void;